Quick Start

What's Emigrate? Learn more about Emigrate and what it can do for you.

Install the Emigrate CLI

npm install @emigrate/cli

pnpm add @emigrate/cli

yarn add @emigrate/cli

bun add @emigrate/cli

{
  "scripts": {
    "emigrate": "emigrate"
  },
  "dependencies": {
    "@emigrate/cli": "*"
  }
}

Pick a storage plugin

Emigrate uses a storage plugin to store the migration history.

Install the plugin you want to use, for example the PostgreSQL Storage:

npm install @emigrate/postgres

pnpm add @emigrate/postgres

yarn add @emigrate/postgres

bun add @emigrate/postgres

{
  "dependencies": {
    "@emigrate/cli": "*",
    "@emigrate/postgres": "*"
  }
}

Create your first migration

Baseline your database Learn how to create a baseline of your existing database.

Create a new migration file in your project using:

npx emigrate new --plugin postgres create users table

pnpm emigrate new --plugin postgres create users table

yarn emigrate new --plugin postgres create users table

bunx --bun emigrate new --plugin postgres create users table

{
  "scripts": {
    "emigrate": "emigrate"
  }
}

deno task emigrate new --plugin postgres create users table

Emigrate new v0.10.0 /your/project/path

  ✔ migrations/20231215125421364_create_users_table.sql (done) 3ms

  1 created

Fill the migration file

Open the migration file in your editor and fill it with your SQL query:

-- Migration: create users table
CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  email VARCHAR(255) NOT NULL
);

Show migration status

To show both pending and already applied migrations (or previously failed), use the list command:

npx emigrate list --storage postgres

pnpm emigrate list --storage postgres

yarn emigrate list --storage postgres

bunx --bun emigrate list --storage postgres

{
  "scripts": {
    "emigrate": "emigrate"
  }
}

deno task emigrate list --storage postgres

Emigrate list v0.10.0 /your/project/path

  ✔ migrations/20231211090830577_another_table.sql (done)
  › migrations/20231215125421364_create_users_table.sql (pending)

  1 done | 1 pending (2 total)

Running the migrations

A good way to test your configuration is to run the migrations in dry mode:

npx emigrate up --storage postgres --plugin postgres --dry

pnpm emigrate up --storage postgres --plugin postgres --dry

yarn emigrate up --storage postgres --plugin postgres --dry

bunx --bun emigrate up --storage postgres --plugin postgres --dry

{
  "scripts": {
    "emigrate": "emigrate"
  }
}

deno task emigrate up --storage postgres --plugin postgres --dry