TypeScript icon, indicating that this package has built-in type declarations

3.0.2 • Public • Published


A node/typescript based migration framework for mongoose

npm npm GitHub
Coverage Quality Gate Status
Reliability Rating Maintainability Rating Security Rating



ts-migrate-mongoose is a migration framework for projects which are already using mongoose


  • Stores migration state in MongoDB
  • Flexibility in configuration migrate.json / migrate.ts or .env
  • Ability to use mongoose models when running migrations
  • Ability to use of async/await in migrations
  • Ability to run migrations from the CLI
  • Ability to run migrations programmatically
  • Ability to prune old migrations, and sync new migrations
  • Ability to create custom templates for migrations


How to use it with express ts-express-swc


  • Locally inside your project
yarn add ts-migrate-mongoose
npm install ts-migrate-mongoose
  • Install it globally
yarn global add ts-migrate-mongoose
npm install -g ts-migrate-mongoose


If you don't want to provide -d or --uri flag in CLI or Programmatic mode, you can configure it.
Create a migrate.json or migrate.ts or .env file in the root of your project:

  • migrate.json
  "uri": "mongodb://localhost/my-db",
  "collection": "migrations",
  "migrationsPath": "./migrations",
  "templatePath": "./migrations/template.ts",
  "autosync": false
  • migrate.ts
export default {
  uri: "mongodb://localhost/my-db",
  collection: "migrations",
  migrationsPath: "./migrations",
  templatePath: "./migrations/template.ts",
  autosync: false,
  • .env
# or 
Config file .env / export Default Required Description
uri MIGRATE_MONGO_URI - Yes mongo connection string
collection MIGRATE_MONGO_COLLECTION migrations No collection name to use for the migrations
configPath MIGRATE_CONFIG_PATH ./migrate No path to the config file
migrationsPath MIGRATE_MIGRATIONS_PATH ./migrations No path to the migration files
templatePath MIGRATE_TEMPLATE_PATH - No template file to use when creating a migration
autosync MIGRATE_AUTOSYNC false No automatically sync new migrations without prompt

Getting Started with the CLI

yarn migrate help
npx migrate help
CLI migration tool for mongoose

  -f, --config-path <path>      path to the config file (default: "migrate")
  -d, --uri <string>            mongo connection string
  -c, --collection <string>     collection name to use for the migrations (default: "migrations")
  -a, --autosync <boolean>      automatically sync new migrations without prompt (default: false)
  -m, --migrations-path <path>  path to the migration files (default: "./migrations")
  -t, --template-path <path>    template file to use when creating a migration
  -h, --help                    display help for command

  list                          list all migrations
  create <migration-name>       create a new migration file
  up [migration-name]           run all migrations or a specific migration if name provided
  down <migration-name>         roll back migrations down to given name
  prune                         delete extraneous migrations from migration folder or database
  help [command]                display help for command
  • Examples yarn
yarn migrate list -d mongodb://localhost/my-db
yarn migrate create add_users -d mongodb://localhost/my-db
yarn migrate up add_user -d mongodb://localhost/my-db
yarn migrate down delete_names -d mongodb://localhost/my-db
yarn migrate prune -d mongodb://localhost/my-db
yarn migrate list --config settings.json
  • Examples npm
npx migrate list -d mongodb://localhost/my-db
npx migrate create add_users -d mongodb://localhost/my-db
npx migrate up add_user -d mongodb://localhost/my-db
npx migrate down delete_names -d mongodb://localhost/my-db
npx migrate prune -d mongodb://localhost/my-db
npx migrate list --config settings.json

Options Override Order

Note that options are overridden in the following order:

  • Command line args > Env vars > Config file

Migration Files

This example demonstrates how you can create a migration file using the CLI
By default, ts-migrate-mongoose assumes your migration folder exists (if it does not it will create one for you)

Here's an example of a migration created using:

yarn migrate create first-migration-demo
npx migrate create first-migration-demo

Executing the above command will create a migration file in the ./migrations folder with the following content:

  • 1673525773572-first-migration-demo.ts
// Import your models here

export async function up (): Promise<void> {
  // Write migration here

export async function down (): Promise<void> {
  // Write migration here

Using mongoose models in your migrations

As long as you can import the references to your models you can use them in migrations
Below is an example of a typical setup in a mongoose project:

  • models/User.ts - defines the User model
import { Schema, model } from 'mongoose'

interface IUser {
  firstName: string
  lastName?: string

const UserSchema = new Schema<IUser>({
  firstName: {
    type: String,
    required: true
  lastName: {
    type: String

export default model<IUser>('user', UserSchema)
  • models/index.ts - ensures that all models are exported and you establish a connection to the database
import mongoose from 'mongoose'
import mongooseOptions from '../options/mongoose'

import User from './User'

const getModels = async () => {
  // In case you using mongoose 6
  // https://mongoosejs.com/docs/guide.html#strictQuery
  mongoose.set('strictQuery', false)

  // Ensure connection is open so we can run migrations
  if (mongoose.connection.readyState !== 1) {
    await mongoose.connect(process.env.MIGRATE_MONGO_URI ?? 'mongodb://localhost:27017/express', mongooseOptions)

  // Return models that will be used in migration methods
  return {

export default getModels
  • 1673525773572-first-migration-demo.ts - your migration file
import getModels from '../models'

export async function up () {
  const { User } = await getModels()
  // Write migration here
  await User.create([
      firstName: 'John',
      lastName: 'Doe'
      firstName: 'Jane',
      lastName: 'Doe'

export async function down () {
  const { User } = await getModels()
  // Write migration here
  await User.deleteMany({ firstName: { $in: ['Jane', 'John'] } }).exec()


  • Currently, the -d or --uri must include the database to use for migrations in the uri.
  • Example: -d mongodb://localhost:27017/development
  • If you don't want to pass it in every time feel free to use migrate.ts or migrate.json config file or an environment variable
  • Feel Free to check out the /examples folder in the project to get a better idea of usage in Programmatic and CLI mode


npm i ts-migrate-mongoose

DownloadsWeekly Downloads






Unpacked Size

163 kB

Total Files


Last publish


  • ilovepixelart