docs: add documentation for the commands: up, list, new and remove
This commit is contained in:
Joakim Carlstein
parent
c460ae7459
commit
2a82897ba8
6 changed files with 316 additions and 0 deletions
27
docs/src/components/PageTitle.astro
Normal file
27
docs/src/components/PageTitle.astro
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
---
|
||||
import type { Props } from '@astrojs/starlight/props';
|
||||
|
||||
const { title } = Astro.props.entry.data;
|
||||
const isCode = title.startsWith('`') && title.endsWith('`');
|
||||
---
|
||||
|
||||
<h1 id="_top">{isCode ? <code>{title.slice(1, -1)}</code> : title}</h1>
|
||||
|
||||
<style>
|
||||
h1 {
|
||||
margin-top: 1rem;
|
||||
font-size: var(--sl-text-h1);
|
||||
line-height: var(--sl-line-height-headings);
|
||||
font-weight: 600;
|
||||
color: var(--sl-color-white);
|
||||
}
|
||||
|
||||
code {
|
||||
font-family: var(--sl-font-system-mono);
|
||||
background-color: var(--sl-color-bg-inline-code);
|
||||
border: 1px solid var(--sl-color-gray-3);
|
||||
color: var(--sl-color-gray-1);
|
||||
padding: 0.25rem 0.5rem;
|
||||
border-radius: 0.25rem;
|
||||
}
|
||||
</style>
|
||||
55
docs/src/content/docs/commands/list.mdx
Normal file
55
docs/src/content/docs/commands/list.mdx
Normal file
|
|
@ -0,0 +1,55 @@
|
|||
---
|
||||
title: "`emigrate list`"
|
||||
description: "List migrations and their status."
|
||||
---
|
||||
|
||||
The `list` command is used to list _all_ migrations, i.e. both already run migrations and migrations that haven't been run yet.
|
||||
|
||||
Emigrate takes all migration files in the given directory that haven't been run yet and all migrations from the migration history.
|
||||
It then sorts the migrations by filename in ascending order and outputs them and their respective status one by one.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
emigrate list [options]
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
### `-h`, `--help`
|
||||
|
||||
Show command help and exit
|
||||
|
||||
### `-d`, `--directory <path>`
|
||||
|
||||
The directory where the migration files are located. The given path should be absolute or relative to the current working directory.
|
||||
|
||||
### `-s`, `--storage <name>`
|
||||
|
||||
The storage to use for where to read the migration history.
|
||||
|
||||
The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:
|
||||
|
||||
- `@emigrate/storage-`
|
||||
- `emigrate-storage-`
|
||||
- `@emigrate/plugin-storage-`
|
||||
- `@emigrate/`
|
||||
|
||||
And then try to load the module/package with the given name.
|
||||
|
||||
For example, if you want to use the `emigrate-storage-somedb` package, you can specify either `emigrate-storage-somedb` or just `somedb` as the name.
|
||||
In case you have both a `emigrate-storage-somedb` and a `somedb` package installed, the `emigrate-storage-somedb` package will be used.
|
||||
|
||||
### `-r`, `--reporter <name>`
|
||||
|
||||
The reporter to use for listing the migrations.
|
||||
|
||||
The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:
|
||||
|
||||
- `@emigrate/reporter-`
|
||||
- `emigrate-reporter-`
|
||||
- `@emigrate/`
|
||||
|
||||
And then try to load the module/package with the given name.
|
||||
|
||||
For example, if you want to use the `emigrate-reporter-somereporter` package, you can specify either `emigrate-reporter-somereporter` or just `somereporter` as the name.
|
||||
72
docs/src/content/docs/commands/new.mdx
Normal file
72
docs/src/content/docs/commands/new.mdx
Normal file
|
|
@ -0,0 +1,72 @@
|
|||
---
|
||||
title: "`emigrate new`"
|
||||
description: "Create new migration."
|
||||
---
|
||||
|
||||
The `new` command is used to create a new migration file in the given directory.
|
||||
|
||||
The migration file can be based on a template, generated by a [generator plugin](/plugins/generators/), or just be an empty file.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
emigrate new [options] <name>
|
||||
```
|
||||
|
||||
## Arguments
|
||||
|
||||
### `<name>`
|
||||
|
||||
The name of the migration. The name will be used to generate the migration filename.
|
||||
|
||||
The name can be provided as a single argument or as multiple arguments.
|
||||
If multiple arguments are provided, the arguments will be joined with a space before being passed to the filename generator (the default filename generator replaces all whitespace and non-path safe characters with underscores).
|
||||
|
||||
## Options
|
||||
|
||||
### `-h`, `--help`
|
||||
|
||||
Show command help and exit
|
||||
|
||||
### `-d`, `--directory <path>`
|
||||
|
||||
The directory where the migration files are located. The given path should be absolute or relative to the current working directory.
|
||||
|
||||
### `-t`, `--template <path>`
|
||||
|
||||
The template file to use for generating the migration file. The given path should be absolute or relative to the current working directory.
|
||||
|
||||
The template can contain a `{{name}}` placeholder which will be replaced with the migration name provided to the command. The generated file will have the same extension as the template file, unless the [`--extension`](#e---extension-ext) option is used.
|
||||
|
||||
### `-e`, `--extension <ext>`
|
||||
|
||||
The extension to use for the migration file. Unless the [`--template`](#t---template-path) option is also specified the file will be empty.
|
||||
|
||||
### `-p`, `--plugin <name>`
|
||||
|
||||
The [generator plugin](/plugins/generators/) to use. The generator plugin is responsible for generating the migration filename and its contents.
|
||||
|
||||
The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:
|
||||
|
||||
- `@emigrate/plugin-`
|
||||
- `emigrate-plugin-`
|
||||
- `@emigrate/`
|
||||
|
||||
And then try to load the module/package with the given name.
|
||||
|
||||
For example, if you want to use the `emigrate-plugin-someplugin` package, you can specify either `emigrate-plugin-someplugin` or just `someplugin` as the name.
|
||||
In case you have both a `emigrate-plugin-someplugin` and a `someplugin` package installed, the `emigrate-plugin-someplugin` package will be used.
|
||||
|
||||
### `-r`, `--reporter <name>`
|
||||
|
||||
The reporter to use for listing the migrations.
|
||||
|
||||
The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:
|
||||
|
||||
- `@emigrate/reporter-`
|
||||
- `emigrate-reporter-`
|
||||
- `@emigrate/`
|
||||
|
||||
And then try to load the module/package with the given name.
|
||||
|
||||
For example, if you want to use the `emigrate-reporter-somereporter` package, you can specify either `emigrate-reporter-somereporter` or just `somereporter` as the name.
|
||||
62
docs/src/content/docs/commands/remove.mdx
Normal file
62
docs/src/content/docs/commands/remove.mdx
Normal file
|
|
@ -0,0 +1,62 @@
|
|||
---
|
||||
title: "`emigrate remove`"
|
||||
description: "Remove a migration from the history."
|
||||
---
|
||||
|
||||
The `remove` command is used to remove a migration from the history. This is useful if you want to retry a migration that has failed.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
emigrate remove [options] <name>
|
||||
```
|
||||
|
||||
## Arguments
|
||||
|
||||
### `<name>`
|
||||
|
||||
The name of the migration file to remove, including the extension, e.g. `20200101000000_some_migration.js`.
|
||||
|
||||
## Options
|
||||
|
||||
### `-h`, `--help`
|
||||
|
||||
Show command help and exit
|
||||
|
||||
### `-d`, `--directory <path>`
|
||||
|
||||
The directory where the migration files are located. The given path should be absolute or relative to the current working directory.
|
||||
|
||||
### `-f`, `--force`
|
||||
|
||||
Force removal of the migration history entry even if the migration file does not exist or it's in a non-failed state.
|
||||
|
||||
### `-s`, `--storage <name>`
|
||||
|
||||
The storage to use for where to read the migration history.
|
||||
|
||||
The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:
|
||||
|
||||
- `@emigrate/storage-`
|
||||
- `emigrate-storage-`
|
||||
- `@emigrate/plugin-storage-`
|
||||
- `@emigrate/`
|
||||
|
||||
And then try to load the module/package with the given name.
|
||||
|
||||
For example, if you want to use the `emigrate-storage-somedb` package, you can specify either `emigrate-storage-somedb` or just `somedb` as the name.
|
||||
In case you have both a `emigrate-storage-somedb` and a `somedb` package installed, the `emigrate-storage-somedb` package will be used.
|
||||
|
||||
### `-r`, `--reporter <name>`
|
||||
|
||||
The reporter to use for listing the migrations.
|
||||
|
||||
The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:
|
||||
|
||||
- `@emigrate/reporter-`
|
||||
- `emigrate-reporter-`
|
||||
- `@emigrate/`
|
||||
|
||||
And then try to load the module/package with the given name.
|
||||
|
||||
For example, if you want to use the `emigrate-reporter-somereporter` package, you can specify either `emigrate-reporter-somereporter` or just `somereporter` as the name.
|
||||
76
docs/src/content/docs/commands/up.mdx
Normal file
76
docs/src/content/docs/commands/up.mdx
Normal file
|
|
@ -0,0 +1,76 @@
|
|||
---
|
||||
title: "`emigrate up`"
|
||||
description: "Run migrations"
|
||||
---
|
||||
|
||||
The `up` command is used to either list or run all pending migrations, i.e. migrations that haven't been run yet.
|
||||
|
||||
Emigrate takes all migration files in the given directory and compares them to the migration history so that it knows which migrations are pending.
|
||||
It then sorts the pending migrations by filename in ascending order and runs them one by one.
|
||||
|
||||
If any of the migrations fail, the command will be aborted and the rest of the migrations will not be run.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
emigrate up [options]
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
### `-h`, `--help`
|
||||
|
||||
Show command help and exit
|
||||
|
||||
### `--dry`
|
||||
|
||||
List the pending migrations that would be run without actually running them
|
||||
|
||||
### `-d`, `--directory <path>`
|
||||
|
||||
The directory where the migration files are located. The given path should be absolute or relative to the current working directory.
|
||||
|
||||
### `-s`, `--storage <name>`
|
||||
|
||||
The storage to use for where to store the migration history.
|
||||
|
||||
The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:
|
||||
|
||||
- `@emigrate/storage-`
|
||||
- `emigrate-storage-`
|
||||
- `@emigrate/plugin-storage-`
|
||||
- `@emigrate/`
|
||||
|
||||
And then try to load the module/package with the given name.
|
||||
|
||||
For example, if you want to use the `emigrate-storage-somedb` package, you can specify either `emigrate-storage-somedb` or just `somedb` as the name.
|
||||
In case you have both a `emigrate-storage-somedb` and a `somedb` package installed, the `emigrate-storage-somedb` package will be used.
|
||||
|
||||
### `-p`, `--plugin <name>`
|
||||
|
||||
The [loader plugin(s)](/plugins/loaders/) to use. Can be specified multiple times to use multiple plugins.
|
||||
|
||||
The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:
|
||||
|
||||
- `@emigrate/plugin-`
|
||||
- `emigrate-plugin-`
|
||||
- `@emigrate/`
|
||||
|
||||
And then try to load the module/package with the given name.
|
||||
|
||||
For example, if you want to use the `emigrate-plugin-someplugin` package, you can specify either `emigrate-plugin-someplugin` or just `someplugin` as the name.
|
||||
In case you have both a `emigrate-plugin-someplugin` and a `someplugin` package installed, the `emigrate-plugin-someplugin` package will be used.
|
||||
|
||||
### `-r`, `--reporter <name>`
|
||||
|
||||
The reporter to use for reporting the migration progress.
|
||||
|
||||
The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:
|
||||
|
||||
- `@emigrate/reporter-`
|
||||
- `emigrate-reporter-`
|
||||
- `@emigrate/`
|
||||
|
||||
And then try to load the module/package with the given name.
|
||||
|
||||
For example, if you want to use the `emigrate-reporter-somereporter` package, you can specify either `emigrate-reporter-somereporter` or just `somereporter` as the name.
|
||||
Loading…
Add table
Add a link
Reference in a new issue