Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/aboviq/emigrate
The modern, modular and flexible migration tool for any database
https://github.com/aboviq/emigrate
bun database database-migrations database-schema javascript migrations nodejs sql tools typescript
Last synced: 23 days ago
JSON representation
The modern, modular and flexible migration tool for any database
- Host: GitHub
- URL: https://github.com/aboviq/emigrate
- Owner: aboviq
- License: mit
- Created: 2023-11-10T09:57:12.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2024-09-23T02:12:20.000Z (about 1 month ago)
- Last Synced: 2024-10-02T21:30:49.259Z (about 1 month ago)
- Topics: bun, database, database-migrations, database-schema, javascript, migrations, nodejs, sql, tools, typescript
- Language: TypeScript
- Homepage: https://emigrate.dev/
- Size: 1.6 MB
- Stars: 2
- Watchers: 3
- Forks: 0
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Emigrate
> The modern, modular and flexible migration tool for any database
It's effectively a successor of [klei-migrate](https://www.npmjs.com/package/klei-migrate) and [Immigration](https://www.npmjs.com/package/immigration).
📖 Read the [documentation](https://emigrate.dev) for more information!
## Features
- Database agnostic
- Emigrate can migrate any database
- Works at any scale
- Supports any database as storage so multiple instances of the same app can share the same migration history
- Supports multiple projects/apps doing migrations on the same database without interfering with each other
- Uses smart locking to ensure only one instance migrates a certain migration at a time
- Thanks to the smart locking it's safe to run migrations in parallel
- Can be run inside containers
- It's common for Docker or Kubernetes to kill containers with health checks if migrations takes too long to run
- Emigrate makes sure the migration history does not get stuck in a locked state if that's the case
- Supports any file type for your migration files
- You can easily write migrations in JavaScript, TypeScript or plain SQL (or any other language)
- JavaScript migration files written using CommonJS or ES modules (ESM) are supported out of the box
- You can customize the template for your migration files to fit your needs (or use a plugin to do it for you)
- Easy to debug
- Emigrate will store any errors that occur during migration in the migration history so you can easily debug them
## Installation
Install the Emigrate CLI in your project:
```bash
npm install @emigrate/cli
# or
pnpm add @emigrate/cli
# or
yarn add @emigrate/cli
# or
bun add @emigrate/cli
```
## Usage
```text
Usage: emigrate up [options]
Run all pending migrations
Options:
-h, --help Show this help message and exit
-d, --directory The directory where the migration files are located (required)
-i, --import Additional modules/packages to import before running the migrations (can be specified multiple times)
For example if you want to use Dotenv to load environment variables or when using TypeScript
-s, --storage The storage to use for where to store the migration history (required)
-p, --plugin The plugin(s) to use (can be specified multiple times)
-r, --reporter The reporter to use for reporting the migration progress
-l, --limit Limit the number of migrations to run
-f, --from Start running migrations from the given migration name or relative file path to a migration file,
the given name or path needs to exist. The same migration and those after it lexicographically will be run
-t, --to Skip migrations after the given migration name or relative file path to a migration file,
the given name or path needs to exist. The same migration and those before it lexicographically will be run
--dry List the pending migrations that would be run without actually running them
--color Force color output (this option is passed to the reporter)
--no-color Disable color output (this option is passed to the reporter)
--no-execution Mark the migrations as executed and successful without actually running them,
which is useful if you want to mark migrations as successful after running them manually
--abort-respite The number of seconds to wait before abandoning running migrations after the command has been aborted (default: 10)
Examples:
emigrate up --directory src/migrations -s fs
emigrate up -d ./migrations --storage @emigrate/mysql
emigrate up -d src/migrations -s postgres -r json --dry
emigrate up -d ./migrations -s mysql --import dotenv/config
emigrate up --limit 1
emigrate up --to 20231122120529381_some_migration_file.js
emigrate up --to 20231122120529381_some_migration_file.js --no-execution
```
### Examples
Create a new migration:
```bash
npx emigrate new -d migrations create some fancy table
# or
pnpm emigrate new -d migrations create some fancy table
# or
yarn emigrate new -d migrations create some fancy table
# or
bunx --bun emigrate new -d migrations create some fancy table
```
Will create a new empty JavaScript migration file with the name "YYYYMMDDHHmmssuuu_create_some_fancy_table.js" in the `migrations` directory.
## License
Emigrate is licensed under the MIT license. See [LICENSE](LICENSE) for the full license text.