#Database

To store settings and other data for your Addon, you will need access to a database. MercuryCMS provides an API to store data in a Mongo document database for your Addon. See the Mongo Documentation for information on available queries and options.

#Listing Collections

// use axios
let response = await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/database/listcollections`)
console.log(response.data.collections) // ['settings', 'vehicle']

// use static-cms-addon
import cms from 'static-cms-addon'
let collections = await cms.database.listCollections()
console.log(collections) // ['settings', 'vehicle']

#Dropping Collections

// use axios
let response = await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/database/vehicle/drop`)

// use static-cms-addon
import cms from 'static-cms-addon'
await cms.database.collection('vehicle').drop()

#Inserting Documents

You can use insertOne and insertMany to insert documents into the database. You can specify a doc or docs and options. The HTTP API will return the insertedId or insertedIds. static-cms-addon will return the doc or docs object and update each doc with its appropriate _id.

// use axios
let response = await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/database/collection/vehicle/insertone`, {
  doc: {make: 'Nissan', model: 'Sentra'},
})
console.log(response.data.insertedId) // '639ab39b7f5fb8a394042762'

// use static-cms-addon
import cms from 'static-cms-addon'
let vehicle = await cms.database.collection('vehicle').insertOne({make: 'Nissan', model: 'Sentra'})
console.log(vehicle) // {_id: '639ab39b7f5fb8a394042762', make: 'Nissan', model: 'Sentra'}

// use axios
let response = await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/database/collection/vehicle/insertmany`, {
  docs: [
    {make: 'Nissan', model: 'Sentra'},
    {make: 'Nissan', model: 'Altima'},
    {make: 'Honda', model: 'Civic'},
    {make: 'Honda', model: 'Accord'},
  ]
})
console.log(response.data.insertedIds) // ['639ab39b7f5fb8a394042762', '639ab39b7f5fb8a394042763', '639ab39b7f5fb8a394042764', '639ab39b7f5fb8a394042765']

// use static-cms-addon
import cms from 'static-cms-addon'
let vehicles = await cms.database.collection('vehicle').insertMany([
  {make: 'Nissan', model: 'Sentra'},
  {make: 'Nissan', model: 'Altima'},
  {make: 'Honda', model: 'Civic'},
  {make: 'Honda', model: 'Accord'},
])
console.log(vehicles)
// [
//   {_id: '639ab39b7f5fb8a394042762', make: 'Nissan', model: 'Sentra'},
//   {_id: '639ab39b7f5fb8a394042763', make: 'Nissan', model: 'Altima'},
//   {_id: '639ab39b7f5fb8a394042763', make: 'Honda', model: 'Civic'},
//   {_id: '639ab39b7f5fb8a394042763', make: 'Honda', model: 'Accord'},
// ]

#Finding Documents

You can use findOne and findMany to fetch documents from the database. You can specify a query and options. The options allows you to specify projections for the data (see the last example below). findOne returns null if no matching document is found, while findMany returns an empty array.

// use axios
let response = await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/database/collection/vehicle/findone`, {
  query: {make: 'Nissan'},
})
console.log(response.data.doc) // {_id: '639ab39b7f5fb8a394042762', make: 'Nissan', model: 'Sentra'}

// use static-cms-addon
import cms from 'static-cms-addon'
let vehicle = await cms.database.collection('vehicle').findOne({make: 'Nissan'})
console.log(vehicle) // {_id: '639ab39b7f5fb8a394042762', make: 'Nissan', model: 'Sentra'}

// use axios
let response = await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/database/collection/vehicle/findmany`, {
  query: {make: 'Nissan'},
})
console.log(response.data.docs) // [{_id: '639ab39b7f5fb8a394042762', make: 'Nissan', model: 'Sentra'}, {_id: '639ab39b7f5fb8a394042763', make: 'Nissan', model: 'Altima'}]

// use static-cms-addon
import cms from 'static-cms-addon'
let vehicles = await cms.database.collection('vehicle').findMany({make: 'Nissan'})
console.log(vehicles) // [{_id: '639ab39b7f5fb8a394042762', make: 'Nissan', model: 'Sentra'}, {_id: '639ab39b7f5fb8a394042763', make: 'Nissan', model: 'Altima'}]

// use axios
let response = await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/database/collection/vehicle/findmany`, {
  query: {make: 'Nissan'},
  options: {_id: false, model: true},
})
console.log(response.data.docs) // [{model: 'Sentra'}, {model: 'Altima'}]

// use static-cms-addon
import cms from 'static-cms-addon'
let vehicles = await cms.database.collection('vehicle').findMany({make: 'Nissan'}, {_id: false, model: true})
console.log(vehicles) // [{model: 'Sentra'}, {model: 'Altima'}]

#Deleting Documents

You can use deleteOne and deleteMany to delete documents from the database. The return value is a count of deleted documents.

// use axios
let response = await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/database/collection/vehicle/deleteone`, {
  query: {make: 'Nissan'},
})
console.log(response.data.count) // 1

// use static-cms-addon
import cms from 'static-cms-addon'
let deletedCount = await cms.database.collection('vehicle').deleteOne({make: 'Nissan'})
console.log(deletedCount) // 1

// use axios
let response = await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/database/collection/vehicle/deletemany`, {
  query: {make: 'Nissan'},
})
console.log(response.data.count) // 2

// use static-cms-addon
import cms from 'static-cms-addon'
let deletedCount = await cms.database.collection('vehicle').deleteMany({make: 'Nissan'})
console.log(deletedCount) // 2

#Updating Documents

You can use updateOne and updateMany to update documents. You must specify a query for which documents to update as well as an update doc with update directives such as $set. You can also pass options.

// use axios
await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/database/collection/vehicle/updateone`, {
  query: {make: 'Nissan'},
  doc: {$set: {year: 1994}},
})

// use static-cms-addon
import cms from 'static-cms-addon'
await cms.database.collection('vehicle').updateOne({make: 'Nissan'}, {$set: {year: 1994}})

// use axios
let response = await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/database/collection/vehicle/updatemany`, {
  query: {make: 'Nissan'},
  doc: {$set: {year: 1994}},
})

// use static-cms-addon
import cms from 'static-cms-addon'
await cms.database.collection('vehicle').updateMany({make: 'Nissan'}, {$set: {year: 1994}})

#Replacing Documents

You can use replaceOne to replace a document. You must specify a query for which document to replace as well as a new doc to replace it with.

// use axios
await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/database/collection/vehicle/replaceone`, {
  query: {_id: {$oid: '639ab39b7f5fb8a394042762'}},
  doc: {make: 'Nissan', model: 'Maxima'},
})

// use static-cms-addon
import cms from 'static-cms-addon'
await cms.database.collection('vehicle').replaceOne({_id: {$oid: '639ab39b7f5fb8a394042762'}}, {make: 'Nissan', model: 'Maxima'})

#Counting Documents

To get a simple count of documents rather than the documents themselves, you can use count. Do not specify a query if you want a count of all documents in the collection.

// use axios
let response = await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/database/collection/vehicle/count`, {
  query: {make: 'Nissan'},
})
console.log(response.data.count) // 2

// use static-cms-addon
import cms from 'static-cms-addon'
let count = await cms.database.collection('vehicle').count({make: 'Nissan'})
console.log(count) // 2

#$oid Support

Note that because you are sending requests encoded as JSON, you cannot use ObjectID() for _id fields. You can instead use $oid. For example:

// does not work. _id is a bson value
let vehicle = await cms.database.collection('vehicle').findOne({_id: '639ab39b7f5fb8a394042762'})

// works. addon database api will convert to a bson value
let vehicle = await cms.database.collection('vehicle').findOne({_id: {$oid: '639ab39b7f5fb8a394042762'}})

#Templating Database Data

It's common to want to provide some of your Addon's database data such as its settings to the Build for Templating. To do this, see Events, specifically the buildStarted Event.