{"id":16438,"library":"migrate-mongo-ts","title":"TypeScript MongoDB Migration Tool","description":"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.","status":"active","version":"1.2.3","language":"javascript","source_language":"en","source_url":"https://github.com/oneralon/migrate-mongo-ts","tags":["javascript","migrate mongo mongodb migrations database"],"install":[{"cmd":"npm install migrate-mongo-ts","lang":"bash","label":"npm"},{"cmd":"yarn add migrate-mongo-ts","lang":"bash","label":"yarn"},{"cmd":"pnpm add migrate-mongo-ts","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core database driver used within migration scripts to interact with MongoDB.","package":"mongodb","optional":false}],"imports":[{"note":"Configuration files are expected to use ES Module `export default` syntax for TypeScript support.","wrong":"module.exports = { /* ... */ };","symbol":"default export (config)","correct":"// migrate-mongo-config.ts\nexport default {\n  mongodb: { /* ... */ }\n};"},{"note":"Migration scripts are TypeScript files and should use ES Module `import` syntax.","wrong":"const { Db } = require('mongodb');","symbol":"Db (in migrations)","correct":"import { Db } from 'mongodb';"},{"note":"Migration functions `up` and `down` should be exported using ES Modules and are expected to be `async` or return a `Promise`.","wrong":"function up(db, client, callback) { /* ... */ callback(); }","symbol":"up/down functions","correct":"export async function up(db: Db, client: MongoClient) { /* ... */ }"}],"quickstart":{"code":"import { Db, MongoClient } from 'mongodb';\n\n// 1. Install CLI: npm install -g migrate-mongo-ts\n// 2. Initialize project:\n// $ mkdir my-app-migrations\n// $ cd my-app-migrations\n// $ migrate-mongo-ts init\n\n// This is an example of the generated 'migrate-mongo-config.ts':\nexport default {\n  mongodb: {\n    url: process.env.MONGO_URL ?? \"mongodb://localhost:27017\",\n    databaseName: process.env.MONGO_DB_NAME ?? \"YOURDATABASENAME\",\n    options: {\n      useNewUrlParser: true\n    }\n  },\n  migrationsDir: \"migrations\",\n  changelogCollectionName: \"changelog\"\n};\n\n// 3. Create a new migration:\n// $ migrate-mongo-ts create initial_setup\n\n// This is an example of the generated migration file (e.g., 'migrations/20231027090000-initial_setup.ts'):\nexport async function up(db: Db, client: MongoClient) {\n  console.log('Running up migration: initial_setup');\n  await db.collection('settings').insertOne({ version: '1.0.0', initializedAt: new Date() });\n}\n\nexport async function down(db: Db, client: MongoClient) {\n  console.log('Running down migration: initial_setup');\n  await db.collection('settings').deleteOne({ version: '1.0.0' });\n}","lang":"typescript","description":"Demonstrates the installation, project initialization, generated configuration, and a sample migration file structure using the CLI."},"warnings":[{"fix":"Review the GitHub repository for `migrate-mongo-ts` for specific differences or announcements compared to `migrate-mongo`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `options: { useNewUrlParser: true }` is included in your `migrate-mongo-config.ts` file under the `mongodb` section.","message":"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.","severity":"deprecated","affected_versions":">=1.0.0"},{"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) { /* ... */ }`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Start your MongoDB server. Verify the `url` in `migrate-mongo-config.ts` matches your MongoDB instance's address and port.","cause":"MongoDB server is not running or is not accessible at the specified address.","error":"Error: MongooseServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017"},{"fix":"Run `npm install -g migrate-mongo-ts` to install the CLI globally, or ensure `npm bin` is in your system's PATH.","cause":"The `migrate-mongo-ts` CLI tool is not installed globally or is not in your system's PATH.","error":"migrate-mongo-ts command not found"},{"fix":"Modify your migration function to be `async`: `export async function up(db: Db) { /* ... */ }`.","cause":"The `up` (or `down`) function in your migration script is not `async` and does not explicitly return a Promise.","error":"TypeError: The 'up' function must return a Promise"}],"ecosystem":"npm"}