hexabot/api/src/migration

Migration Module

The migration module for Hexabot provides a simple and effective way to manage database migrations. It allows you to create, execute, and roll back migrations, ensuring the database schema stays in sync with the version DB updates.

Whenever a new version is released which requires some DB updates, the onApplicationBootstrap() will apply migrations automatically but only if it's a dev environement and config.mongo.autoMigrate is enabled.

Features

• Generate timestamped migration files automatically in kebab-case.
• Track migration execution status in a MongoDB collection (migrations).
• Run individual or all migrations with ease.
• Built-in support for rollback logic.
• Keeps track of the database schema version in the metadata collection (SettingModule).

Usage

Creating a Migration

To create a new migration:

npm run cli migration create <version>

Replace <version> with the next version for your migration, such as v2.1.1.

Example:

npm run cli migration create v2.1.1

This will generate a new file under src/migration/migrations/ with a timestamped filename in kebab-case.

Running Migrations

Running a Specific Migration

To execute a specific migration, use:

npm run cli migration migrate up <version>

Example:

npm run cli migration migrate up v2.1.1

Rolling Back a Specific Migration

To roll back a specific migration, use:

npm run cli migration migrate down <version>

Example:

npm run cli migration migrate down v2.1.1

Running All Migrations

To execute all pending migrations:

npm run cli migration migrate up

Rolling Back All Migrations

To roll back all migrations:

npm run cli migration migrate down

Tracking Migration Status

The migration status is stored in a MongoDB collection called migrations. This collection helps ensure that each migration is executed or rolled back only once, avoiding duplicate operations.

Example Migration File

Below is an example migration file:

import mongoose from 'mongoose';
import attachmentSchema, {
  Attachment,
} from '@/attachment/schemas/attachment.schema';

module.exports = {
  async up() {
    const AttachmentModel = mongoose.model<Attachment>(
      Attachment.name,
      attachmentSchema,
    );
    await AttachmentModel.updateMany({
        type: 'csv'
    }, {
        $set: {  type: 'text/csv' }
    });
  },
  async down() {
    // Rollback logic
    const AttachmentModel = mongoose.model<Attachment>(
      Attachment.name,
      attachmentSchema,
    );
    await AttachmentModel.updateMany({
        type: 'text/csv'
    }, {
        $set: {  type: 'csv' }
    });
  },
};

Explanation

• up Method: Defines the operations to apply the migration (e.g., modifying schemas or inserting data).
• down Method: Defines the rollback logic to revert the migration.

Best Practices

• Use semantic versioning (e.g., v2.1.1) for your migration names to keep track of changes systematically.
• Always test migrations in a development or staging environment before running them in production.
• Keep the up and down methods idempotent to avoid side effects from repeated execution.