TypeScript MongoDB Migration Tool

1.2.3 · active · verified Wed Apr 22

migrate-mongo-ts is a database migration tool specifically designed for MongoDB within Node.js environments, providing robust TypeScript support. As a direct fork of the widely-used `migrate-mongo` package, it adapts its functionality for modern TypeScript workflows, ensuring type safety and improved developer experience when managing database schema changes. The current stable version is 1.2.3. This tool simplifies the process of evolving MongoDB schemas by enabling developers to define discrete 'up' and 'down' migration scripts, which are then applied and rolled back via a command-line interface. Key differentiators include its explicit focus on TypeScript for configuration and migration scripts, offering strong typing for the MongoDB `Db` and `MongoClient` objects passed into migration functions. It supports common operations such as project initialization, creating new migration files, applying pending migrations, rolling back the last migration, and checking migration status, making it a comprehensive solution for maintaining database consistency across various environments. Its release cadence typically mirrors updates from its upstream `migrate-mongo` parent, incorporating TypeScript-specific enhancements.

Common errors

```
Error: MongooseServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017
```
cause MongoDB server is not running or is not accessible at the specified address.

fix Start your MongoDB server. Verify the `url` in `migrate-mongo-config.ts` matches your MongoDB instance's address and port.
```
migrate-mongo-ts command not found
```
cause The `migrate-mongo-ts` CLI tool is not installed globally or is not in your system's PATH.

fix Run `npm install -g migrate-mongo-ts` to install the CLI globally, or ensure `npm bin` is in your system's PATH.
```
TypeError: The 'up' function must return a Promise
```
cause The `up` (or `down`) function in your migration script is not `async` and does not explicitly return a Promise.

fix Modify your migration function to be `async`: `export async function up(db: Db) { /* ... */ }`.

Warnings

gotcha The `migrate-mongo-ts` package is a fork of `migrate-mongo`. While aiming for compatibility, it may diverge in features, bug fixes, or release cadence. Users should be aware of potential differences from the upstream project.
Fix: Review the GitHub repository for `migrate-mongo-ts` for specific differences or announcements compared to `migrate-mongo`.
deprecated When configuring the MongoDB connection, `useNewUrlParser: true` is highly recommended (and often required in newer MongoDB driver versions) to avoid deprecation warnings. Omitting it can lead to warnings or connection issues.
Fix: Ensure `options: { useNewUrlParser: true }` is included in your `migrate-mongo-config.ts` file under the `mongodb` section.
gotcha Migration functions (`up` and `down`) must return a Promise, either by explicitly returning one or by being declared `async`. Forgetting this can lead to migrations not completing correctly or silently failing.
Fix: Always declare your `up` and `down` functions as `async` or ensure they explicitly return a Promise. For example: `export async function up(db: Db) { /* ... */ }`.

Install

npm install migrate-mongo-ts npm
yarn add migrate-mongo-ts yarn
pnpm add migrate-mongo-ts pnpm

Imports

default export (config)
wrong:
```
module.exports = { /* ... */ };
```
correct:
```
// migrate-mongo-config.ts
export default {
  mongodb: { /* ... */ }
};
```
Configuration files are expected to use ES Module `export default` syntax for TypeScript support.
Db (in migrations)
wrong:
```
const { Db } = require('mongodb');
```
correct:
```
import { Db } from 'mongodb';
```
Migration scripts are TypeScript files and should use ES Module `import` syntax.
up/down functions
wrong:
```
function up(db, client, callback) { /* ... */ callback(); }
```
correct:
```
export async function up(db: Db, client: MongoClient) { /* ... */ }
```
Migration functions `up` and `down` should be exported using ES Modules and are expected to be `async` or return a `Promise`.

Quickstart

Demonstrates the installation, project initialization, generated configuration, and a sample migration file structure using the CLI.

import { Db, MongoClient } from 'mongodb';

// 1. Install CLI: npm install -g migrate-mongo-ts
// 2. Initialize project:
// $ mkdir my-app-migrations
// $ cd my-app-migrations
// $ migrate-mongo-ts init

// This is an example of the generated 'migrate-mongo-config.ts':
export default {
  mongodb: {
    url: process.env.MONGO_URL ?? "mongodb://localhost:27017",
    databaseName: process.env.MONGO_DB_NAME ?? "YOURDATABASENAME",
    options: {
      useNewUrlParser: true
    }
  },
  migrationsDir: "migrations",
  changelogCollectionName: "changelog"
};

// 3. Create a new migration:
// $ migrate-mongo-ts create initial_setup

// This is an example of the generated migration file (e.g., 'migrations/20231027090000-initial_setup.ts'):
export async function up(db: Db, client: MongoClient) {
  console.log('Running up migration: initial_setup');
  await db.collection('settings').insertOne({ version: '1.0.0', initializedAt: new Date() });
}

export async function down(db: Db, client: MongoClient) {
  console.log('Running down migration: initial_setup');
  await db.collection('settings').deleteOne({ version: '1.0.0' });
}

view raw JSON →