Refactor docs (#510)

Signed-off-by: Alexis Rico <[email protected]>

---------

Signed-off-by: Alexis Rico <[email protected]>
Co-authored-by: Andrew Farries <[email protected]>

Author: SferaDev

docs/cli-reference.md

@@ -0,0 +1,19 @@
+# Command line reference
+
+The `pgroll` CLI has the following top-level flags:
+
+- `--postgres-url`: The URL of the postgres instance against which migrations will be run.
+- `--schema`: The Postgres schema in which migrations will be run (default `"public"`).
+- `--pgroll-schema`: The Postgres schema in which `pgroll` will store its internal state (default: `"pgroll"`). One `--pgroll-schema` may be used safely with multiple `--schema`s.
+- `--lock-timeout`: The Postgres `lock_timeout` value to use for all `pgroll` DDL operations, specified in milliseconds (default `500`).
+- `--role`: The Postgres role to use for all `pgroll` DDL operations (default: `""`, which doesn't set any role).
+
+Each of these flags can also be set via an environment variable:
+
+- `PGROLL_PG_URL`
+- `PGROLL_SCHEMA`
+- `PGROLL_STATE_SCHEMA`
+- `PGROLL_LOCK_TIMEOUT`
+- `PGROLL_ROLE`
+
+The CLI flag takes precedence if a flag is set via both an environment variable and a CLI flag.

docs/cli/README.md

@@ -0,0 +1,23 @@
+---
+title: Complete
+description: Complete a pgroll migration, removing the previous schema and leaving only the latest schema.
+---
+
+## Command
+
+```
+$ pgroll complete
+```
+
+This completes the most recently started migration.
+
+Running `pgroll complete` when there is no migration in progress is a no-op.
+
+Completing a `pgroll` migration removes the previous schema version from the database (e.g. `public_02_create_table`), leaving only the latest version of the schema (e.g. `public_03_add_column`). At this point, any temporary columns and triggers created on the affected tables in the `public` schema will also be cleaned up, leaving the table schema in its final state. Note that the real schema (e.g. `public`) should never be used directly by the client as that is not safe; instead, clients should use the schemas with versioned views (e.g. `public_03_add_column`).
+
+<Warning>
+  Before running `pgroll complete` ensure that all applications that depend on
+  the old version of the database schema are no longer live. Prematurely running
+  `pgroll complete` can cause downtime of old application instances that depend
+  on the old schema.
+</Warning>

docs/cli/complete.mdx

@@ -0,0 +1,14 @@
+---
+title: Init
+description: Initializes pgroll for first use.
+---
+
+## Command
+
+```
+$ pgroll init
+```
+
+This will create a new schema in the database called `pgroll` (or whatever value is specified with the `--pgroll-schema` switch).
+
+The tables and functions in this schema store `pgroll`'s internal state and are not intended to be modified outside of `pgroll` CLI.

docs/cli/init.mdx

@@ -0,0 +1,42 @@
+---
+title: Latest
+description: Prints the latest schema version in either the target database or a local directory of migration files.
+---
+
+## Command
+
+By default, `pgroll latest` prints the latest version in the target database. Use the `--local` flag to print the latest version in a local directory of migration files instead.
+
+In both cases, the `--with-schema` flag can be used to prefix the latest version with the schema name.
+
+### Database
+
+Assuming that the [example migrations](https://github.com/xataio/pgroll/tree/main/examples) have been applied to the `public` schema in the target database, running:
+
+```
+$ pgroll latest
+```
+
+will print the latest version in the target database:
+
+```
+45_add_table_check_constraint
+```
+
+The exact output will vary as the `examples/` directory is updated.
+
+### Local
+
+Assuming that the [example migrations](https://github.com/xataio/pgroll/tree/main/examples) are on disk in a directory called `examples`, running:
+
+```
+$ pgroll latest --local examples/
+```
+
+will print the latest migration in the directory:
+
+```
+45_add_table_check_constraint
+```
+
+The exact output will vary as the `examples/` directory is updated.

docs/cli/latest.mdx

@@ -0,0 +1,16 @@
+---
+title: Migrate
+description: Applies all outstanding migrations from a directory to the target database.
+---
+
+## Command
+
+Assuming that migrations up to and including migration `40_create_enum_type` from the [example migrations](https://github.com/xataio/pgroll/tree/main/examples) directory have been applied, running:
+
+```
+$ pgroll migrate examples/
+```
+
+will apply migrations from `41_add_enum_column` onwards to the target database.
+
+If the `--complete` flag is passed to `pgroll migrate` the final migration to be applied will be completed. Otherwise the final migration will be left active (started but not completed).

docs/cli/migrate.mdx

@@ -0,0 +1,44 @@
+---
+title: Pull
+description: Pull the complete schema history of applied migrations from the target database and write the migrations to disk.
+---
+
+## Command
+
+Assuming that all [example migrations](https://github.com/xataio/pgroll/tree/main/examples) have been applied, running:
+
+```
+$ pgroll pull migrations/
+```
+
+will write the complete schema history as `.json` files to the `migrations/` directory:
+
+```
+$ ls migrations/
+
+01_create_tables.json
+02_create_another_table.json
+03_add_column_to_products.json
+04_rename_table.json
+05_sql.json
+06_add_column_to_sql_table.json
+...
+```
+
+The command takes an optional `--with-prefixes` flag which will write each filename prefixed with its position in the schema history:
+
+```
+$ ls migrations/
+
+0001_01_create_tables.json
+0002_02_create_another_table.json
+0003_03_add_column_to_products.json
+0004_04_rename_table.json
+0005_05_sql.json
+0006_06_add_column_to_sql_table.json
+...
+```
+
+The `--with-prefixes` flag ensures that files are sorted lexicographically by their time of application.
+
+If the directory specified as the required argument to `pgroll pull` does not exist, `pgroll pull` will create it.