mongoose-migration-ts

A type-safe database migration library for Mongoose.

Table of Contents

• Installation
• Setup
• Usage
  • Generating a Migration
  • Running Migrations
  • Rolling Back Migrations
• Configuration
• API Reference
• Contributing
• License

Installation

Install the package using npm:

npm install mongoose-migration-ts

Or using yarn:

yarn add mongoose-migration-ts

Setup

1. Create a configuration file named migrate.mongoose.ts (or .js) in your project root:

import { MigrationConfig } from 'mongoose-migration-ts';

const config: MigrationConfig = {
  migrationsDir: './migrations',
  sourceType: 'typescript', // or 'javascript'
  moduleType: 'esm', // or 'commonjs'
  dbUrl: 'mongodb://localhost:27017/your_database',
  dbName: 'your_database'
};

export default config;

2. Add the following scripts to your package.json:

{
  "scripts": {
    "migrate:generate": "mongoose-migrate generate --config ./migrate.mongoose.ts",
    "migrate:up": "mongoose-migrate up --config ./migrate.mongoose.ts",
    "migrate:down": "mongoose-migrate down --config ./migrate.mongoose.ts",
    "migrate:down:steps": "mongoose-migrate down --config ./migrate.mongoose.ts --steps"
  }
}

Usage

Generating a Migration

To create a new migration file:

npm run migrate:generate -- my_new_migration

This will create a new file in your migrations directory with a timestamp prefix.

Running Migrations

To apply all pending migrations:

npm run migrate:up

Rolling Back Migrations

To roll back the most recent migration:

npm run migrate:down

To roll back a specific number of migrations:

npm run migrate:down:steps -- 3

Configuration

The MigrationConfig interface accepts the following options:

• migrationsDir: The directory where migration files are stored.
• sourceType: The type of source files ('typescript' or 'javascript').
• moduleType: The module system used ('esm' or 'commonjs').
• dbUrl: The MongoDB connection URL.
• dbName: The name of the database.

API Reference

Migrator Class

The main class for performing migrations.

Methods:

• up(): Apply all pending migrations.
• down(steps: number): Roll back a specified number of migrations.
• generate(name: string): Generate a new migration file.

Migration File Structure

Each migration file should export an object with up and down methods:

import mongoose from 'mongoose';

export default {
  async up() {
    // Migration logic here
  },

  async down() {
    // Rollback logic here
  }
};

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.