7.0-database-abstraction.md

Database Abstraction

To provide the MBEE Community users with greater modularity, a database abstraction layer has been created. This layer defines a list of functions and classes which are required to be implemented in a database strategy. If these functions and classes are properly implemented, swapping databases should be as simple as specifying the strategy of choice in the running config.

Strategy Requirements

Each strategy must implement the list of classes and functions below. If ANY of the functions or classes are not defined, a critical error will be logged to the console, and the process will be terminated.

Functions

• connect()

  Opens a connection to the database. The connection should persist until the disconnect() function is called. Returns an empty promise.

• disconnect()

  Closes a connection to the database. Returns an empty promise.

• clear()

  Completely wipes the entire database. All collections, documents, and indexes should be deleted. Used in the 000 and 999 tests. NOTE: These tests should never be run in production. Returns an empty promise.

• sanitize(data)

  Sanitizes database specific key words/characters from user input. Data passed into this function will be used in queries and inserted into the database, so it is important to sanitize against injections or access to incorrect data. Returns the sanitized data.

Schema Class

A schema defines a template for each document inserted into the database, as well as any static methods, indexes, validators, or virtuals which may exist.

• constructor(definition, options)

  Creates an instance of a Schema. The definition contains the base schema, which details the properties of the document. Each property is an object, and has additional parameters which detail that property. The parameters can include the type, validator functions, defaults, references to other models, enums and booleans for specifying indexes, uniqueness and whether or not the property is required.

• add(obj, prefix)

  Appends an object or schema to the current schema.

• plugin(cb, options)

  Calls a callback function on the schema. Currently only used to append a schema containing shared properties to every schema.

• index(fields, options)

  Adds an index to the schema. Can add compound or text indexes, depending on the content of fields. This is one of two ways to define an index, where the other is supplying the parameter index: true on a property in the Schema constructor.

• virtual(name, options)

  Adds a virtual property to the Schema. Virtuals are fields, which are NOT stored in the database, and are calculated after the document is found. Often times virtuals reference other documents and will require an additional find operation to populate. For example, the virtual field projects on the organization schema returns all projects which the organization contains.

• static(name, fn)

  Adds a static function to the schema, which will later become a static function on the model.

Model Class

A model is used to directly manipulate the database, as well as create any new documents or indexes. Models are the core pieces of MBEE, and are exported from all of the files in app/models. Models define functions which perform certain CRUD operations on the database, as well as any methods used for maintaining the database (i.e. creating indexes).

• constructor(name, schema, collection)

  Creates an instance of a Model from the supplied Schema. Should create the collection/table in the database, along with any indexes which were specified. Returns an instance of a Model. NOTE: the constructor is not asynchronous. Any asynchronous operations needed to be performed should be added to the init() function.

• init()

  An asynchronous function run on startup of MBEE. Used to perform any async operations required for model initialization which could not be performed in the Model constructor.

• bulkWrite(ops, options, cb)

  Performs a large write operation on the database, and allows for multiple different operations to occur, including: insertOne, updateOne, deleteOne, and deleteMany. Accepts an array of objects, where each object defines one of the above operations, and any additional parameters to perform that operation. Should return an object containing the results of the operations, including the number of each type and overall success.

• countDocuments(filter, cb)

  Returns the number of documents which match the filter.

• deleteIndex(name)

  Deletes an index name from the collection/table.

• deleteMany(conditions, options, cb)

  Delete all documents from the collection/table which match the provided conditions.

• find(filter, projection, options, cb)

  Finds multiple documents which match the filter. Only fields specified in projection are returned; if null all fields are returned. Supported options are sort (order of returned documents), limit, skip (pagination), and populate (virtuals or references only). Find is one of the most used methods in the core framework.

• findOne(filter, projection, options, cb)

  Similar to find, but only returns either a single found document or null. Only supports the option populate.

• getIndexes()

  Returns an array of all existing indexes on the collection/table.

• insertMany(docs, options, cb)

  Inserts the array of documents docs into the database. Supports the option skipValidation, which optionally allows the caller to skip validating documents. If this option is not provided or is false, all documents should be validated before inserting into the database.

• updateMany(filter, doc, options, cb)

  Updates all documents which match the filter, with the changes provided in the doc parameter.

• updateOne(filter, doc, options, cb)

  Updates a single document that matches the filter with the changes provided in the doc parameter.

Store Class

The Store class is used for session management/storage alongside the library express-session. The Store class MUST extend the built in EventEmitter class, as many of the built in functions are used by express-session. The store should be able to create, retrieve and delete sessions in your database of choice. There are many supported libraries which handle the store for popular databases. See the link above for a list of those libraries.

• constructor(options)

  Creates an instance of the Store class.

• all(cb)

  An optional function which retrieves all sessions in the store.

• destory(sid, cb)

  A required function which deletes a session matching the parameter sid.

• clear(cb)

  An optional function which deletes all sessions in the store.

• length(cb)

  An optional function which returns the number of sessions in the store.

• get(sid, cb)

  A required function which gets a session matching the parameter sid.

• set(sid, session, cb)

  A required function which creates a session if it doesn't exist, otherwise updates it.

• touch(sid, session, cb)

  An optional (but recommended) function which resets a session's idle timer if it is queued for destruction.

Migrations

It is possible to add database specific migration scripts which will be run alongside generic migrations scripts during node mbee migrate. Database specific migration scripts are intended to only be written when content in that migration script cannot be run by other databases. For example, MongoDB previously stored special ObjectIDs as the _id, instead of strings. The migration to change to strings cannot be run by other databases, because of the special ObjectID type, unique to MongoDB.

Each migration script written should be named after the version which the migration will be run on. For example, if the current version is 0.10.0 and the next version is 0.10.1, the migration script would be titled 0.10.1.js. This database specific migration script should be stored in a migrations folder under the database's folder in db (ex: app/db/mongoose-mongodb-strategy/migrations/0.10.1.js.) These migration scripts will run after any generic migration scripts have run. If there is a 0.10.1.js migration script for the entire system this script will run first, followed by the database specific migration. Every migration function needs to define and export one function called up, which performs the actual migration. For example migration scripts, please view any of the scripts in scripts/migrations.