Database

Your Mirage server has a database which you can interact with in your route handlers. You’ll typically use models to interact with your database data, but you can always reach into the db directly in the event you want more control.

Access the db from your route handlers via schema.db.

# db.createCollection(name)

Add an empty collection named name to your database. Typically you won’t need to do this yourself, since collections are automatically created for any models you have defined.

# db.collection

Returns the collection attached to the database object.

For example if you had the following data file named mirage/fixtures/contacts.js

export default [
  {id: 1, name: 'Zelda'},
  {id: 2, name: 'Link'}
];

then db.contacts would return this array.

# db.collection.insert(data)

Inserts data into the collection. data can be a single object or an array of objects. Returns the inserted record.

// Insert a single record
let link = db.users.insert({name: 'Link', age: 173});

link;  // {id: 1, name: 'Link', age: 173}

// Insert an array
let users = db.users.insert([
  {name: 'Zelda', age: 142},
  {name: 'Epona', age: 58},
]);

users;  // [{id: 2, name: 'Zelda', age: 142}, {id: 3, name: 'Epona', age: 58}]

# db.collection.find(ids)

Returns a single record from the collection if ids is a single id, or an array of records if ids is an array of ids. Note each id can be an int or a string, but integer ids as strings (e.g. the string “1”) will be treated as integers.

/* 
  Given users = [{id: 1, name: 'Link'}, {id: 2, name: 'Zelda'}]
*/
db.users.find(1);      // {id: 1, name: 'Link'}
db.users.find([1, 2]); // [{id: 1, name: 'Link'}, {id: 2, name: 'Zelda'}]

# db.collection.findBy(query)

Returns the first model from collection that matches the key-value pairs in the query object. Note that a string comparison is used. query is a POJO.

/* 
  Given users = [{id: 1, name: 'Link'}, {id: 2, name: 'Zelda'}]
*/
db.users.findBy({name: 'Link'}); // {id: 1, name: 'Link'}

# db.collection.where(query)

Returns an array of models from collection that match the key-value pairs in the query object. Note that a string comparison is used. query is normally a POJO but can also be a function (see PR #379 for details

/* 
  Given users = [{id: 1, name: 'Link'}, {id: 2, name: 'Zelda'}]
*/

db.users.where({name: 'Zelda'}); // [{id: 2, name: 'Zelda'}]

# db.collection.update(attrs) or db.collection.update(target, attrs)

Updates one or more records in collection.

If attrs is the only arg present, updates all records in the collection according to the key-value pairs in attrs.

If target is present, restricts updates to those that match target. If target is a number or string, finds a single record whose id is target to update. If target is a POJO, queries collection for records that match the key-value pairs in target, and updates their attrs.

Returns the updated record or records.

/* 
  Given users = [
    {id: 1, name: 'Link'},
    {id: 2, name: 'Zelda'}
  ]
*/

db.users.update({name: 'Ganon'}); // db.users = [{id: 1, name: 'Ganon'}, {id: 2, name: 'Ganon'}]
db.users.update(1, {name: 'Young Link'}); // db.users = [{id: 1, name: 'Young Link'}, {id: 2, name: 'Zelda'}]
db.users.update({name: 'Link'}, {name: 'Epona'}); // db.users = [{id: 1, name: 'Epona'}, {id: 2, name: 'Zelda'}]

# db.collection.remove(target)

Removes one or more records in collection.

If target is undefined, removes all records. If target is a number or string, removes a single record using target as id. If target is a POJO, queries collection for records that match the key-value pairs in target, and removes them from the collection.

/* 
  Given users = [
    {id: 1, name: 'Link'},
    {id: 2, name: 'Zelda'}
  ]
*/

db.users.remove(); // db.users = []
db.users.remove(1); // db.users = [{id: 2, name: 'Zelda'}]
db.users.remove({name: 'Zelda'}); // db.users = [{id: 1, name: 'Link'}]

# db.collection.firstOrCreate(query, attributesForCreate)

Finds the first record matching the provided query in collection, or creates a new record using a merge of the query and optional attributesForCreate. Often times you may have a pattern like the following in your API stub:

/* 
  Given users = [
    {id: 1, name: 'Link'},
    {id: 2, name: 'Zelda'}
  ]
*/
let records = db.users.where({ name: 'Link' });
let record;

if (records.length > 0) {
  record = records[0];
} else {
  record = db.users.insert({ name: 'Link' });
}

You can now replace this with the following:

let record = db.users.firstOrCreate({ name: 'Link' });

An extended example using attributesForCreate:

let record = db.users.firstOrCreate({ name: 'Link' }, { evil: false });