arangrate2

Arangrate2 is a flexible ArangoDB migration package for node.js.

It is a fork of arangrate with a few changes, most importantly catering more towards usage from inside existing code instead of targeting CLI, allowing more flexible use as module without tying the database connection info to environment variables.

By David Dyess II and David Trapp.

Install

npm install arangrate2 --save

Usage

src/migrate.js

import { fileURLToPath } from 'url'
import Arangrate from 'arangrate2'

const arangrate = new Arangrate({
  database: { // Can come from some configuration file, or can be a precreated client instance
    url: 'http://localhost:8529',
    auth: {
      username: 'root',
      password: 'root'
    },
    databaseName: 'mydb'
  },
  path: fileURLToPath(new URL('../migrations', import.meta.url)),
  collection: 'migrations'
})

export async function migrate (target) {
  await arangrate.migrate(target)
}

You have to call your migrate script yourself as needed.

Options

• database: A database connection info object passed to arangojs' Database constructor, or optionally a precreated database client instance.
• path: The location of your migrations, relative to the main entry point (required).
• (optional) collection: The database collection used to track migrations. Default: migrations

Migrations

Arangrate2 has a peer dependency to the arangojs package to handle connections and also exports a few helper functions:

• db
  • Database instance
• aql
  • Template strings from arangojs
• createCollection
• createEdgeCollection
• dropCollection

Anything that can be done with the Database class from arangojs can be done with the db object here.

Usage of the helper functions is demonstrated in the examples below.

Arangrate2 provides flexibility for your migrations. Migrations will be stored as determined in the migration script you created. You are also allowed to choose the naming convention for your migrations, with the following format:

• [indentifier].do.[title].js

Reversions use .undo. instead of .do., but should use the same identifier and title in the following format:

• [identifier].undo.[title].js

The identifier should provide an alphabetical or numerical order, such as 0001, 0002, 0003...

The title is displayed in the console log and stored in the migrations collection for reference later.

I recommend using a logger in the migration scripts arangrate2 uses the logade npm package for logging, so that is what is used in the examples.

The only requirement for arangrate to run the script is for it to have a default export: export default async fuction setup() { ... } to handle the migration. You write the queries or use the arangrate helpers to perform the migration. Arangrate2 will execute the setup() function to perform the migration and record it in the database. If the function returns false, the operation will not be recorded and will thereby run again next time.

Example - 0001.do.initial.js

import { db, createCollection, createEdgeCollection } from 'arangrate2'
import { getLogger } from 'logade'

export default async function setup () {
  const log = getLogger('0001')

  log.info('Migrating')

  const documentCollections = [
    'notifications',
    'profiles',
    'sessions',
    'users'
  ]
  const edgeCollections = ['hasPrivilege', 'hasRole']

  for (const localName of documentCollections) {
    await createCollection({ name: localName })
  }

  for (const localName of edgeCollections) {
    await createEdgeCollection({ name: localName })
  }

  /**
   * Sessions Indexes
   */
  const sessions = await db.collection('sessions')

  await sessions.ensureIndex({
    type: 'hash',
    unique: false,
    fields: ['uid']
  })

  await sessions.ensureIndex({
    type: 'hash',
    unique: false,
    fields: ['expires']
  })

  /**
   * Users Indexes
   */
  const users = await db.collection('users')

  await users.ensureIndex({
    type: 'hash',
    unique: true,
    fields: ['username']
  })

  await users.ensureIndex({
    type: 'hash',
    unique: true,
    fields: ['email']
  })

  /**
   * Notifications
   */
  const notifications = await db.collection('notifications')

  await notifications.ensureIndex({
    type: 'hash',
    unique: false,
    fields: ['userId']
  })
}

Migrate

import { migrate } from '.../path/to/src/migrate.js'

await migrate('max') // can be target version instead of 'max'

2021-10-03 16:56:09 [info][arangrate] Performing migration to max!
2021-10-03 16:56:09 [info][arangrate] Total migrations: 1
2021-10-03 16:56:09 [info][0001] Migrating
2021-10-03 16:56:09 [info][arangrate] Migration 0001 - 0001.initial complete!
2021-10-03 16:56:09 [info][arangrate] Migration target completed!

Example - 0001.undo.initial.js

import { dropCollection } from 'arangrate2'
import { getLogger } from 'logade'

export default async function setup () {
  const log = getLogger('0001')

  log.info('Reverting')

  const documentCollections = [
    'notifications',
    'profiles',
    'sessions',
    'users'
  ]
  const edgeCollections = ['hasPrivilege', 'hasRole']

  for (const localName of documentCollections) {
    await dropCollection({ name: localName })
  }

  for (const localName of edgeCollections) {
    await dropCollection({ name: localName })
  }
}

Revert a Migration

To revert, simply provide the migration identifier you would to revert to. If you are on migration 6, you can revert to any identifier before 6, such as entering 5 to revert just migration 6, with 0 being to revert all.

import { migrate } from '.../path/to/src/migrate.js'

await migrate(0)

2021-10-03 16:59:52 [info][arangrate] Performing migration to 0!
2021-10-03 16:59:52 [info][arangrate] Total migrations: 1
2021-10-03 16:59:52 [info][0001] Reverting
2021-10-03 16:59:52 [info][arangrate] Reverted 0001 - 0001.initial complete!
2021-10-03 16:59:52 [info][arangrate] Migration target completed!

File Structure

The examples used here would fall under the following file structure:

- /src
  - migrate.js
- /migrations
  - 0001.do.initial.js
  - 0001.undo.initial.js