chpr-mongodb

MongoDB connector

MIGRATIONS GUIDELINES

• Requirements
• Configuration
  • Overall configuration
  • Database connection configuration
• Instanciation
  • Simple connection
  • Models definitions
  • Migrations definitions
• Migrate to version chpr-mongodb 2
• Installation
• Tests
• /!\ Deprecation warnings
  • migrate('update', 'init')
  • migrate('update') with no second parameter

This library is a wrapper on node-mongodb-native. The original documentation is available here. The purpose is to help having robust connection on MongoDb databases potentially on multiple databases, with models definitions and migration patterns.

Requirements

• async / await is required (Node.js 7+)
• MongoDB 3.2+ is required to use the document validation feature

Configuration

Overall configuration

The connector configuration object must look like this:

{
  databases: [
    // Database configuration
  ]
}

By default, all indexes are created in background. You can change this behavior by setting the property ensureIndexInBackground to false.

Database connection configuration

If you want to connect a specific database, please use the following object format:

{
  name: 'riders', // Database name
  url: 'mongodb://localhost:27017/riders', // Database connection string
  options: {
    // MongoDb connection options
  }
}

The options properties are documented in the official documentation.

Instanciation

Simple connection

const { MongoDbConnector } = require('chpr-mongodb');

async function start() {
  const client = new MongoDbConnector({
    databases: [{
      name: 'test',
      url: 'mongodb://localhost:27017/test'
    }]
  });

  await client.connect();
}

async function stop() {
  await client.disconnect();
}

Models definitions

Please have a look to the example.

const { MongoDbConnector } = require('chpr-mongodb');

async function start() {
  const client = new MongoDbConnector({
    databases: [{
      name: 'test',
      url: 'mongodb://localhost:27017/test'
    }]
  }, {
    users: {
      DATABASE: 'test',
      COLLECTION: 'users'
    }
  });

  await client.connect();

  // Example of models initialization (tests only):
  await client.migrate('update', 'from-models');
}

async function stop() {
  await client.disconnect();
}

Migrations definitions

Please have a look to the migrations documentation.

// migrations/index.js
const addUniqueIndexExample20171129 = require('./1.add-unique-index-example.js');

module.exports = new Map([
  ['1', addUniqueIndexExample20171129]
]);

// migrate.js
const { MongoDbConnector } = require('chpr-mongodb');

const migrations = require('./migrations');

async function start() {
  const client = new MongoDbConnector({
    databases: [{
      name: 'test',
      url: 'mongodb://localhost:27017/test'
    }]
  }, {
    users: {
      DATABASE: 'test',
      COLLECTION: 'users'
    }
  }, migrations);

  await client.connect();

  // Example of unique migration call (tests only):
  await client.migrate('update', '1');
}

async function stop() {
  await client.disconnect();
}

Installation

nvm i

npm install

Tests

# Run the mocha tests only
npm run mocha

# Run the eslint only
npm run eslint

# Run the coverage withuut eslint
npm run mocha

# Run all the tests
npm test

/!\ Deprecation warnings

migrate('update', 'init')

After 2018-03-01, no guarantee about its support is given

The keyword init has been deprecated in favor of from-models. It was unclear that this migration was special and was applying for a test purpose only migration of models from the models definitions themselves. The replacement will be:

migrate('update', 'from-models')

Or even more explicit:

applyModels('update')

migrate('update') with no second parameter

After 2018-03-01, no guarantee about its support is given

The absence of second parameter to the migrate method was unclear that it will apply all migrations from the very first one to the last one. The keyword all is prefered until now. The following syntax will apply the same result:

migrate('update', 'all')

Or even more explicit:

applyAllMigrations('update')