Detalhes do pacote

ts-migrate-mongoose

ilovepixelart33kMIT4.0.9

A migration framework for Mongoose, built with TypeScript.

backend, migrate, migration, migrations

readme (leia-me)

ts-migrate-mongoose

A migration framework for Mongoose, built with TypeScript.

\ \

Features

Stores migration state in MongoDB
Flexible configuration using migrate.json, migrate.ts, .env
Utilizes mongoose models during migrations
Supports async/await in migrations
Run migrations from the CLI or programmatically
Prune old migrations and sync new migrations
Create custom templates for migrations
Run individual migration up/down using -s, --single
Supports ESM and CommonJS

Example

How to use it with:

Express: ts-express-tsx, ts-express-esbuild
Nest: ts-express-nest

Installation

Locally inside your project

npm install ts-migrate-mongoose
pnpm add ts-migrate-mongoose
yarn add ts-migrate-mongoose
bun add ts-migrate-mongoose

Install it globally

npm install -g ts-migrate-mongoose
pnpm add -g ts-migrate-mongoose
yarn global add ts-migrate-mongoose
bun add -g ts-migrate-mongoose

Migrations and alias imports

If you are using alias imports in your project, you can use tsconfig.json paths to resolve them for your project.

Configuration

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

# You can set this variable or in your CI/CD pipeline
# Or use --mode flag in CLI mode to switch between .env files
MIGRATE_MODE=development

If mode is set, it will look for .env.[mode] file in the root of your project \ For example, if MIGRATE_MODE=development it will look for .env.development file \ If mode is not set, it will look for .env file in the root of your project

.env                # loaded in all cases
.env.local          # loaded in all cases (used as override for local development)
.env.[mode]         # only loaded in specified mode
.env.[mode].local   # only loaded in specified mode (used as override for local development)

# Example .env file content
MIGRATE_MONGO_URI=mongodb://localhost/my-db
MIGRATE_MONGO_COLLECTION=migrations
MIGRATE_CONFIG_PATH=./migrate
MIGRATE_MIGRATIONS_PATH=./migrations
MIGRATE_TEMPLATE_PATH=./migrations/template.ts
MIGRATE_AUTOSYNC=false

Config file	`.env` / export	Default	Required	Description
mode	MIGRATE_MODE	-	No	environment mode to use .env.[mode] file
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	-	No	will lookup ./migrate[.ts,.js,.json] in root
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

Explore and learn commands, rest of the tutorial will be using npm

npx migrate -h
pnpm migrate -h
yarn migrate -h
bun migrate -h

CLI migration tool for mongoose

Options:
  -f, --config-path <path>         path to the config file
  -d, --uri <string>               mongo connection string
  -c, --collection <string>        collection name to use for the migrations
  -a, --autosync <boolean>         automatically sync new migrations without prompt
  -m, --migrations-path <path>     path to the migration files
  -t, --template-path <path>       template file to use when creating a migration
  --mode <string>                  environment mode to use .env.[mode] file
  -h, --help                       display help for command

Commands:
  list                             list all migrations
  create <migration-name>          create a new migration file
  up [options] [migration-name]    run all migrations or a specific migration if name is provided
  down [options] <migration-name>  roll back migrations down to given name
  prune                            delete extraneous migrations from migration folder or database
  help [command]                   display help for command

Before you start make sure you setup .env file or migrate.ts/json file so you don't need to provide -d on each command

npx migrate create add-users -d mongodb://localhost/my-db

In case you want to run just one migration up or down use option --single

npx migrate create first-migration
npx migrate create second-migration
npx migrate list
npx migrate up second-migration -s # will migrate up only second-migration
npx migrate down second-migration -s # will migrate down only second-migration
npx migrate up -s # will migrate up first-migration

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:

npx migrate create first-migration
pnpm migrate create first-migration
yarn migrate create first-migration
bun migrate create first-migration

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

1673525773572-first-migration.ts

// Import your schemas here
import type { Connection } from 'mongoose'

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

export async function down (connection: Connection): 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, models } from 'mongoose'

interface IUser {
  firstName: string
  lastName?: string
}

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

export default models.User ?? model<IUser>('User', UserSchema)

1673525773572-first-migration-demo.ts - your migration file

import { UserSchema } from '../models/User'
import type { Connection } from 'mongoose'

export async function up(connection: Connection) {
  const User = connection.model('User', UserSchema)
  await User.create([
    {
      firstName: 'John',
      lastName: 'Doe',
    },
    {
      firstName: 'Jane',
      lastName: 'Doe',
    },
  ])
}

export async function down(connection: Connection) {
  const User = connection.model('User', UserSchema)
  await User.deleteMany({ firstName: { $in: ['Jane', 'John'] } }).exec()
}

Contributing

We welcome contributions from the community. Please read our Contributing Guidelines before submitting a pull request.

Code of Conduct

Please read our Code of Conduct to understand the expectations we have for everyone who participates in our community.

Notes

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

Check my other projects

ts-patch-mongoose - Patch history & events plugin for mongoose
ts-cache-mongoose - Cache plugin for mongoose Queries and Aggregate (in-memory, redis)

changelog (log de mudanças)

v4.0.8 - 2025-04-05

Merge pull request #407 from ilovepixelart/feature/dep f66681e
Dep aa59b49
Merge pull request #406 from ilovepixelart/feature/dep 0738c3a
Dep 9b611b2
Merge pull request #405 from ilovepixelart/dependabot-npm_and_yarn-all-dependencies-a15b0b07a2 5cd355e
Update dependencies: Bump the all-dependencies group with 2 updates 60ae76d
Update changelog for v4.0.7 e452c0e

https://github.com/ilovepixelart/ts-migrate-mongoose/compare/v4.0.7...v4.0.8

Detalhes do pacote

readme (leia-me)

ts-migrate-mongoose

Features

Example

Installation

Migrations and alias imports

Configuration

Getting started with the CLI

Options override order

Migration files

Using mongoose models in your migrations

Contributing

Code of Conduct

Notes

Check my other projects

changelog (log de mudanças)

v4.0.8 - 2025-04-05

v4.0.7 - 2025-03-28

v4.0.6 - 2025-03-02

v4.0.5 - 2025-03-01

v4.0.4 - 2025-02-28

v4.0.3 - 2025-02-27

v4.0.2 - 2025-02-26

v4.0.1 - 2025-02-22

v4.0.0 - 2025-02-22

v3.8.9 - 2025-01-19

v3.8.8 - 2025-01-12

v3.8.7 - 2024-12-12

v3.8.6 - 2024-12-07

v3.8.5 - 2024-10-26

v3.8.4 - 2024-09-21

v3.8.3 - 2024-08-01

v3.8.2 - 2024-07-06

v3.8.1 - 2024-06-15

v3.8.0 - 2024-06-15

v3.7.1 - 2024-05-18

v3.7.0 - 2024-05-07

v3.6.4 - 2024-04-01

v3.6.3 - 2024-03-27

v3.6.2 - 2024-03-14

v3.6.1 - 2024-02-24

v3.6.0 - 2024-01-28

v3.5.7 - 2024-01-20

v3.5.6 - 2024-01-05

v3.5.5 - 2023-12-16

v3.5.4 - 2023-12-14

v3.5.3 - 2023-12-06

v3.5.2 - 2023-11-28

v3.5.1 - 2023-11-28

v3.5.0 - 2023-11-12

v3.4.2 - 2023-11-06

v3.4.1 - 2023-10-16

v3.4.0 - 2023-10-02

v3.3.3 - 2023-09-15

v3.3.2 - 2023-09-01

v3.3.1 - 2023-08-14

v3.3.0 - 2023-08-05

v3.2.0 - 2023-07-24

v3.1.9 - 2023-07-15

v3.1.8 - 2023-06-30

v3.1.7 - 2023-06-09

v3.1.6 - 2023-05-17

v3.1.5 - 2023-05-03

v3.1.4 - 2023-04-29

v3.1.3 - 2023-04-22

v3.1.2 - 2023-04-18

v3.1.1 - 2023-04-13

v3.1.0 - 2023-04-11

v3.0.9 - 2023-04-11

v3.0.8 - 2023-04-10

v3.0.7 - 2023-04-07

v3.0.6 - 2023-04-06

v3.0.5 - 2023-04-06

v3.0.4 - 2023-03-30

v3.0.3 - 2023-03-29

v3.0.2 - 2023-03-25

v3.0.1 - 2023-03-25

v3.0.0 - 2023-03-23

v2.5.3 - 2023-03-16