A MySQL plugin for Emigrate. Uses a MySQL database for storing the migration history. Can load and generate .sql migration files.
The table used for storing the migration history is compatible with the immigration-mysql package, so you can use this together with the @emigrate/cli as a drop-in replacement for that package.
This plugin is actually three different Emigrate plugins in one:
- A storage plugin for storing the migration history in a MySQL database.
- A loader plugin for loading .sql migration files and be able to execute them as part of the migration process.
- A generator plugin for generating .sql migration files.
Install the plugin in your project, alongside the Emigrate CLI:
npm install @emigrate/cli @emigrate/mysql
# or
pnpm add @emigrate/cli @emigrate/mysql
# or
yarn add @emigrate/cli @emigrate/mysql
# or
bun add @emigrate/cli @emigrate/mysql
See Options below for the default values and how to configure the plugin using environment variables.
Configure the storage in your emigrate.config.js
file:
export default {
directory: 'migrations',
storage: 'mysql', // the @emigrate/ prefix is optional
};
Or use the CLI options --storage
(or -s
)
emigrate up --storage mysql # the @emigrate/ prefix is optional
Configure the storage in your emigrate.config.js
file by importing the createMysqlStorage
function (see Options for available options).
In this mode the plugin will not use any of the environment variables for configuration.
import { createMysqlStorage } from '@emigrate/mysql';
export default {
directory: 'migrations',
storage: createMysqlStorage({ table: 'migrations', connection: { ... } }), // All connection options are passed to mysql.createConnection()
};
Or use the CLI option --storage
(or -s
) and use environment variables (see Options for available variables).
MYSQL_URL=mysql://user:pass@host/db emigrate up --storage mysql # the @emigrate/ prefix is optional
The loader plugin is used to transform .sql migration files into JavaScript functions that can be executed by the "up" command.
See Options below for the default values and how to configure the plugin using environment variables.
Configure the loader in your emigrate.config.js
file:
export default {
directory: 'migrations',
plugins: ['mysql'], // the @emigrate/ prefix is optional
};
Or by importing the default export from the plugin:
import mysqlPlugin from '@emigrate/mysql';
export default {
directory: 'migrations',
plugins: [mysqlPlugin],
};
NOTE: Using the root level plugins
option will load the plugin for all commands, which means the generator plugin will be used by default for the "new" command as well. If you only want to use the loader plugin, use the up.plugins
option instead:
export default {
directory: 'migrations',
up: {
plugins: ['mysql'], // the @emigrate/ prefix is optional
// or:
plugins: [import('@emigrate/mysql')],
},
};
The loader plugin can also be loaded using the CLI option --plugin
(or -p
) together with the "up" command:
emigrate up --plugin mysql # the @emigrate/ prefix is optional
The generator plugin is used to generate skeleton .sql migration files inside your migration directory.
Configure the generator in your emigrate.config.js
file:
export default {
directory: 'migrations',
plugins: ['mysql'], // the @emigrate/ prefix is optional
};
Or by importing the default export from the plugin:
import mysqlPlugin from '@emigrate/mysql';
export default {
directory: 'migrations',
plugins: [mysqlPlugin],
};
NOTE: Using the root level plugins
option will load the plugin for all commands, which means the loader plugin will be used by default for the "up" command as well. If you only want to use the generator plugin, use the new.plugins
option instead:
export default {
directory: 'migrations',
new: {
plugins: ['mysql'], // the @emigrate/ prefix is optional
// or:
plugins: [import('@emigrate/mysql')],
},
};
The generator plugin can also be loaded using the CLI option --plugin
(or -p
) together with the "new" command:
emigrate new --plugin mysql My new migration file # the @emigrate/ prefix is optional
Configure the loader in your emigrate.config.js
file by importing the createMysqlLoader
function (see Options for available options).
In this mode the plugin will not use any of the environment variables for configuration.
import { createMysqlLoader } from '@emigrate/mysql';
export default {
directory: 'migrations',
plugins: [
createMysqlLoader({ connection: { ... } }), // All connection options are passed to mysql.createConnection()
],
};
The storage plugin accepts the following options:
Option | Applies to | Description | Default | Environment variable |
---|---|---|---|---|
table |
storage plugin | The name of the table to use for storing the migrations. | migrations |
MYSQL_TABLE |
connection |
storage and loader plugins | The connection options to pass to mysql.createConnection() . |
{} |
MYSQL_URL or MYSQL_HOST , MYSQL_PORT , MYSQL_USER , MYSQL_PASSWORD and MYSQL_DATABASE
|