migrate-mongo-ts

library1.2.3jsnpmunverified

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.

database devops type-stubs

npm install migrate-mongo-ts

github ↗package ↗

INSTALL

IMPORT

SIG · MIGRATE-MONGO-TS

migrate-mongo-ts

databasejavascriptv1.2.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default export (config)

✓ // migrate-mongo-config.ts export default { mongodb: { /* ... */ } };

✗ module.exports = { /* ... */ };

Configuration files are expected to use ES Module `export default` syntax for TypeScript support.

Db (in migrations)

✓ import { Db } from 'mongodb';

✗ const { Db } = require('mongodb');

Migration scripts are TypeScript files and should use ES Module `import` syntax.

up/down functions

✓ export async function up(db: Db, client: MongoClient) { /* ... */ }

✗ function up(db, client, callback) { /* ... */ callback(); }

Migration functions `up` and `down` should be exported using ES Modules and are expected to be `async` or return a `Promise`.

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' }); }

migrate-mongo-ts --version

Debug

Known issues

gotchaThe `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`.

affects: >=1.0.0

deprecatedWhen 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.

affects: >=1.0.0

gotchaMigration 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) { /* ... */ }`.

affects: >=1.0.0

Errors

Common errors & fixes

Error: MongooseServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017

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

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

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) { /* ... */ }`.

Upgrade

Version history

1.2.3latest on npm

Audit

Dependencies

mongodbrequiredCore database driver used within migration scripts to interact with MongoDB.

Agent activity

31 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/oneralon/migrate-mongo-ts ↗

packagehttps://www.npmjs.com/package/migrate-mongo-ts ↗