feat(mysql): implement the first version of the MySQL plugin package

packages/mysql/README.md

@@ -0,0 +1,177 @@
+# @emigrate/storage-mysql
+
+A MySQL plugin for Emigrate. Uses a MySQL database for storing migration history. Can load and generate .sql migration files.
+
+The table used for storing the migration history is compatible with the [immigration-mysql](https://github.com/joakimbeng/immigration-mysql) package, so you can use this together with the [@emigrate/cli](../cli) as a drop-in replacement for that package.
+
+## Description
+
+This plugin is actually three different Emigrate plugins in one:
+
+1. A [storage plugin](#using-the-storage-plugin) for storing the migration history in a MySQL database.
+2. A [loader plugin](#using-the-loader-plugin) for loading .sql migration files and be able to execute them as part of the migration process.
+3. A [generator plugin](#using-the-generator-plugin) for generating .sql migration files.
+
+## Installation
+
+Install the plugin in your project, alongside the Emigrate CLI:
+
+```bash
+npm install --save-dev @emigrate/cli @emigrate/mysql
+```
+
+## Usage
+
+### Using the storage plugin
+
+See [Options](#options) below for the default values and how to configure the plugin using environment variables.
+
+Configure the storage in your `emigrate.config.js` file:
+
+```js
+export default {
+  directory: 'migrations',
+  storage: 'mysql', // the @emigrate/ prefix is optional
+};
+```
+
+Or use the CLI options `--storage` (or `-s`)
+
+```bash
+emigrate up --storage mysql  # the @emigrate/ prefix is optional
+```
+
+#### Storage plugin with custom options
+
+Configure the storage in your `emigrate.config.js` file by importing the `createMysqlStorage` function (see [Options](#options) for available options).
+
+In this mode the plugin will _not_ use any of the environment variables for configuration.
+
+```js
+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](#options) for available variables).
+
+```bash
+MYSQL_URL=mysql://user:pass@host/db emigrate up --storage mysql  # the @emigrate/ prefix is optional
+```
+
+### Using the loader plugin
+
+The loader plugin is used to transform .sql migration files into JavaScript functions that can be executed by the "up" command.
+
+See [Options](#options) below for the default values and how to configure the plugin using environment variables.
+
+Configure the loader in your `emigrate.config.js` file:
+
+```js
+export default {
+  directory: 'migrations',
+  plugins: ['mysql'], // the @emigrate/ prefix is optional
+};
+```
+
+Or by importing the default export from the plugin:
+
+```js
+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](#using-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:
+
+```js
+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:
+
+```bash
+emigrate up --plugin mysql  # the @emigrate/ prefix is optional
+```
+
+### Using the generator plugin
+
+The generator plugin is used to generate skeleton .sql migration files inside your migration directory.
+
+Configure the generator in your `emigrate.config.js` file:
+
+```js
+export default {
+  directory: 'migrations',
+  plugins: ['mysql'], // the @emigrate/ prefix is optional
+};
+```
+
+Or by importing the default export from the plugin:
+
+```js
+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](#using-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:
+
+```js
+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:
+
+```bash
+emigrate new --plugin mysql My new migration file  # the @emigrate/ prefix is optional
+```
+
+#### Loader plugin with custom options
+
+Configure the loader in your `emigrate.config.js` file by importing the `createMysqlLoader` function (see [Options](#options) for available options).
+
+In this mode the plugin will _not_ use any of the environment variables for configuration.
+
+```js
+import { createMysqlLoader } from '@emigrate/mysql';
+
+export default {
+  directory: 'migrations',
+  plugins: [
+    createMysqlLoader({ connection: { ... } }), // All connection options are passed to mysql.createConnection()
+  ],
+};
+```
+
+## Options
+
+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()`](https://github.com/mysqljs/mysql#connection-options). | `{}`         | `MYSQL_URL` or `MYSQL_HOST`, `MYSQL_PORT`, `MYSQL_USER`, `MYSQL_PASSWORD` and `MYSQL_DATABASE` |