From 2a82897ba8cdd353c72d1d3319cdb0a9863c0c08 Mon Sep 17 00:00:00 2001 From: Joakim Carlstein Date: Mon, 18 Dec 2023 11:55:32 +0100 Subject: [PATCH] docs: add documentation for the commands: up, list, new and remove --- docs/astro.config.mjs | 24 +++++++ docs/src/components/PageTitle.astro | 27 ++++++++ docs/src/content/docs/commands/list.mdx | 55 ++++++++++++++++ docs/src/content/docs/commands/new.mdx | 72 +++++++++++++++++++++ docs/src/content/docs/commands/remove.mdx | 62 ++++++++++++++++++ docs/src/content/docs/commands/up.mdx | 76 +++++++++++++++++++++++ 6 files changed, 316 insertions(+) create mode 100644 docs/src/components/PageTitle.astro create mode 100644 docs/src/content/docs/commands/list.mdx create mode 100644 docs/src/content/docs/commands/new.mdx create mode 100644 docs/src/content/docs/commands/remove.mdx create mode 100644 docs/src/content/docs/commands/up.mdx diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index c91251a..fdbadee 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -12,6 +12,9 @@ export default defineConfig({ editLink: { baseUrl: 'https://github.com/aboviq/emigrate/edit/main/docs/', }, + components: { + PageTitle: './src/components/PageTitle.astro', + }, sidebar: [ { label: 'Introduction', @@ -26,6 +29,27 @@ export default defineConfig({ }, ], }, + { + label: 'Commands', + items: [ + { + label: 'emigrate up', + link: '/commands/up/', + }, + { + label: 'emigrate list', + link: '/commands/list/', + }, + { + label: 'emigrate new', + link: '/commands/new/', + }, + { + label: 'emigrate remove', + link: '/commands/remove/', + }, + ], + }, { label: 'Plugins', items: [ diff --git a/docs/src/components/PageTitle.astro b/docs/src/components/PageTitle.astro new file mode 100644 index 0000000..76e9e02 --- /dev/null +++ b/docs/src/components/PageTitle.astro @@ -0,0 +1,27 @@ +--- +import type { Props } from '@astrojs/starlight/props'; + +const { title } = Astro.props.entry.data; +const isCode = title.startsWith('`') && title.endsWith('`'); +--- + +

{isCode ? {title.slice(1, -1)} : title}

+ + diff --git a/docs/src/content/docs/commands/list.mdx b/docs/src/content/docs/commands/list.mdx new file mode 100644 index 0000000..c17dedb --- /dev/null +++ b/docs/src/content/docs/commands/list.mdx @@ -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 ` + +The directory where the migration files are located. The given path should be absolute or relative to the current working directory. + +### `-s`, `--storage ` + +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 ` + +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. diff --git a/docs/src/content/docs/commands/new.mdx b/docs/src/content/docs/commands/new.mdx new file mode 100644 index 0000000..48ca2be --- /dev/null +++ b/docs/src/content/docs/commands/new.mdx @@ -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] +``` + +## Arguments + +### `` + +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 ` + +The directory where the migration files are located. The given path should be absolute or relative to the current working directory. + +### `-t`, `--template ` + +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 ` + +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 ` + +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 ` + +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. diff --git a/docs/src/content/docs/commands/remove.mdx b/docs/src/content/docs/commands/remove.mdx new file mode 100644 index 0000000..dca59ae --- /dev/null +++ b/docs/src/content/docs/commands/remove.mdx @@ -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] +``` + +## Arguments + +### `` + +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 ` + +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 ` + +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 ` + +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. diff --git a/docs/src/content/docs/commands/up.mdx b/docs/src/content/docs/commands/up.mdx new file mode 100644 index 0000000..78aea06 --- /dev/null +++ b/docs/src/content/docs/commands/up.mdx @@ -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 ` + +The directory where the migration files are located. The given path should be absolute or relative to the current working directory. + +### `-s`, `--storage ` + +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 ` + +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 ` + +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.