aboviq/emigrate
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

docs: first commit for the docs

Browse source
This commit is contained in:
Joakim Carlstein 2023-12-15 16:51:17 +01:00 • committed by Joakim Carlstein
parent 987374dbd5
commit d5c6e9b1db
27 changed files with 4281 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

BIN
docs/src/assets/houston.webp Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 96 KiB

7
docs/src/content/config.ts Normal file
View file

@ -0,0 +1,7 @@
import { defineCollection } from 'astro:content';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
export const collections = {
docs: defineCollection({ schema: docsSchema() }),
i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
};

153
docs/src/content/docs/getting-started.mdx Normal file
View file

@ -0,0 +1,153 @@
---
title: Getting Started
description: How to getting started with Emigrate, the database migration tool
---
import { Tabs, TabItem } from '@astrojs/starlight/components';
Emigrate is written in [TypeScript](https://www.typescriptlang.org) and is a database migration tool for any database.
* It's the successor of [klei-migrate](https://github.com/klei/migrate) and is designed to be compatible with [Immigration](https://github.com/blakeembrey/node-immigration) and many of its storage plugins, as well as [Migrate](https://github.com/tj/node-migrate).
* It supports migration files written using [CommonJS or ES Modules out of the box](/loaders/default/), with any of the following extensions: `.js`, `.cjs` or `.mjs`, and supports [async functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function), [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) or using the [NodeJS Callback Pattern](https://nodejs.org/en/learn/asynchronous-work/javascript-asynchronous-programming-and-callbacks#handling-errors-in-callbacks).
* Other languages can be used by using a [Loader Plugin](/loaders/).
* The migration history can be stored anywhere using a [Storage Plugin](/storage/).
* The output can be customized using [Reporters](/reporters/).
:::tip[Did you know?]
Thanks to the plugin system you can even write migrations in plain SQL! So no need for Java-based tools like Liquibase or Flyway.
:::
## Quick Start
:::note
The following guide will be even simpler soon with the release of a initialization command.
But for now, this is the way to go.
:::
### Install the Emigrate CLI
<Tabs>
<TabItem label="npm">
```bash
npm install @emigrate/cli
```
</TabItem>
<TabItem label="pnpm">
```bash
pnpm add @emigrate/cli
```
</TabItem>
<TabItem label="yarn">
```bash
yarn add @emigrate/cli
```
</TabItem>
</Tabs>
### Pick a storage plugin
Emigrate uses a storage plugin to store the migration history. You can use one of the following plugins:
- [MySQL](/storage/mysql)
- [File System](/storage/file-system)
Install the plugin you want to use, for example:
<Tabs>
<TabItem label="npm">
```bash
npm install @emigrate/mysql
```
</TabItem>
<TabItem label="pnpm">
```bash
pnpm add @emigrate/mysql
```
</TabItem>
<TabItem label="yarn">
```bash
yarn add @emigrate/mysql
```
</TabItem>
</Tabs>
### Create your first migration
Create a new migration file in your project using:
```bash title="Create a new migration file"
npx emigrate new --plugin mysql create users table
```
```txt title="Output"
Emigrate new v0.9.0 /your/project/path
✔ migrations/20231215125421364_create_users_table.sql (done) 3ms
1 created
```
:::note
The `mysql` plugin is used here to generate a migration file with the `.sql` extension.
Otherwise the file would have the `.js` extension by default.
:::
:::tip[Did you know?]
You can avoid typing `--plugin mysql` by configuring Emigrate using an `emigrate.config.js` file.
See [Configuration](/configuration) for more information.
:::
#### Fill the migration file
Open the migration file in your editor and fill it with your SQL query:
```sql title="migrations/20231215125421364_create_users_table.sql" {2-7}
-- Migration: create users table
CREATE TABLE users (
id INT NOT NULL AUTO_INCREMENT,
name VARCHAR(255) NOT NULL,
email VARCHAR(255) NOT NULL,
PRIMARY KEY (id)
);
```
### Show migration status
To show both pending and already applied migrations (or previously failed), use the `list` command:
```bash title="Show all migrations"
npx emigrate list --storage mysql
```
```txt title="Example output"
Emigrate list v0.9.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:
```bash title="Show pending migrations"
npx emigrate up --storage mysql --plugin mysql --dry
```
:::note
This will connect to the database using some default values. For ways to configure the connection, see [Configuration](/configuration).
:::
:::caution
Without the `--dry` flag this will run the migration and change your database!
Be sure to configure the connection correctly and use the `--dry` flag to test your configuration.
:::
:::tip[Did you know?]
In the example above the `@emigrate/mysql` plugin is used twice, once for the `--storage` option as a [Storage Plugin](/storage/)
and once for the `--plugin` option as a [Loader Plugin](/loaders/) to be able to read `.sql` files.
:::

11
docs/src/content/docs/guides/example.md Normal file
View file

@ -0,0 +1,11 @@
---
title: Example Guide
description: A guide in my new Starlight docs site.
---
Guides lead a user through a specific task they want to accomplish, often with a sequence of steps.
Writing a good guide requires thinking about what your users are trying to do.
## Further reading
- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework

36
docs/src/content/docs/index.mdx Normal file
View file

@ -0,0 +1,36 @@
---
title: Effortless database changes with Emigrate
description: Adapt any and all of your databases to your needs at any scale. Modern, flexible, and easy to use.
template: splash
hero:
tagline: Adapt any and all of your databases to new business needs.<br>Emigrate is modern, flexible, scalable, and easy to use.
image:
file: ../../assets/houston.webp
actions:
- text: Quick Start
link: /getting-started/
icon: right-arrow
variant: primary
- text: View on GitHub
link: https://github.com/aboviq/emigrate
icon: external
---
import { Card, CardGrid } from '@astrojs/starlight/components';
## Next steps
<CardGrid stagger>
<Card title="Update content" icon="pencil">
Edit `src/content/docs/index.mdx` to see this page change.
</Card>
<Card title="Add new content" icon="add-document">
Add Markdown or MDX files to `src/content/docs` to create new pages.
</Card>
<Card title="Configure your site" icon="setting">
Edit your `sidebar` and other config in `astro.config.mjs`.
</Card>
<Card title="Read the docs" icon="open-book">
Learn more in [the Starlight Docs](https://starlight.astro.build/).
</Card>
</CardGrid>

228
docs/src/content/docs/loaders/default.mdx Normal file
View file

@ -0,0 +1,228 @@
---
title: Default Loader Plugin
---
import { Tabs, TabItem } from '@astrojs/starlight/components';
The default loader plugin is responsible for importing migration files written in JavaScript.
Migration files can be written using either CommonJS or ES Modules.
## Supported extensions
The default loader plugin supports the following extensions:
* `.js` - either CommonJS or ES Modules depending on your package.json's [`type` field](https://nodejs.org/api/packages.html#type)
* `.cjs` - CommonJS
* `.mjs` - ES Modules
## Supported exports
The default loader plugin supports the following exports:
### ES Modules
#### Default export
Exporting a function as the default export.
<Tabs>
<TabItem label="Async/Await">
```js
import { database } from 'some-database';
export default async function someMigration() {
await database.query(...);
await database.query(...);
}
```
</TabItem>
<TabItem label="Promises">
```js
import { database } from 'some-database';
export default function someMigration() {
// Remember to return the promise
return database.query(...)
.then(() => {
return database.query(...);
})
}
```
</TabItem>
<TabItem label="Callback">
```js
import { database } from 'some-database';
export default function someMigration(done) {
database.query(..., (err) => {
if (err) {
return done(err);
}
database.query(..., (err) => {
if (err) {
return done(err);
}
done();
});
});
}
```
</TabItem>
</Tabs>
#### Named export
Exporting a function named `up`.
<Tabs>
<TabItem label="Async/Await">
```js
import { database } from 'some-database';
export const up = async () => {
await database.query(...);
await database.query(...);
};
```
</TabItem>
<TabItem label="Promises">
```js
import { database } from 'some-database';
export const up = () => {
// Remember to return the promise
return database.query(...)
.then(() => {
return database.query(...);
})
};
```
</TabItem>
<TabItem label="Callback">
```js
import { database } from 'some-database';
export const up = (done) => {
database.query(..., (err) => {
if (err) {
return done(err);
}
database.query(..., (err) => {
if (err) {
return done(err);
}
done();
});
});
}
```
</TabItem>
</Tabs>
### CommonJS
#### `module.exports`
Exporting a function as the module.
<Tabs>
<TabItem label="Async/Await">
```js
const { database } = require('some-database');
module.exports = async function someMigration() {
await database.query(...);
await database.query(...);
}
```
</TabItem>
<TabItem label="Promises">
```js
const { database } = require('some-database');
module.exports = function someMigration() {
// Remember to return the promise
return database.query(...)
.then(() => {
return database.query(...);
})
}
```
</TabItem>
<TabItem label="Callback">
```js
const { database } = require('some-database');
module.exports = function someMigration(done) {
database.query(..., (err) => {
if (err) {
return done(err);
}
database.query(..., (err) => {
if (err) {
return done(err);
}
done();
});
});
}
```
</TabItem>
</Tabs>
#### `exports.up`
Exporting an `up` function.
<Tabs>
<TabItem label="Async/Await">
```js
const { database } = require('some-database');
exports.up = async () => {
await database.query(...);
await database.query(...);
};
```
</TabItem>
<TabItem label="Promises">
```js
const { database } = require('some-database');
exports.up = () => {
// Remember to return the promise
return database.query(...)
.then(() => {
return database.query(...);
})
};
```
</TabItem>
<TabItem label="Callback">
```js
const { database } = require('some-database');
exports.up = (done) => {
database.query(..., (err) => {
if (err) {
return done(err);
}
database.query(..., (err) => {
if (err) {
return done(err);
}
done();
});
});
}
```
</TabItem>
</Tabs>

32
docs/src/content/docs/loaders/index.mdx Normal file
View file

@ -0,0 +1,32 @@
---
title: Loader Plugins
---
import { LinkCard, CardGrid } from '@astrojs/starlight/components';
Loader plugins are used to transform any file type into a JavaScript function that will be called when the migration file is executed.
Out of the box, Emigrate supports the following file extensions: `.js`, `.cjs` and `.mjs`. And both CommonJS and ES Modules are supported. See the [Default Loader](/loaders/default/) for more information.
## Using a loader plugin
You can specify a loader plugin via the `--plugin` (or `-p` for short) option:
```bash
npx emigrate up --plugin mysql
```
Or set it up in your configuration file, see [Plugin configuration](/reference/configuration/#plugins) for more information.
:::tip[Did you know?]
You can specify multiple loader plugins at the same time, which is needed when you mix file types in your migrations.
For example, you can use the `mysql` loader for `.sql` files and the `typescript` loader for `.ts` files.
The [default loader](/loaders/default/) will be used for all other file types, and doesn't need to be specified.
:::
## Available Loader Plugins
<CardGrid>
<LinkCard title="Default Loader" href="/loaders/default/" description="The loader responsible for loading .js, .cjs and .mjs files" />
<LinkCard title="MySQL Loader" href="/loaders/mysql/" description="Can load and execute .sql files against a MySQL database" />
</CardGrid>

85
docs/src/content/docs/loaders/mysql.mdx Normal file
View file

@ -0,0 +1,85 @@
---
title: MySQL Loader Plugin
---
import { Tabs, TabItem } from '@astrojs/starlight/components';
The MySQL loader plugin transforms `.sql` files into JavaScript functions that Emigrate can use to execute the migrations.
## Installation
<Tabs>
<TabItem label="npm">
```bash
npm install @emigrate/mysql
```
</TabItem>
<TabItem label="pnpm">
```bash
pnpm add @emigrate/mysql
```
</TabItem>
<TabItem label="yarn">
```bash
yarn add @emigrate/mysql
```
</TabItem>
</Tabs>
## Configuration
The MySQL loader plugin can be configured either using environment variables or by configuring the plugin directly in the [`emigrate.config.js` file](/reference/configuration).
### Configuration file
```js title="emigrate.config.js" {1,4-8}
import { createMysqlLoader } from '@emigrate/mysql';
export default {
plugins: [
createMysqlLoader({
connection: { ... },
}),
],
};
```
#### Options
##### `connection` (required)
**type:** `object | string`
The connection options to use for connecting to the MySQL database when the SQL statements from the migration files are executed. This can either be a connection URI or an object with connection options.
For a list of supported connection options, see the [mysql documentation](https://github.com/mysqljs/mysql#connection-options).
### Environment variables
The following environment variables are supported:
| Variable | Description | Default |
| ---------------- | --------------------------------------------------------------------------------------------------- | -------------- |
| `MYSQL_URL` | The full URI for connecting to a MySQL database, e.g: `"mysql://user:pass@127.0.0.1:3306/database"` | |
| `MYSQL_HOST` | The host on which the MySQL server instance is running | `"localhost"` |
| `MYSQL_USER` | The MySQL user account to use for the authentication | |
| `MYSQL_PASSWORD` | The MySQL user password to use for the authentication | |
| `MYSQL_PORT` | The network port on which the MySQL server is listening | `3306` |
| `MYSQL_DATABASE` | The MySQL database to use for the connection | |
:::note
The `MYSQL_URL` environment variable takes precedence over the other environment variables. If `MYSQL_URL` is set, the other environment variables are ignored.
:::
The environment variables are used when the plugin is used using the `--plugin` command line option:
```bash
npx emigrate list --plugin mysql
```
Or when specifying the plugin in the [`emigrate.config.js` file](/reference/configuration) as a string:
```js title="emigrate.config.js" {2}
export default {
plugins: ['mysql'],
};
```

143
docs/src/content/docs/reference/configuration.mdx Normal file
View file

@ -0,0 +1,143 @@
---
title: Configuration Reference
description: How to configure Emigrate to your needs
sidebar:
order: 1
---
import { Tabs, TabItem } from '@astrojs/starlight/components';
Emigrate can be configured using a configuration file, and it uses [Cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) under the hood
so you can use a variety of formats and locations for your configuration file.
## Configure Emigrate
<Tabs>
<TabItem label="JavaScript">
```js title="emigrate.config.js"
/** @type {import('@emigrate/cli').EmigrateConfig} */
export default {
directory: 'migrations',
};
```
</TabItem>
<TabItem label="TypeScript">
```ts title="emigrate.config.ts"
import { type EmigrateConfig } from '@emigrate/cli';
const config: EmigrateConfig = {
directory: 'migrations',
};
export default config;
```
</TabItem>
</Tabs>
You can specify the following options:
### `directory`
**type:** `string`
Set the directory where your migrations are located, relative to the project root. This option is required by all Emigrate commands.
### `reporter`
**type:** `string | EmigrateReporter | Promise<EmigrateReporter> | (() => Promise<EmigrateReporter>)`
**default:** `"default"` - the default reporter
Set the reporter to use for the different commands. Specifying a reporter is most useful in a CI or production environment where you either ship logs or want to have a machine-readable format.
```js title="emigrate.config.js" {2}
export default {
reporter: 'json',
};
```
If you want to use different reporters for different commands, you can use an object:
```js title="emigrate.config.js" {2-4}
export default {
up: {
reporter: 'json',
},
};
```
:::note
Commands that are not specified will use the default reporter.
:::
:::tip[Did you know?]
The default reporter automatically detects if the current environment is an interactive terminal or not, and will only render animations and similar if it is.
:::
### `storage`
**type:** `string | EmigrateStorage | Promise<EmigrateStorage> | (() => Promise<EmigrateStorage>)`
Set the storage plugin to use for storing and reading the migration history. This option is required by all Emigrate commands except `new` which doesn't use it.
```js title="emigrate.config.js" {2}
export default {
storage: 'mysql',
};
```
:::note
Each storage plugin can have its own configuration options, see the corresponding [Storage Plugin](/storage/) section for more information.
:::
### `plugins`
**type:** `Array<string | EmigratePlugin | Promise<EmigratePlugin> | (() => Promise<EmigratePlugin>)>`
Set the plugins to use for the different commands. There are different types of plugins, and some are only useful for specific commands.
In short:
* [Loader Plugins](/loaders/) - are used for transforming non-JavaScript files into JavaScript files that can be executed by Node.js. These are only used by the `up` command.
* [Generator Plugins](/generators/) - are used for generating new migration files. These are only used by the `new` command.
```js title="emigrate.config.js" {2}
export default {
plugins: ['typescript'],
};
```
:::tip[Did you know?]
The same package can expose multiple plugins, so you can specify the plugin only once and it can be used as both a loader and a generator (and storage, in the case of [MySQL](/storage/mysql) for instance).
:::
### `template`
**type:** `string`
Set the path to a template file to use when creating new migrations. This option is only used by the `new` command.
```js title="emigrate.config.js" {2-4}
export default {
new: {
template: 'path/to/template.js',
},
};
```
The migration file will use the template file's extension, unless the [extension](#extension) option is set.
### `extension`
**type:** `string`
Set the extension to use for new migrations. This option is only used by the `new` command.
```js title="emigrate.config.js" {2-4}
export default {
new: {
extension: '.ts',
},
};
```
Will create new migration files with the `.ts` extension.

5
docs/src/content/docs/reporters/default.mdx Normal file
View file

@ -0,0 +1,5 @@
---
title: Default Reporter
---
Emigrate's default reporter.

24
docs/src/content/docs/reporters/index.mdx Normal file
View file

@ -0,0 +1,24 @@
---
title: Reporters
---
import { LinkCard, CardGrid } from '@astrojs/starlight/components';
A reporter is a plugin that's responsible for printing the migration progress and results to the console.
## Using a reporter
You can specify a reporter via the `--reporter` (or `-r` for short) option:
```bash
npx emigrate list --reporter pino
```
Or set it up in your configuration file, see [Reporter configuration](/reference/configuration/#reporter) for more information.
## Available Reporters
<CardGrid>
<LinkCard title="Default Reporter" href="/reporters/default/" />
<LinkCard title="Pino Reporter" href="/reporters/pino/" />
</CardGrid>

5
docs/src/content/docs/reporters/pino.mdx Normal file
View file

@ -0,0 +1,5 @@
---
title: Pino Reporter
---
Emigrate's reporter that uses [Pino](https://getpino.io/#/) as the logger.

53
docs/src/content/docs/storage/file-system.mdx Normal file
View file

@ -0,0 +1,53 @@
---
title: File System Storage
---
import { Tabs, TabItem } from '@astrojs/starlight/components';
The File System Storage is a storage driver that stores the migration history in a `.json` file on the local file system.
:::caution
This is suitable for simple setups, but for more advanced setups for instance where the application is deployed on multiple servers, you should use a database storage plugin instead.
:::
## Installation
<Tabs>
<TabItem label="npm">
```bash
npm install @emigrate/storage-fs
```
</TabItem>
<TabItem label="pnpm">
```bash
pnpm add @emigrate/storage-fs
```
</TabItem>
<TabItem label="yarn">
```bash
yarn add @emigrate/storage-fs
```
</TabItem>
</Tabs>
## Configuration
The File System Storage can be configured easily in your [`emigrate.config.js` file](/reference/configuration):
```js {1,4-6}
import storageFs from '@emigrate/storage-fs';
export default {
storage: storageFs({
filename: './migrations.json',
}),
};
```
### Options
#### `filename`
**type:** `string`
Should be a path either relative to the project root or an absolute path. It doesn't need to have the `.json` extension, but its contents will be in JSON format.

33
docs/src/content/docs/storage/index.mdx Normal file
View file

@ -0,0 +1,33 @@
---
title: Storage Plugins
---
import { LinkCard, CardGrid } from '@astrojs/starlight/components';
Storage plugins are used for storing and reading the migration history state.
Usually you'll want to store the migration history in the same database as the one which your migration files are targeting.
## Using a storage plugin
You can specify a storage plugin via the `--storage` (or `-s` for short) option:
```bash
npx emigrate list --storage mysql
```
Or set it up in your configuration file, see [Storage configuration](/reference/configuration/#storage) for more information.
## Available storage plugins
<CardGrid>
<LinkCard title="File System" href="/storage/file-system/" description="The most basic storage plugin - for simple setups" />
<LinkCard title="MySQL" href="/storage/mysql/" description="A storage plugin that uses a MySQL database for storing the migration history state" />
</CardGrid>
:::note
More storage plugins are coming soon!
:::
:::tip[Is your database missing?]
Writing a storage plugin is easy! Check out the [Storage Plugin API](/reference/storage-plugin-api/) for more information.
:::

92
docs/src/content/docs/storage/mysql.mdx Normal file
View file

@ -0,0 +1,92 @@
---
title: MySQL Storage
---
import { Tabs, TabItem } from '@astrojs/starlight/components';
The MySQL storage plugin uses a MySQL database to store the migration history (*duh*).
## Installation
<Tabs>
<TabItem label="npm">
```bash
npm install @emigrate/mysql
```
</TabItem>
<TabItem label="pnpm">
```bash
pnpm add @emigrate/mysql
```
</TabItem>
<TabItem label="yarn">
```bash
yarn add @emigrate/mysql
```
</TabItem>
</Tabs>
## Configuration
The MySQL storage can be configured either using environment variables or by configuring the plugin directly in the [`emigrate.config.js` file](/reference/configuration).
### Configuration file
```js title="emigrate.config.js" {1,4-7}
import { createMysqlStorage } from '@emigrate/mysql';
export default {
storage: createMysqlStorage({
table: 'migrations',
connection: { ... },
}),
};
```
#### Options
##### `table`
**type:** `string`
**default:** `"migrations"`
The name of the table to use for storing the migrations.
##### `connection` (required)
**type:** `object | string`
The connection options to use for connecting to the MySQL database. This can either be a connection URI or an object with connection options.
For a list of supported connection options, see the [mysql documentation](https://github.com/mysqljs/mysql#connection-options).
### Environment variables
The following environment variables are supported:
| Variable | Description | Default |
| ---------------- | --------------------------------------------------------------------------------------------------- | -------------- |
| `MYSQL_TABLE` | The name of the table to use for storing the migrations | `"migrations"` |
| `MYSQL_URL` | The full URI for connecting to a MySQL database, e.g: `"mysql://user:pass@127.0.0.1:3306/database"` | |
| `MYSQL_HOST` | The host on which the MySQL server instance is running | `"localhost"` |
| `MYSQL_USER` | The MySQL user account to use for the authentication | |
| `MYSQL_PASSWORD` | The MySQL user password to use for the authentication | |
| `MYSQL_PORT` | The network port on which the MySQL server is listening | `3306` |
| `MYSQL_DATABASE` | The MySQL database to use for the connection | |
:::note
The `MYSQL_URL` environment variable takes precedence over the other environment variables. If `MYSQL_URL` is set, the other environment variables are ignored, except for `MYSQL_TABLE`.
:::
The environment variables are used when the storage plugin is used using the `--storage` command line option:
```bash
npx emigrate list --storage mysql
```
Or when specifying the storage in the [`emigrate.config.js` file](/reference/configuration) as a string:
```js title="emigrate.config.js" {2}
export default {
storage: 'mysql',
};
```

3
docs/src/env.d.ts vendored Normal file
View file

@ -0,0 +1,3 @@
/* eslint-disable @typescript-eslint/triple-slash-reference */
/// <reference path="../.astro/types.d.ts" />
/// <reference types="astro/client" />