From 06e69c2340618430742897652c284523f6ad3932 Mon Sep 17 00:00:00 2001 From: Alexis Rico Date: Thu, 5 Dec 2024 13:13:39 +0100 Subject: [PATCH] Refactor docs (#510) Signed-off-by: Alexis Rico --------- Signed-off-by: Alexis Rico Co-authored-by: Andrew Farries --- docs/cli-reference.md | 232 ------- docs/cli/README.md | 19 + docs/cli/complete.mdx | 23 + docs/cli/init.mdx | 14 + docs/cli/latest.mdx | 42 ++ docs/cli/migrate.mdx | 16 + docs/cli/pull.mdx | 44 ++ docs/cli/rollback.mdx | 23 + docs/cli/start.mdx | 31 + docs/cli/status.mdx | 44 ++ docs/config.json | 191 +++++- docs/operations-reference.md | 642 ------------------ docs/operations/README.md | 10 + docs/operations/add_column.mdx | 55 ++ docs/operations/alter_column/README.md | 5 + .../alter_column/add_check_constraint.mdx | 25 + .../alter_column/add_foreign_key.mdx | 27 + .../alter_column/add_not_null_constraint.mdx | 22 + .../alter_column/add_unique_constraint.mdx | 24 + .../alter_column/change_comment.mdx | 24 + .../alter_column/change_default.mdx | 24 + docs/operations/alter_column/change_type.mdx | 22 + .../alter_column/drop_not_null_constraint.mdx | 22 + .../operations/alter_column/rename_column.mdx | 20 + docs/operations/create_constraint.mdx | 47 ++ docs/operations/create_index.mdx | 35 + docs/operations/create_table.mdx | 64 ++ docs/operations/drop_column.mdx | 26 + docs/operations/drop_constraint.mdx | 33 + docs/operations/drop_index.mdx | 18 + .../drop_multi_column_constraint.mdx | 29 + docs/operations/drop_table.mdx | 18 + docs/operations/raw_sql.mdx | 43 ++ docs/operations/rename_constraint.mdx | 20 + docs/operations/rename_table.mdx | 19 + docs/operations/set_replica_identity.mdx | 34 + 36 files changed, 1099 insertions(+), 888 deletions(-) delete mode 100644 docs/cli-reference.md create mode 100644 docs/cli/README.md create mode 100644 docs/cli/complete.mdx create mode 100644 docs/cli/init.mdx create mode 100644 docs/cli/latest.mdx create mode 100644 docs/cli/migrate.mdx create mode 100644 docs/cli/pull.mdx create mode 100644 docs/cli/rollback.mdx create mode 100644 docs/cli/start.mdx create mode 100644 docs/cli/status.mdx delete mode 100644 docs/operations-reference.md create mode 100644 docs/operations/README.md create mode 100644 docs/operations/add_column.mdx create mode 100644 docs/operations/alter_column/README.md create mode 100644 docs/operations/alter_column/add_check_constraint.mdx create mode 100644 docs/operations/alter_column/add_foreign_key.mdx create mode 100644 docs/operations/alter_column/add_not_null_constraint.mdx create mode 100644 docs/operations/alter_column/add_unique_constraint.mdx create mode 100644 docs/operations/alter_column/change_comment.mdx create mode 100644 docs/operations/alter_column/change_default.mdx create mode 100644 docs/operations/alter_column/change_type.mdx create mode 100644 docs/operations/alter_column/drop_not_null_constraint.mdx create mode 100644 docs/operations/alter_column/rename_column.mdx create mode 100644 docs/operations/create_constraint.mdx create mode 100644 docs/operations/create_index.mdx create mode 100644 docs/operations/create_table.mdx create mode 100644 docs/operations/drop_column.mdx create mode 100644 docs/operations/drop_constraint.mdx create mode 100644 docs/operations/drop_index.mdx create mode 100644 docs/operations/drop_multi_column_constraint.mdx create mode 100644 docs/operations/drop_table.mdx create mode 100644 docs/operations/raw_sql.mdx create mode 100644 docs/operations/rename_constraint.mdx create mode 100644 docs/operations/rename_table.mdx create mode 100644 docs/operations/set_replica_identity.mdx diff --git a/docs/cli-reference.md b/docs/cli-reference.md deleted file mode 100644 index e741ab4d..00000000 --- a/docs/cli-reference.md +++ /dev/null @@ -1,232 +0,0 @@ -# Command line reference - -This document describes the `pgroll` CLI and its subcommands. - -The `pgroll` CLI offers the following subcommands: -* [init](#init) -* [start](#start) -* [complete](#complete) -* [rollback](#rollback) -* [status](#status) -* [migrate](#migrate) -* [latest](#latest) -* [pull](#pull) - -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. - -### Init - -`pgroll init` initializes `pgroll` for first use. - -``` -$ 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. - -### Start - -`pgroll start` starts a `pgroll` migration: - -``` -$ pgroll start sql/03_add_column.json -``` - -This starts the migration defined in the `sql/03_add_column.json` file. - -After starting a migration there will be two schema versions in the database; one for the old schema before the migration (e.g. `public_02_create_table`) and one for the new version with the schema changes (e.g. `public_03_add_column`). Each of these schemas merely contains views on the tables in the `public` schema. - -#### Using `pgroll start` with the `--complete` flag - -A migration can be started and completed with one command by specifying the `--complete` flag: - -``` -$ pgroll start sql/03_add_column.json --complete -``` - -This is equivalent to running `pgroll start` immediately followed by `pgroll complete`. - -:warning: Using the `--complete` flag is appropriate only when there are no applications running against the old database schema. In most cases, the recommended workflow is to run `pgroll start`, then gracefully shut down old applications before running `pgroll complete` as a separate step. - -### Complete - -`pgroll complete` completes a `pgroll` migration, removing the previous schema and leaving only the latest schema. - -``` -$ 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. - -### Rollback - -`pgroll rollback` rolls back the currently active migration. - -``` -$ pgroll rollback -``` - -This rolls back the currently active migration (an active migration is one that has been started but not yet completed). - -Rolling back a `pgroll` migration means removing the new schema version. The old schema version was still present throughout the migration period and does not require modification. - -Migrations cannot be rolled back once completed. Attempting to roll back a migration that has already been completed is a no-op. - -:warning: Before running `pgroll rollback` ensure that any new versions of applications that depend on the new database schema are no longer live. Prematurely running `pgroll rollback` can cause downtime of new application instances that depend on the new schema. - - -### Migrate - -`pgroll migrate` applies all outstanding migrations from a directory to the target database. - -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). - -### Latest - -`pgroll latest` prints the latest schema version in either the target database or a local directory of migration files. - -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. - -### Status - -`pgroll status` shows the current status of `pgroll` within a given schema: - -``` -$ pgroll status -``` -```json -{ - "Schema": "public", - "Version": "27_drop_unique_constraint", - "Status": "Complete" -} -``` - -The status field can be one of the following values: -* `"No migrations"` - no migrations have been applied in this schema yet. -* `"In progress"` - a migration has been started, but not yet completed. -* `"Complete"` - the most recent migration was completed. - -The `Version` field gives the name of the latest schema version. - -If a migration is `In progress` the schemas for both the latest version indicated by the `Version` field and the previous version will exist in the database. - -If a migration is `Complete` only the latest version of the schema will exist in the database. - -The top-level `--schema` flag can be used to view the status of `pgroll` in a different schema: - -``` -$ pgroll status --schema schema_a -``` -```json -{ - "Schema": "schema_a", - "Version": "01_create_tables", - "Status": "Complete" -} -``` - -### Pull - -`pgroll pull` pulls the complete schema history of applied migrations from the target database and writes the migrations to disk. - -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. diff --git a/docs/cli/README.md b/docs/cli/README.md new file mode 100644 index 00000000..317d25f7 --- /dev/null +++ b/docs/cli/README.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. diff --git a/docs/cli/complete.mdx b/docs/cli/complete.mdx new file mode 100644 index 00000000..c42b2f29 --- /dev/null +++ b/docs/cli/complete.mdx @@ -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`). + + + 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. + diff --git a/docs/cli/init.mdx b/docs/cli/init.mdx new file mode 100644 index 00000000..3ee185af --- /dev/null +++ b/docs/cli/init.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. diff --git a/docs/cli/latest.mdx b/docs/cli/latest.mdx new file mode 100644 index 00000000..e19ad35e --- /dev/null +++ b/docs/cli/latest.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. diff --git a/docs/cli/migrate.mdx b/docs/cli/migrate.mdx new file mode 100644 index 00000000..ea0dcbb6 --- /dev/null +++ b/docs/cli/migrate.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). diff --git a/docs/cli/pull.mdx b/docs/cli/pull.mdx new file mode 100644 index 00000000..44a10e6d --- /dev/null +++ b/docs/cli/pull.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. diff --git a/docs/cli/rollback.mdx b/docs/cli/rollback.mdx new file mode 100644 index 00000000..7c78aa1a --- /dev/null +++ b/docs/cli/rollback.mdx @@ -0,0 +1,23 @@ +--- +title: Rollback +description: Roll back the currently active migration. +--- + +## Command + +``` +$ pgroll rollback +``` + +This rolls back the currently active migration (an active migration is one that has been started but not yet completed). + +Rolling back a `pgroll` migration means removing the new schema version. The old schema version was still present throughout the migration period and does not require modification. + +Migrations cannot be rolled back once completed. Attempting to roll back a migration that has already been completed is a no-op. + + + Before running `pgroll rollback` ensure that any new versions of applications + that depend on the new database schema are no longer live. Prematurely running + `pgroll rollback` can cause downtime of new application instances that depend + on the new schema. + diff --git a/docs/cli/start.mdx b/docs/cli/start.mdx new file mode 100644 index 00000000..f5e2a2ec --- /dev/null +++ b/docs/cli/start.mdx @@ -0,0 +1,31 @@ +--- +title: Start +description: Start a pgroll migration +--- + +## Command + +``` +$ pgroll start sql/03_add_column.json +``` + +This starts the migration defined in the `sql/03_add_column.json` file. + +After starting a migration there will be two schema versions in the database; one for the old schema before the migration (e.g. `public_02_create_table`) and one for the new version with the schema changes (e.g. `public_03_add_column`). Each of these schemas merely contains views on the tables in the `public` schema. + +### Using `pgroll start` with the `--complete` flag + +A migration can be started and completed with one command by specifying the `--complete` flag: + +``` +$ pgroll start sql/03_add_column.json --complete +``` + +This is equivalent to running `pgroll start` immediately followed by `pgroll complete`. + + + Using the `--complete` flag is appropriate only when there are no applications + running against the old database schema. In most cases, the recommended + workflow is to run `pgroll start`, then gracefully shut down old applications + before running `pgroll complete` as a separate step. + diff --git a/docs/cli/status.mdx b/docs/cli/status.mdx new file mode 100644 index 00000000..78bb759f --- /dev/null +++ b/docs/cli/status.mdx @@ -0,0 +1,44 @@ +--- +title: Status +description: Show the current status of pgroll within a given schema. +--- + +## Command + +``` +$ pgroll status +``` + +```json +{ + "Schema": "public", + "Version": "27_drop_unique_constraint", + "Status": "Complete" +} +``` + +The status field can be one of the following values: + +- `"No migrations"` - no migrations have been applied in this schema yet. +- `"In progress"` - a migration has been started, but not yet completed. +- `"Complete"` - the most recent migration was completed. + +The `Version` field gives the name of the latest schema version. + +If a migration is `In progress` the schemas for both the latest version indicated by the `Version` field and the previous version will exist in the database. + +If a migration is `Complete` only the latest version of the schema will exist in the database. + +The top-level `--schema` flag can be used to view the status of `pgroll` in a different schema: + +``` +$ pgroll status --schema schema_a +``` + +```json +{ + "Schema": "schema_a", + "Version": "01_create_tables", + "Status": "Complete" +} +``` diff --git a/docs/config.json b/docs/config.json index 59faf099..86bea7ea 100644 --- a/docs/config.json +++ b/docs/config.json @@ -1,24 +1,187 @@ { - "routes": [ + "routes": [ + { + "title": "Getting started", + "href": "/getting-started", + "file": "docs/getting-started.md" + }, + { + "title": "Tutorial", + "href": "/tutorial", + "file": "docs/tutorial.md" + }, + { + "title": "Command-line interface", + "href": "/cli", + "file": "docs/cli/README.md", + "items": [ { - "title": "Getting Started", - "href": "/getting-started", - "file": "docs/getting-started.md" + "title": "Init", + "href": "/cli/init", + "file": "docs/cli/init.mdx" }, { - "title": "Tutorial", - "href": "/tutorial", - "file": "docs/tutorial.md" + "title": "Start", + "href": "/cli/start", + "file": "docs/cli/start.mdx" }, { - "title": "Command-line Reference", - "href": "/cli-reference", - "file": "docs/cli-reference.md" + "title": "Complete", + "href": "/cli/complete", + "file": "docs/cli/complete.mdx" }, { - "title": "Operations Reference", - "href": "/operations-reference", - "file": "docs/operations-reference.md" + "title": "Rollback", + "href": "/cli/rollback", + "file": "docs/cli/rollback.mdx" + }, + { + "title": "Status", + "href": "/cli/status", + "file": "docs/cli/status.mdx" + }, + { + "title": "Migrate", + "href": "/cli/migrate", + "file": "docs/cli/migrate.mdx" + }, + { + "title": "Latest", + "href": "/cli/latest", + "file": "docs/cli/latest.mdx" + }, + { + "title": "Pull", + "href": "/cli/pull", + "file": "docs/cli/pull.mdx" + } + ] + }, + { + "title": "Operations", + "href": "/operations", + "file": "docs/operations/README.md", + "noLink": true, + "items": [ + { + "title": "Add column", + "href": "/operations/add_column", + "file": "docs/operations/add_column.mdx" + }, + { + "title": "Alter column", + "href": "/operations/alter_column", + "file": "docs/operations/alter_column/README.md", + "noLink": true, + "items": [ + { + "title": "Rename column", + "href": "/operations/alter_column/rename_column", + "file": "docs/operations/alter_column/rename_column.mdx" + }, + { + "title": "Change type", + "href": "/operations/alter_column/change_type", + "file": "docs/operations/alter_column/change_type.mdx" + }, + { + "title": "Change default", + "href": "/operations/alter_column/change_default", + "file": "docs/operations/alter_column/change_default.mdx" + }, + { + "title": "Change comment", + "href": "/operations/alter_column/change_comment", + "file": "docs/operations/alter_column/change_comment.mdx" + }, + { + "title": "Add check constraint", + "href": "/operations/alter_column/add_check_constraint", + "file": "docs/operations/alter_column/add_check_constraint.mdx" + }, + { + "title": "Add foreign key", + "href": "/operations/alter_column/add_foreign_key", + "file": "docs/operations/alter_column/add_foreign_key.mdx" + }, + { + "title": "Add not null constraint", + "href": "/operations/alter_column/add_not_null_constraint", + "file": "docs/operations/alter_column/add_not_null_constraint.mdx" + }, + { + "title": "Drop not null constraint", + "href": "/operations/alter_column/drop_not_null_constraint", + "file": "docs/operations/alter_column/drop_not_null_constraint.mdx" + }, + { + "title": "Add unique constraint", + "href": "/operations/alter_column/add_unique_constraint", + "file": "docs/operations/alter_column/add_unique_constraint.mdx" + } + ] + }, + { + "title": "Create index", + "href": "/operations/create_index", + "file": "docs/operations/create_index.mdx" + }, + { + "title": "Create table", + "href": "/operations/create_table", + "file": "docs/operations/create_table.mdx" + }, + { + "title": "Create constraint", + "href": "/operations/create_constraint", + "file": "docs/operations/create_constraint.mdx" + }, + { + "title": "Drop column", + "href": "/operations/drop_column", + "file": "docs/operations/drop_column.mdx" + }, + { + "title": "Drop constraint (deprecated)", + "href": "/operations/drop_constraint", + "file": "docs/operations/drop_constraint.mdx" + }, + { + "title": "Drop multi column constraint", + "href": "/operations/drop_multi_column_constraint", + "file": "docs/operations/drop_multi_column_constraint.mdx" + }, + { + "title": "Drop index", + "href": "/operations/drop_index", + "file": "docs/operations/drop_index.mdx" + }, + { + "title": "Drop table", + "href": "/operations/drop_table", + "file": "docs/operations/drop_table.mdx" + }, + { + "title": "Raw SQL", + "href": "/operations/raw_sql", + "file": "docs/operations/raw_sql.mdx" + }, + { + "title": "Rename table", + "href": "/operations/rename_table", + "file": "docs/operations/rename_table.mdx" + }, + { + "title": "Rename constraint", + "href": "/operations/rename_constraint", + "file": "docs/operations/rename_constraint.mdx" + }, + { + "title": "Set replica identity (deprecated)", + "href": "/operations/set_replica_identity", + "file": "docs/operations/set_replica_identity.mdx" } - ] + ] + } + ] } diff --git a/docs/operations-reference.md b/docs/operations-reference.md deleted file mode 100644 index 3dd2aefb..00000000 --- a/docs/operations-reference.md +++ /dev/null @@ -1,642 +0,0 @@ -## Operations reference - -`pgroll` migrations are specified as JSON files. All migrations follow the same basic structure: - -```json -{ - "name": "0x_migration_name", - "operations": [...] -} -``` - -See the [examples](../examples) directory for examples of each kind of operation. - -`pgroll` supports the following migration operations: - -* [Add column](#add-column) -* [Alter column](#alter-column) - * [Rename column](#rename-column) - * [Change type](#change-type) - * [Change default](#change-default) - * [Change comment](#change-comment) - * [Add check constraint](#add-check-constraint) - * [Add foreign key](#add-foreign-key) - * [Add not null constraint](#add-not-null-constraint) - * [Drop not null constraint](#drop-not-null-constraint) - * [Add unique constraint](#add-unique-constraint) -* [Create index](#create-index) -* [Create table](#create-table) -* [Create constraint](#create-constraint) -* [Drop column](#drop-column) -* [Drop constraint](#drop-constraint) -* [Drop multi-column constraint](#drop-multi-column-constraint) -* [Drop index](#drop-index) -* [Drop table](#drop-table) -* [Raw SQL](#raw-sql) -* [Rename table](#rename-table) -* [Rename constraint](#rename-constraint) -* [Set replica identity](#set-replica-identity) - -### Add column - -An add column operation creates a new column on an existing table. - -**add column** operations have this structure: - -```json -{ - "add_column": { - "table": "name of table to which the column should be added", - "up": "SQL expression", - "column": { - "name": "name of column", - "type": "postgres type", - "comment": "postgres comment for the column", - "nullable": true|false, - "unique": true|false, - "pk": true|false, - "default": "default value for the column", - "check": { - "name": "name of check constraint", - "constraint": "constraint expression" - }, - "references": { - "name": "name of foreign key constraint", - "table": "name of referenced table", - "column": "name of referenced column" - "on_delete": "ON DELETE behaviour, can be CASCADE, SET NULL, RESTRICT, or NO ACTION. Default is NO ACTION", - } - } - } -} -``` - -Default values are subject to the usual rules for quoting SQL expressions. In particular, string literals should be surrounded with single quotes. - -**NOTE:** As a special case, the `up` field can be omitted when adding `smallserial`, `serial` and `bigserial` columns. - -Example **add column** migrations: - -* [03_add_column.json](../examples/03_add_column.json) -* [06_add_column_to_sql_table.json](../examples/06_add_column_to_sql_table.json) -* [17_add_rating_column.json](../examples/17_add_rating_column.json) -* [26_add_column_with_check_constraint.json](../examples/26_add_column_with_check_constraint.json) -* [30_add_column_simple_up.json](../examples/30_add_column_simple_up.json) -* [41_add_enum_column.json](../examples/41_add_enum_column.json) - -### Alter column - -An alter column operation alters the properties of a column. The operation supports several sub-operations, described below. - -An alter column operation may contain multiple sub-operations. For example, a single alter column operation may rename a column, change its type, and add a check constraint. - -#### Rename column - -A rename column operation renames a column. - -**rename column** operations have this structure: - -```json -{ - "alter_column": { - "table": "table name", - "column": "old column name", - "name": "new column name" - } -} -``` - -Example **rename column** migrations: - -* [13_rename_column.json](../examples/13_rename_column.json) - -#### Change type - -A change type operation changes the type of a column. - -**change type** operations have this structure: - -```json -{ - "alter_column": { - "table": "table name", - "column": "column name", - "type": "new type of column", - "up": "SQL expression", - "down": "SQL expression" - } -} -``` - -Example **change type** migrations: - -* [18_change_column_type.json](../examples/18_change_column_type.json) - -#### Change default - -A change default operation changes the default value of a column. - -**change default** operations have this structure: - -```json -{ - "alter_column": { - "table": "table name", - "column": "column name", - "default": "new default value" | null, - "up": "SQL expression", - "down": "SQL expression" - } -} -``` - -Example **change default** migrations: - -* [35_alter_column_multiple.json](../examples/35_alter_column_multiple.json) -* [46_alter_column_drop_default](../examples/46_alter_column_drop_default.json) - -#### Change comment - -A change comment operation changes the comment on a column. - -**change comment** operations have this structure: - -```json -{ - "alter_column": { - "table": "table name", - "column": "column name", - "comment": "new comment for column" | null, - "up": "SQL expression", - "down": "SQL expression" - } -} -``` - -* [35_alter_column_multiple.json](../examples/35_alter_column_multiple.json) -* [36_set_comment_to_null.json](../examples/36_set_comment_to_null.json) - -#### Add check constraint - -An add check constraint operation adds a `CHECK` constraint to a column. - -**add check constraint** migrations have this structure: - -```json -{ - "alter_column": { - "table": "table name", - "column": "column name", - "check": { - "name": "check constraint name", - "constraint": "constraint expression" - }, - "up": "SQL expression", - "down": "SQL expression" - } -} -``` - -Example **add check constraint** migrations: - -* [22_add_check_constraint.json](../examples/22_add_check_constraint.json) - -#### Add foreign key - -Add foreign key operations add a foreign key constraint to a column. - -**add foreign key** constraints have this structure: - -```json -{ - "alter_column": { - "table": "table name", - "column": "column name", - "references": { - "name": "name of foreign key reference", - "table": "name of referenced table", - "column": "name of referenced column", - "on_delete": "ON DELETE behaviour, can be CASCADE, SET NULL, RESTRICT, or NO ACTION. Default is NO ACTION", - }, - "up": "SQL expression", - "down": "SQL expression" - } -} -``` - -Example **add foreign key** migrations: - -* [21_add_foreign_key_constraint.json](../examples/21_add_foreign_key_constraint.json) - -#### Add not null constraint - -Add not null operations add a `NOT NULL` constraint to a column. - -**add not null** operations have this structure: - -```json -{ - "alter_column": { - "table": "table name", - "column": "column name", - "nullable": false, - "up": "SQL expression", - "down": "SQL expression" - } -} -``` - -Example **add not null** migrations: - -* [16_set_nullable.json](../examples/16_set_nullable.json) - -#### Drop not null constraint - -Drop not null operations drop a `NOT NULL` constraint from a column. - -**drop not null** operations have this structure: - -```json -{ - "alter_column": { - "table": "table name", - "column": "column name", - "nullable": true, - "up": "SQL expression", - "down": "SQL expression" - } -} -``` - -Example **drop not null** migrations: - -* [31_unset_not_null.json](../examples/31_unset_not_null.json) - -#### Add unique constraint - -Add unique operations add a `UNIQUE` constraint to a column. - -**add unique** operations have this structure: - -```json -{ - "alter_column": { - "table": "table name", - "column": "column name", - "unique": { - "name": "name of unique constraint" - }, - "up": "SQL expression", - "down": "SQL expression" - } -} -``` - -Example **add unique** migrations: - -* [15_set_column_unique.json](../examples/15_set_column_unique.json) - -### Create index - -A create index operation creates a new index on a set of columns. - -**create index** operations have this structure: - -```json -{ - "create_index": { - "table": "name of table on which to define the index", - "name": "index name", - "columns": [ "names of columns on which to define the index" ] - "predicate": "conditional expression for defining a partial index", - "method": "btree" - } -} -``` - -The field `method` can be `btree`, `hash`, `gist`, `spgist`, `gin`, `brin`. -You can also specify storage parameters for the index in `storage_parameters`. -To create a unique index set `unique` to `true`. - -Example **create index** migrations: - -* [10_create_index.json](../examples/10_create_index.json) -* [37_create_partial_index.json](../examples/37_create_partial_index.json) -* [38_create_hash_index_with_fillfactor.json](../examples/38_create_hash_index_with_fillfactor.json) -* [42_create_unique_index.json](../examples/42_create_unique_index.json) - -### Create table - -A create table operation creates a new table in the database. - -**create table** operations have this structure: - -```json -{ - "create_table": { - "name": "name of new table", - "columns": [...] - ] - } -} -``` - -where each `column` is defined as: - -```json -{ - "name": "column name", - "type": "postgres type", - "comment": "postgres comment for the column", - "nullable": true|false, - "unique": true|false, - "pk": true|false, - "default": "default value" - "check": { - "name": "name of check constraint" - "constraint": "constraint expression" - } - "references": { - "name": "name of foreign key constraint" - "table": "name of referenced table" - "column": "name of referenced column" - "on_delete": "ON DELETE behaviour, can be CASCADE, SET NULL, RESTRICT, or NO ACTION. Default is NO ACTION", - } -}, -``` - -Default values are subject to the usual rules for quoting SQL expressions. In particular, string literals should be surrounded with single quotes. - -Example **create table** migrations: - -* [01_create_tables.json](../examples/01_create_tables.json) -* [02_create_another_table.json](../examples/02_create_another_table.json) -* [08_create_fruits_table.json](../examples/08_create_fruits_table.json) -* [12_create_employees_table.json](../examples/12_create_employees_table.json) -* [14_add_reviews_table.json](../examples/14_add_reviews_table.json) -* [19_create_orders_table.json](../examples/19_create_orders_table.json) -* [20_create_posts_table.json](../examples/20_create_posts_table.json) -* [25_add_table_with_check_constraint.json](../examples/25_add_table_with_check_constraint.json) -* [28_different_defaults.json](../examples/28_different_defaults.json) - -### Create constraint - -A create constraint operation adds a new constraint to an existing table. - -`UNIQUE`, `CHECK` and `FOREIGN KEY` constraints are supported. - -Required fields: `name`, `table`, `type`, `up`, `down`. - -**create constraint** operations have this structure: - -```json -{ - "create_constraint": { - "table": "name of table", - "name": "my_unique_constraint", - "columns": ["column1", "column2"], - "type": "unique"| "check" | "foreign_key", - "check": "SQL expression for CHECK constraint", - "references": { - "name": "name of foreign key reference", - "table": "name of referenced table", - "columns": "[names of referenced columns]", - "on_delete": "ON DELETE behaviour, can be CASCADE, SET NULL, RESTRICT, or NO ACTION. Default is NO ACTION", - }, - "up": { - "column1": "up SQL expressions for each column covered by the constraint", - ... - }, - "down": { - "column1": "up SQL expressions for each column covered by the constraint", - ... - } - } -} -``` - -Example **create constraint** migrations: - -* [44_add_table_unique_constraint.json](../examples/44_add_table_unique_constraint.json) -* [45_add_table_check_constraint.json](../examples/45_add_table_check_constraint.json) -* [46_add_table_foreign_key_constraint.json](../examples/46_add_table_foreign_key_constraint.json) - -### Drop column - -A drop column operation drops a column from an existing table. - -**drop column** operations have this structure: - -```json -{ - "drop_column": { - "table": "name of table", - "column": "name of column to drop", - "down": "SQL expression" - } -} -``` - -The `down` field above is required in order to backfill the previous version of the schema during an active migration. For instance, in our [example](../examples/09_drop_column.json), you can see that if a new row is inserted against the new schema without a `price` column, the old schema `price` column will be set to `0`. - -Example **drop column** migrations: - -* [09_drop_column.json](../examples/09_drop_column.json) - -### Drop constraint - -:warning: The **drop constraint** operation is deprecated. Please use the [drop multi-column constraint](#drop-multi-column-constraint) operation instead. The **drop_constraint** operation will be removed in a future release of `pgroll`. :warning: - -A drop constraint operation drops a single-column constraint from an existing table. - -Only `CHECK`, `FOREIGN KEY`, and `UNIQUE` constraints can be dropped. - -**drop constraint** operations have this structure: - -```json -{ - "drop_constraint": { - "table": "name of table", - "name": "name of constraint to drop", - "up": "SQL expression", - "down": "SQL expression" - } -} -``` - -Example **drop constraint** migrations: - -* [23_drop_check_constraint.json](../examples/23_drop_check_constraint.json) -* [24_drop_foreign_key_constraint.json](../examples/24_drop_foreign_key_constraint.json) -* [27_drop_unique_constraint.json](../examples/27_drop_unique_constraint.json) - -### Drop multi-column constraint - -A drop constraint operation drops a multi-column constraint from an existing table. - -Only `CHECK`, `FOREIGN KEY`, and `UNIQUE` constraints can be dropped. - -**drop multi-column constraint** operations have this structure: - -```json -{ - "drop_multicolumn_constraint": { - "table": "name of table", - "name": "name of constraint to drop", - "up": { - "column1": "up SQL expressions for each column covered by the constraint", - ... - }, - "down": { - "column1": "down SQL expressions for each column covered by the constraint", - ... - } - } -} -``` - -Example **drop multi-column constraint** migrations: - -* [48_drop_tickets_check.json](../examples/48_drop_tickets_check.json) - -### Drop index - -A drop index operation drops an index from a table. - -**drop index** operations have this structure: - -```json -{ - "drop_index": { - "name": "name of index to drop" - } -} -``` - -Example **drop index** migrations: - -* [11_drop_index.json](../examples/11_drop_index.json) - -### Drop table - -A drop table operation drops a table. - -**drop table** operations have this structure: - -```json -{ - "drop_table": { - "name": "name of table to drop" - } -} -``` - -Example **drop table** migrations: - -* [07_drop_table.json](../examples/07_drop_table.json) - -### Raw SQL - -A raw SQL operation runs arbitrary SQL against the database. This is intended as an 'escape hatch' to allow a migration to perform operations that are otherwise not supported by `pgroll`. - -:warning: `pgroll` is unable to guarantee that raw SQL migrations are safe and will not result in application downtime. :warning: - -**sql** operations have this structure: - -```json -{ - "sql": { - "up": "SQL expression", - "down": "SQL expression" - } -} -``` - -By default, a `sql` operation cannot run together with other operations in the same migration. This is to ensure pgroll can correctly track the state of the database. However, it is possible to run a `sql` operation together with other operations by setting the `onComplete` flag to `true`. - -The `onComplete` flag will make this operation run the `up` expression on the complete phase (instead of the default, which is to run it on the start phase). - -`onComplete` flag is incompatible with `down` expression, as `pgroll` does not support running rollback after complete was executed. - - - - -```json -{ - "sql": { - "up": "SQL expression", - "onComplete": true - } -} -``` - -Example **raw SQL** migrations: - -* [05_sql.json](../examples/05_sql.json) -* [32_sql_on_complete.json](../examples/32_sql_on_complete.json) - - -### Rename table - -A rename table operation renames a table. - -**rename table** operations have this structure: - -```json -{ - "rename_table": { - "from": "old column name", - "to": "new column name" - } -} -``` - -Example **rename table** migrations: - -* [04_rename_table.json](../examples/04_rename_table.json) - - -### Rename constraint - -A rename constraint operation renames a constraint. - -**rename constraint** operations have this structure: - -```json -{ - "rename_constraint": { - "table": "table name", - "from": "old constraint name", - "to": "new constraint name" - } -} -``` - -Example **rename constraint** migrations: - -* [33_rename_constraint.json](../examples/33_rename_constraint.json) - - -### Set replica identity - -A set replica identity operation sets the replica identity for a table. - -**set replica identity** operations have this structure: - -```json -{ - "set_replica_identity": { - "table": "name of the table", - "identity": { - "type": "full | default | nothing | index" - "index": "name of the index, if type is 'index'" - } - } -} -``` - -:warning: A **set replica identity** operation is applied directly to the underlying table on migration start. This means that both versions of the table exposed in the old and new version schemas will have the new replica identity set. :warning: - -Example **set replica identity** migrations: - -* [29_set_replica_identity.json](../examples/29_set_replica_identity.json) diff --git a/docs/operations/README.md b/docs/operations/README.md new file mode 100644 index 00000000..0a568861 --- /dev/null +++ b/docs/operations/README.md @@ -0,0 +1,10 @@ +# Operations reference + +`pgroll` migrations are specified as JSON files. All migrations follow the same basic structure: + +```json +{ + "name": "0x_migration_name", + "operations": [...] +} +``` diff --git a/docs/operations/add_column.mdx b/docs/operations/add_column.mdx new file mode 100644 index 00000000..02661c6d --- /dev/null +++ b/docs/operations/add_column.mdx @@ -0,0 +1,55 @@ +--- +title: Add column +description: An add column operation creates a new column on an existing table. +--- + +## Structure + +```json +{ + "add_column": { + "table": "name of table to which the column should be added", + "up": "SQL expression", + "column": { + "name": "name of column", + "type": "postgres type", + "comment": "postgres comment for the column", + "nullable": true|false, + "unique": true|false, + "pk": true|false, + "default": "default value for the column", + "check": { + "name": "name of check constraint", + "constraint": "constraint expression" + }, + "references": { + "name": "name of foreign key constraint", + "table": "name of referenced table", + "column": "name of referenced column", + "on_delete": "ON DELETE behaviour, can be CASCADE, SET NULL, RESTRICT, or NO ACTION. Default is NO ACTION", + } + } + } +} +``` + +Default values are subject to the usual rules for quoting SQL expressions. In particular, string literals should be surrounded with single quotes. + +**NOTE:** As a special case, the `up` field can be omitted when adding `smallserial`, `serial` and `bigserial` columns. + +## Examples + + + + + + + + + + + + diff --git a/docs/operations/alter_column/README.md b/docs/operations/alter_column/README.md new file mode 100644 index 00000000..d3ca5af6 --- /dev/null +++ b/docs/operations/alter_column/README.md @@ -0,0 +1,5 @@ +# Alter column + +An alter column operation alters the properties of a column. The operation supports several sub-operations, described below. + +An alter column operation may contain multiple sub-operations. For example, a single alter column operation may rename a column, change its type, and add a check constraint. diff --git a/docs/operations/alter_column/add_check_constraint.mdx b/docs/operations/alter_column/add_check_constraint.mdx new file mode 100644 index 00000000..783ae465 --- /dev/null +++ b/docs/operations/alter_column/add_check_constraint.mdx @@ -0,0 +1,25 @@ +--- +title: Add check constraint +description: An add check constraint operation adds a `CHECK` constraint to a column. +--- + +## Structure + +```json +{ + "alter_column": { + "table": "table name", + "column": "column name", + "check": { + "name": "check constraint name", + "constraint": "constraint expression" + }, + "up": "SQL expression", + "down": "SQL expression" + } +} +``` + +## Examples + + diff --git a/docs/operations/alter_column/add_foreign_key.mdx b/docs/operations/alter_column/add_foreign_key.mdx new file mode 100644 index 00000000..5705b1dc --- /dev/null +++ b/docs/operations/alter_column/add_foreign_key.mdx @@ -0,0 +1,27 @@ +--- +title: Add foreign key +description: Add foreign key operations add a foreign key constraint to a column. +--- + +## Structure + +```json +{ + "alter_column": { + "table": "table name", + "column": "column name", + "references": { + "name": "name of foreign key reference", + "table": "name of referenced table", + "column": "name of referenced column", + "on_delete": "ON DELETE behaviour, can be CASCADE, SET NULL, RESTRICT, or NO ACTION. Default is NO ACTION" + }, + "up": "SQL expression", + "down": "SQL expression" + } +} +``` + +## Examples + + diff --git a/docs/operations/alter_column/add_not_null_constraint.mdx b/docs/operations/alter_column/add_not_null_constraint.mdx new file mode 100644 index 00000000..6eedf73a --- /dev/null +++ b/docs/operations/alter_column/add_not_null_constraint.mdx @@ -0,0 +1,22 @@ +--- +title: Add not null constraint +description: Add not null operations add a `NOT NULL` constraint to a column. +--- + +## Structure + +```json +{ + "alter_column": { + "table": "table name", + "column": "column name", + "nullable": false, + "up": "SQL expression", + "down": "SQL expression" + } +} +``` + +## Examples + + diff --git a/docs/operations/alter_column/add_unique_constraint.mdx b/docs/operations/alter_column/add_unique_constraint.mdx new file mode 100644 index 00000000..51b40a69 --- /dev/null +++ b/docs/operations/alter_column/add_unique_constraint.mdx @@ -0,0 +1,24 @@ +--- +title: Add unique constraint +description: Add unique operations add a `UNIQUE` constraint to a column. +--- + +## Structure + +```json +{ + "alter_column": { + "table": "table name", + "column": "column name", + "unique": { + "name": "name of unique constraint" + }, + "up": "SQL expression", + "down": "SQL expression" + } +} +``` + +## Examples + + diff --git a/docs/operations/alter_column/change_comment.mdx b/docs/operations/alter_column/change_comment.mdx new file mode 100644 index 00000000..d268f84f --- /dev/null +++ b/docs/operations/alter_column/change_comment.mdx @@ -0,0 +1,24 @@ +--- +title: Change comment +description: A change comment operation changes the comment on a column. +--- + +## Structure + +```json +{ + "alter_column": { + "table": "table name", + "column": "column name", + "comment": "new comment for column" | null, + "up": "SQL expression", + "down": "SQL expression" + } +} +``` + +## Examples + + + + diff --git a/docs/operations/alter_column/change_default.mdx b/docs/operations/alter_column/change_default.mdx new file mode 100644 index 00000000..92478dd3 --- /dev/null +++ b/docs/operations/alter_column/change_default.mdx @@ -0,0 +1,24 @@ +--- +title: Change default +description: A change default operation changes the default value of a column. +--- + +## Structure + +```json +{ + "alter_column": { + "table": "table name", + "column": "column name", + "default": "new default value" | null, + "up": "SQL expression", + "down": "SQL expression" + } +} +``` + +## Examples + + + + diff --git a/docs/operations/alter_column/change_type.mdx b/docs/operations/alter_column/change_type.mdx new file mode 100644 index 00000000..ab14eaf4 --- /dev/null +++ b/docs/operations/alter_column/change_type.mdx @@ -0,0 +1,22 @@ +--- +title: Change type +description: A change type operation changes the type of a column. +--- + +## Structure + +```json +{ + "alter_column": { + "table": "table name", + "column": "column name", + "type": "new type of column", + "up": "SQL expression", + "down": "SQL expression" + } +} +``` + +## Examples + + diff --git a/docs/operations/alter_column/drop_not_null_constraint.mdx b/docs/operations/alter_column/drop_not_null_constraint.mdx new file mode 100644 index 00000000..6cc471cf --- /dev/null +++ b/docs/operations/alter_column/drop_not_null_constraint.mdx @@ -0,0 +1,22 @@ +--- +title: Drop not null constraint +description: Drop not null operations drop a `NOT NULL` constraint from a column. +--- + +## Structure + +```json +{ + "alter_column": { + "table": "table name", + "column": "column name", + "nullable": true, + "up": "SQL expression", + "down": "SQL expression" + } +} +``` + +## Examples + + diff --git a/docs/operations/alter_column/rename_column.mdx b/docs/operations/alter_column/rename_column.mdx new file mode 100644 index 00000000..cf353be3 --- /dev/null +++ b/docs/operations/alter_column/rename_column.mdx @@ -0,0 +1,20 @@ +--- +title: Rename column +description: A rename column operation renames a column. +--- + +## Structure + +```json +{ + "alter_column": { + "table": "table name", + "column": "old column name", + "name": "new column name" + } +} +``` + +## Examples + + diff --git a/docs/operations/create_constraint.mdx b/docs/operations/create_constraint.mdx new file mode 100644 index 00000000..cc58a42e --- /dev/null +++ b/docs/operations/create_constraint.mdx @@ -0,0 +1,47 @@ +--- +title: Create constraint +description: A create constraint operation adds a new constraint to an existing table. +--- + +## Structure + +`UNIQUE`, `CHECK` and `FOREIGN KEY` constraints are supported. + +Required fields: `name`, `table`, `type`, `up`, `down`. + +```json +{ + "create_constraint": { + "table": "name of table", + "name": "my_unique_constraint", + "columns": ["column1", "column2"], + "type": "unique"| "check" | "foreign_key", + "check": "SQL expression for CHECK constraint", + "references": { + "name": "name of foreign key reference", + "table": "name of referenced table", + "columns": "[names of referenced columns]", + "on_delete": "ON DELETE behaviour, can be CASCADE, SET NULL, RESTRICT, or NO ACTION. Default is NO ACTION", + }, + "up": { + "column1": "up SQL expressions for each column covered by the constraint", + ... + }, + "down": { + "column1": "up SQL expressions for each column covered by the constraint", + ... + } + } +} +``` + +## Examples + + + + + + diff --git a/docs/operations/create_index.mdx b/docs/operations/create_index.mdx new file mode 100644 index 00000000..cd977ad6 --- /dev/null +++ b/docs/operations/create_index.mdx @@ -0,0 +1,35 @@ +--- +title: Create index +description: A create index operation creates a new index on a set of columns. +--- + +## Structure + +```json +{ + "create_index": { + "table": "name of table on which to define the index", + "name": "index name", + "columns": [ "names of columns on which to define the index" ] + "predicate": "conditional expression for defining a partial index", + "method": "btree" + } +} +``` + +The field `method` can be `btree`, `hash`, `gist`, `spgist`, `gin`, `brin`. +You can also specify storage parameters for the index in `storage_parameters`. +To create a unique index set `unique` to `true`. + +## Examples + + + + + + + + diff --git a/docs/operations/create_table.mdx b/docs/operations/create_table.mdx new file mode 100644 index 00000000..81d082c8 --- /dev/null +++ b/docs/operations/create_table.mdx @@ -0,0 +1,64 @@ +--- +title: Create table +description: A create table operation creates a new table in the database. +--- + +## Structure + +```json +{ + "create_table": { + "name": "name of new table", + "columns": [...] + } +} +``` + +Each `column` is defined as: + +```json +{ + "name": "column name", + "type": "postgres type", + "comment": "postgres comment for the column", + "nullable": true|false, + "unique": true|false, + "pk": true|false, + "default": "default value", + "check": { + "name": "name of check constraint", + "constraint": "constraint expression" + }, + "references": { + "name": "name of foreign key constraint", + "table": "name of referenced table", + "column": "name of referenced column", + "on_delete": "ON DELETE behaviour, can be CASCADE, SET NULL, RESTRICT, or NO ACTION. Default is NO ACTION", + } +}, +``` + +Default values are subject to the usual rules for quoting SQL expressions. In particular, string literals should be surrounded with single quotes. + +## Examples + + + + + + + + + + + + + + + + + + diff --git a/docs/operations/drop_column.mdx b/docs/operations/drop_column.mdx new file mode 100644 index 00000000..e555c4b1 --- /dev/null +++ b/docs/operations/drop_column.mdx @@ -0,0 +1,26 @@ +--- +title: Drop column +description: A drop column operation drops a column from an existing table. +--- + +## Structure + +```json +{ + "drop_column": { + "table": "name of table", + "column": "name of column to drop", + "down": "SQL expression" + } +} +``` + +The `down` field above is required in order to backfill the previous version of the schema during an active migration. + +## Examples + +### Drop a column with a default value + +If a new row is inserted against the new schema without a `price` column, the old schema `price` column will be set to `0`. + + diff --git a/docs/operations/drop_constraint.mdx b/docs/operations/drop_constraint.mdx new file mode 100644 index 00000000..10ed8e40 --- /dev/null +++ b/docs/operations/drop_constraint.mdx @@ -0,0 +1,33 @@ +--- +title: Drop constraint +description: A drop constraint operation drops a single-column constraint from an existing table. +--- + + + The **drop constraint** operation is deprecated. Please use the [drop + multi-column constraint](#drop-multi-column-constraint) operation instead. The + **drop_constraint** operation will be removed in a future release of `pgroll`. + + +## Structure + +Only `CHECK`, `FOREIGN KEY`, and `UNIQUE` constraints can be dropped. + +```json +{ + "drop_constraint": { + "table": "name of table", + "name": "name of constraint to drop", + "up": "SQL expression", + "down": "SQL expression" + } +} +``` + +## Examples + + + + + + diff --git a/docs/operations/drop_index.mdx b/docs/operations/drop_index.mdx new file mode 100644 index 00000000..51df11e5 --- /dev/null +++ b/docs/operations/drop_index.mdx @@ -0,0 +1,18 @@ +--- +title: Drop index +description: A drop index operation drops an index from a table. +--- + +## Structure + +```json +{ + "drop_index": { + "name": "name of index to drop" + } +} +``` + +## Examples + + diff --git a/docs/operations/drop_multi_column_constraint.mdx b/docs/operations/drop_multi_column_constraint.mdx new file mode 100644 index 00000000..a93e5c0f --- /dev/null +++ b/docs/operations/drop_multi_column_constraint.mdx @@ -0,0 +1,29 @@ +--- +title: Drop multi-column constraint +description: A drop constraint operation drops a multi-column constraint from an existing table. +--- + +## Structure + +Only `CHECK`, `FOREIGN KEY`, and `UNIQUE` constraints can be dropped. + +```json +{ + "drop_multicolumn_constraint": { + "table": "name of table", + "name": "name of constraint to drop", + "up": { + "column1": "up SQL expressions for each column covered by the constraint", + ... + }, + "down": { + "column1": "down SQL expressions for each column covered by the constraint", + ... + } + } +} +``` + +## Examples + + diff --git a/docs/operations/drop_table.mdx b/docs/operations/drop_table.mdx new file mode 100644 index 00000000..5eef06d1 --- /dev/null +++ b/docs/operations/drop_table.mdx @@ -0,0 +1,18 @@ +--- +title: Drop table +description: A drop table operation drops a table. +--- + +## Structure + +```json +{ + "drop_table": { + "name": "name of table to drop" + } +} +``` + +## Examples + + diff --git a/docs/operations/raw_sql.mdx b/docs/operations/raw_sql.mdx new file mode 100644 index 00000000..811deb15 --- /dev/null +++ b/docs/operations/raw_sql.mdx @@ -0,0 +1,43 @@ +--- +title: Raw SQL +description: A raw SQL operation runs arbitrary SQL against the database. +--- + +## Structure + +This is intended as an 'escape hatch' to allow a migration to perform operations that are otherwise not supported by `pgroll`. + + + `pgroll` is unable to guarantee that raw SQL migrations are safe and will not + result in application downtime. + + +```json +{ + "sql": { + "up": "SQL expression", + "down": "SQL expression" + } +} +``` + +By default, a `sql` operation cannot run together with other operations in the same migration. This is to ensure pgroll can correctly track the state of the database. However, it is possible to run a `sql` operation together with other operations by setting the `onComplete` flag to `true`. + +The `onComplete` flag will make this operation run the `up` expression on the complete phase (instead of the default, which is to run it on the start phase). + +`onComplete` flag is incompatible with `down` expression, as `pgroll` does not support running rollback after complete was executed. + +```json +{ + "sql": { + "up": "SQL expression", + "onComplete": true + } +} +``` + +## Examples + + + + diff --git a/docs/operations/rename_constraint.mdx b/docs/operations/rename_constraint.mdx new file mode 100644 index 00000000..94f7d5af --- /dev/null +++ b/docs/operations/rename_constraint.mdx @@ -0,0 +1,20 @@ +--- +title: Rename constraint +description: A rename constraint operation renames a constraint. +--- + +## Structure + +```json +{ + "rename_constraint": { + "table": "table name", + "from": "old constraint name", + "to": "new constraint name" + } +} +``` + +## Examples + + diff --git a/docs/operations/rename_table.mdx b/docs/operations/rename_table.mdx new file mode 100644 index 00000000..b22019be --- /dev/null +++ b/docs/operations/rename_table.mdx @@ -0,0 +1,19 @@ +--- +title: Rename table +description: A rename table operation renames a table. +--- + +## Structure + +```json +{ + "rename_table": { + "from": "old column name", + "to": "new column name" + } +} +``` + +## Examples + + diff --git a/docs/operations/set_replica_identity.mdx b/docs/operations/set_replica_identity.mdx new file mode 100644 index 00000000..20b3fdac --- /dev/null +++ b/docs/operations/set_replica_identity.mdx @@ -0,0 +1,34 @@ +--- +title: Set replica identity +description: A set replica identity operation sets the replica identity for a table. +--- + + + The **set replica identity** operation is deprecated and will be removed in a + future release. Please use a [raw SQL operation](#raw-sql) to set the replica + identity of table instead. + + +## Structure + +```json +{ + "set_replica_identity": { + "table": "name of the table", + "identity": { + "type": "full | default | nothing | index" + "index": "name of the index, if type is 'index'" + } + } +} +``` + + + A **set replica identity** operation is applied directly to the underlying + table on migration start. This means that both versions of the table exposed + in the old and new version schemas will have the new replica identity set. + + +## Examples + +