From 3991f2130952fca80fa3248e82f4e129773eff69 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?No=C3=A9mi=20V=C3=A1nyi?= Date: Tue, 1 Apr 2025 14:13:30 +0200 Subject: [PATCH] Transform JSON structure descriptions and examples to YAML This PR converts JSON descriptions to YAML. --- docs/cli/start.mdx | 6 +- docs/operations/README.md | 12 +- docs/operations/add_column.mdx | 46 +++---- .../alter_column/add_check_constraint.mdx | 22 ++- .../alter_column/add_foreign_key.mdx | 26 ++-- .../alter_column/add_not_null_constraint.mdx | 17 +-- .../alter_column/add_unique_constraint.mdx | 20 ++- .../alter_column/change_comment.mdx | 17 +-- .../alter_column/change_default.mdx | 17 +-- docs/operations/alter_column/change_type.mdx | 17 +-- .../alter_column/drop_not_null_constraint.mdx | 17 +-- docs/operations/create_constraint.mdx | 68 ++++----- docs/operations/create_index.mdx | 43 +++--- docs/operations/create_table.mdx | 130 ++++++++---------- docs/operations/drop_column.mdx | 13 +- docs/operations/drop_constraint.mdx | 15 +- docs/operations/drop_index.mdx | 9 +- .../drop_multi_column_constraint.mdx | 43 +++--- docs/operations/drop_table.mdx | 9 +- docs/operations/raw_sql.mdx | 22 ++- docs/tutorial.md | 120 +++++++--------- 21 files changed, 291 insertions(+), 398 deletions(-) diff --git a/docs/cli/start.mdx b/docs/cli/start.mdx index f5e2a2ec2..f79d60924 100644 --- a/docs/cli/start.mdx +++ b/docs/cli/start.mdx @@ -6,10 +6,10 @@ description: Start a pgroll migration ## Command ``` -$ pgroll start sql/03_add_column.json +$ pgroll start sql/03_add_column.yaml ``` -This starts the migration defined in the `sql/03_add_column.json` file. +This starts the migration defined in the `sql/03_add_column.yaml` 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. @@ -18,7 +18,7 @@ After starting a migration there will be two schema versions in the database; on A migration can be started and completed with one command by specifying the `--complete` flag: ``` -$ pgroll start sql/03_add_column.json --complete +$ pgroll start sql/03_add_column.yaml --complete ``` This is equivalent to running `pgroll start` immediately followed by `pgroll complete`. diff --git a/docs/operations/README.md b/docs/operations/README.md index 0a5688615..e4f61760e 100644 --- a/docs/operations/README.md +++ b/docs/operations/README.md @@ -1,6 +1,15 @@ # Operations reference -`pgroll` migrations are specified as JSON files. All migrations follow the same basic structure: +`pgroll` migrations are specified as YAML or JSON files. All migrations follow the same basic structure: + +YAML migration: + +```yaml +name: "0x_migration_name" +operations: [...] +``` + +JSON migration: ```json { @@ -8,3 +17,4 @@ "operations": [...] } ``` + diff --git a/docs/operations/add_column.mdx b/docs/operations/add_column.mdx index 6b713abcd..6aeb88e40 100644 --- a/docs/operations/add_column.mdx +++ b/docs/operations/add_column.mdx @@ -5,32 +5,26 @@ 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", - } - } - } -} +```yaml +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 ``` The `up` SQL is used when a row is added to the old version of the table (ie, without the new column). In the new version of the table, the row's value for the new column is determined by the `up` SQL expression. The `up` SQL can be omitted if the new column is nullable or has a `DEFAULT` defined. diff --git a/docs/operations/alter_column/add_check_constraint.mdx b/docs/operations/alter_column/add_check_constraint.mdx index 1788adfd5..3d891a865 100644 --- a/docs/operations/alter_column/add_check_constraint.mdx +++ b/docs/operations/alter_column/add_check_constraint.mdx @@ -5,19 +5,15 @@ description: An add check constraint operation adds a `CHECK` constraint to a co ## Structure -```json -{ - "alter_column": { - "table": "table name", - "column": "column name", - "check": { - "name": "check constraint name", - "constraint": "constraint expression" - }, - "up": "SQL expression", - "down": "SQL expression" - } -} +```yaml +alter_column: + table: table name + column: column name + check: + name: check constraint name + constraint: constraint expression + up: SQL expression + down: SQL expression ``` The `up` SQL expression is used to migrate values from the column in the old schema version that aren't subject to the constraint to values in the new schema version that are subject to the constraint. diff --git a/docs/operations/alter_column/add_foreign_key.mdx b/docs/operations/alter_column/add_foreign_key.mdx index 1b7c4f848..935db712a 100644 --- a/docs/operations/alter_column/add_foreign_key.mdx +++ b/docs/operations/alter_column/add_foreign_key.mdx @@ -5,21 +5,17 @@ description: 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" - } -} +```yaml +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 index ee84ca4ec..9fc831993 100644 --- a/docs/operations/alter_column/add_not_null_constraint.mdx +++ b/docs/operations/alter_column/add_not_null_constraint.mdx @@ -5,16 +5,13 @@ 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" - } -} +```yaml +alter_column: + table: table name + column: column name + nullable: false + up: SQL expression + down: SQL expression ``` Use `up` to migrate values from the nullable column in the old schema view to the `NOT NULL` column in the new schema version. `down` is used to migrate values in the other direction. diff --git a/docs/operations/alter_column/add_unique_constraint.mdx b/docs/operations/alter_column/add_unique_constraint.mdx index 2ff3943fb..c82b84396 100644 --- a/docs/operations/alter_column/add_unique_constraint.mdx +++ b/docs/operations/alter_column/add_unique_constraint.mdx @@ -5,18 +5,14 @@ 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" - } -} +```yaml +alter_column: + table: table name + column: column name + unique: + name: name of unique constraint + up: SQL expression + down: SQL expression ``` Use the `up` SQL expression to migrate values from the old non-unique column in the old schema to the `UNIQUE` column in the new schema. diff --git a/docs/operations/alter_column/change_comment.mdx b/docs/operations/alter_column/change_comment.mdx index 408a3f84e..a812de2d3 100644 --- a/docs/operations/alter_column/change_comment.mdx +++ b/docs/operations/alter_column/change_comment.mdx @@ -5,16 +5,13 @@ 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" - } -} +```yaml +alter_column: + table: table name + column: column name + comment: new comment for column | null + up: SQL expression + down: SQL expression ``` The comment is added directly to the column on migration start. diff --git a/docs/operations/alter_column/change_default.mdx b/docs/operations/alter_column/change_default.mdx index 7353bb364..cfbdf9ac8 100644 --- a/docs/operations/alter_column/change_default.mdx +++ b/docs/operations/alter_column/change_default.mdx @@ -5,16 +5,13 @@ 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" - } -} +```yaml +alter_column: + table: table name + column: column name + default: new default value | null + up: SQL expression + down: SQL expression ``` The `default` expression is subject to the usual SQL quoting rules. In particular, string literals should be surrounded with `''`. diff --git a/docs/operations/alter_column/change_type.mdx b/docs/operations/alter_column/change_type.mdx index e3d390d8f..5249f4f74 100644 --- a/docs/operations/alter_column/change_type.mdx +++ b/docs/operations/alter_column/change_type.mdx @@ -5,16 +5,13 @@ 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" - } -} +```yaml +alter_column: + table: table name + column: column name + type: new type of column + up: SQL expression + down: SQL expression ``` Use the `up` SQL expression to do data conversion from the old column type to the new type. In the old schema version, the column will have its old data type; in the new version the column will have its new type. diff --git a/docs/operations/alter_column/drop_not_null_constraint.mdx b/docs/operations/alter_column/drop_not_null_constraint.mdx index ddf89ae9e..971799fa8 100644 --- a/docs/operations/alter_column/drop_not_null_constraint.mdx +++ b/docs/operations/alter_column/drop_not_null_constraint.mdx @@ -5,16 +5,13 @@ 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" - } -} +```yaml +alter_column: + table: table name + column: column name + nullable: true + up: SQL expression + down: SQL expression ``` ## Examples diff --git a/docs/operations/create_constraint.mdx b/docs/operations/create_constraint.mdx index 040ec39d9..e1470952c 100644 --- a/docs/operations/create_constraint.mdx +++ b/docs/operations/create_constraint.mdx @@ -9,49 +9,39 @@ description: A create constraint operation adds a new constraint to an existing 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", - "no_inherit": "true|false", - "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", - "on_delete_set_columns": ["list of FKs to set", "in on delete operation on SET NULL or SET DEFAULT"], - "on_update": "ON UPDATE behaviour, can be CASCADE, SET NULL, RESTRICT, or NO ACTION. Default is NO ACTION", - "match_type": "match type, can be SIMPLE or FULL. Default is SIMPLE" - }, - "up": { - "column1": "up SQL expressions for each column covered by the constraint", - ... - }, - "down": { - "column1": "up SQL expressions for each column covered by the constraint", - ... - } - } -} +```yaml +create_constraint: + table: name of table + name: my_unique_constraint + columns: [column1, column2] + type: unique | check | foreign_key + check: SQL expression for CHECK constraint + no_inherit: true|false + 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 + on_delete_set_columns: [list of FKs to set, in on delete operation on SET NULL or SET DEFAULT] + on_update: ON UPDATE behaviour, can be CASCADE, SET NULL, RESTRICT, or NO ACTION. Default is NO ACTION + match_type: match type, can be SIMPLE or FULL. Default is SIMPLE + up: + column1: up SQL expressions for each column covered by the constraint + ... + down: + column1: up SQL expressions for each column covered by the constraint + ... ``` An `up` and `down` SQL expression is required for each column covered by the constraint, and no other column names are permitted. For example, when adding a new constraint covering columns `a` and `b` the `up` and `down` fields should look like: -```json -{ - "up": { - "a": "up SQL expression for column a", - "b": "up SQL expression for column b", - }, - "down": { - "a": "down SQL expression for column a", - "b": "down SQL expression for column b", - } -} +```yaml +up: + a: up SQL expression for column a + b: up SQL expression for column b +down: + a: down SQL expression for column a + b: down SQL expression for column b ``` ## Examples diff --git a/docs/operations/create_index.mdx b/docs/operations/create_index.mdx index 604ec7509..f3843af48 100644 --- a/docs/operations/create_index.mdx +++ b/docs/operations/create_index.mdx @@ -5,31 +5,24 @@ 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": [ - "column_name": { - "collate": "collation name", - "sort": "ASC | DESC", - "nulls": "FIRST | LAST", - "opclass": { - "name": "operator_class_name", - "params": [ - "param1=val", - "param2=val" - ] - } - } - ] - "predicate": "conditional expression for defining a partial index", - "storage_parameters": "comma-separated list of storage parameters", - "unique": true | false, - "method": "btree" - } -} +```yaml +create_index: + table: name of table on which to define the index + name: index name + columns: + column_name: + collate: collation name + sort: ASC | DESC + nulls: FIRST | LAST + opclass: + name: operator_class_name + params: + - param1=val + - param2=val + predicate: conditional expression for defining a partial index + storage_parameters: comma-separated list of storage parameters + unique: true | false + method: btree ``` * The field `method` can be `btree`, `hash`, `gist`, `spgist`, `gin`, `brin`. diff --git a/docs/operations/create_table.mdx b/docs/operations/create_table.mdx index 3fb431928..d1476880a 100644 --- a/docs/operations/create_table.mdx +++ b/docs/operations/create_table.mdx @@ -5,88 +5,74 @@ description: A create table operation creates a new table in the database. ## Structure -```json -{ - "create_table": { - "name": "name of new table", - "columns": [...], - "constraints": [...] - } -} +```yaml +create_table: + name: name of new table + columns: [...] + constraints: [...] ``` 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", - "no_inherit": "true|false" - }, - "generated": { - "expression": "expression for stored column", - "identity": { - "user_specified_values": "user specified values can be used, can be ALWAYS and BY DEFAULT. Default is ALWAYS", - "sequence_options": "sequence options for identity columns" - } - }, - "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, SET DEFAULT, RESTRICT, or NO ACTION. Default is NO ACTION", - "on_update": "ON UPDATE behaviour, can be CASCADE, SET NULL, RESTRICT, or NO ACTION. Default is NO ACTION", - "match_type": "match type, can be SIMPLE or FULL. Default is SIMPLE" - } -}, +```yaml +- 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 + no_inherit: true|false + generated: + expression: expression for stored column + identity: + user_specified_values: user specified values can be used, can be ALWAYS and BY DEFAULT. Default is ALWAYS + sequence_options: sequence options for identity columns + 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, SET DEFAULT, RESTRICT, or NO ACTION. Default is NO ACTION + on_update: ON UPDATE behaviour, can be CASCADE, SET NULL, RESTRICT, or NO ACTION. Default is NO ACTION + match_type: match type, can be SIMPLE or FULL. Default is SIMPLE ``` -Default values are subject to the usual rules for quoting SQL expressions. In particular, string literals should be surrounded with single quotes. - -Generated columns can either be stored or identity columns. Options `generated.expression` and `generated.identity` cannot be set at the same time. - Each `constraint` is defined as: -```json -{ - "name": "constraint name", - "type": "constraint type", - "columns": ["list", "of", "columns"], - "check": "condition of CHECK constraint", - "nulls_not_distinct": true|false, - "deferrable": true|false, - "initially_deferred": true|false, - "no_inherit": true|false, - "references": { - "name": "name of foreign key constraint", - "table": "name of referenced table", - "columns": ["list", "of", "referenced", "columns"], - "on_delete": "ON DELETE behaviour, can be CASCADE, SET NULL, SET DEFAULT, RESTRICT, or NO ACTION. Default is NO ACTION", - "on_delete_set_columns": ["list of FKs to set", "in on delete operation on SET NULL or SET DEFAULT"], - "on_update": "ON UPDATE behaviour, can be CASCADE, SET NULL, SET DEFAULT, RESTRICT, or NO ACTION. Default is NO ACTION", - "match_type": "match type, can be SIMPLE, FULL or PARTIAL. Default is SIMPLE" - }, - "index_parameters": { - "tablespace": "index_tablespace", - "storage_parameters": "parameter=value", - "include_columns": ["list", "of", "columns", "included in index"] - }, - "exclude": { - "index_method": "name of the index method, e.g. btree", - "elements": "exclude elements", - "predicate": "WHERE clause of the exclude constraint" - } -}, +```yaml +- name: constraint name + type: constraint type + columns: [list, of, columns] + check: condition of CHECK constraint + nulls_not_distinct: true|false + deferrable: true|false + initially_deferred: true|false + no_inherit: true|false + references: + name: name of foreign key constraint + table: name of referenced table + columns: [list, of, referenced, columns] + on_delete: ON DELETE behaviour, can be CASCADE, SET NULL, SET DEFAULT, RESTRICT, or NO ACTION. Default is NO ACTION + on_delete_set_columns: [list of FKs to set, in on delete operation on SET NULL or SET DEFAULT] + on_update: ON UPDATE behaviour, can be CASCADE, SET NULL, SET DEFAULT, RESTRICT, or NO ACTION. Default is NO ACTION + match_type: match type, can be SIMPLE, FULL or PARTIAL. Default is SIMPLE + index_parameters: + tablespace: index_tablespace + storage_parameters: parameter=value + include_columns: [list, of, columns, included in index] + exclude: + index_method: name of the index method, e.g. btree + elements: exclude elements + predicate: WHERE clause of the exclude constraint ``` +Default values are subject to the usual rules for quoting SQL expressions. In particular, string literals should be surrounded with single quotes. + +Generated columns can either be stored or identity columns. Options `generated.expression` and `generated.identity` cannot be set at the same time. + Supported constraint types: `unique`, `check`, `primary_key`, `foreign_key`, `exclude`. Please note that you can only configure primary keys in `columns` list or `constraints` list, but diff --git a/docs/operations/drop_column.mdx b/docs/operations/drop_column.mdx index 8d8d5e5dc..afed96eb4 100644 --- a/docs/operations/drop_column.mdx +++ b/docs/operations/drop_column.mdx @@ -5,14 +5,11 @@ 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" - } -} +```yaml +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. diff --git a/docs/operations/drop_constraint.mdx b/docs/operations/drop_constraint.mdx index d2da25df5..fba0a2d71 100644 --- a/docs/operations/drop_constraint.mdx +++ b/docs/operations/drop_constraint.mdx @@ -13,15 +13,12 @@ description: A drop constraint operation drops a single-column constraint from a 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" - } -} +```yaml +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 index 4ec2698fa..41bdd9eb2 100644 --- a/docs/operations/drop_index.mdx +++ b/docs/operations/drop_index.mdx @@ -5,12 +5,9 @@ description: A drop index operation drops an index from a table. ## Structure -```json -{ - "drop_index": { - "name": "name of index to drop" - } -} +```yaml +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 index 3367505ab..4f61e7cb7 100644 --- a/docs/operations/drop_multi_column_constraint.mdx +++ b/docs/operations/drop_multi_column_constraint.mdx @@ -7,38 +7,29 @@ description: A drop constraint operation drops a multi-column constraint from an 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", - ... - } - } -} +```yaml +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 + ... ``` This operation can also be used to drop single-column constraints and replaces the deprecated (#drop-constraint) operation. An `up` and `down` SQL expression is required for each column covered by the constraint, and no other column names are permitted. For example, when droping a constraint covering columns `a` and `b` the `up` and `down` fields should look like: -```json -{ - "up": { - "a": "up SQL expression for column a", - "b": "up SQL expression for column b", - }, - "down": { - "a": "down SQL expression for column a", - "b": "down SQL expression for column b", - } -} +```yaml +up: + a: up SQL expression for column a + b: up SQL expression for column b +down: + a: down SQL expression for column a + b: down SQL expression for column b ``` The new versions of the columns will no longer have the constraint, but in the old view of the table the columns will still be covered by the constraint; the `down` expressions should therefore be used to ensure that the combination of values meets the constraint being dropped. diff --git a/docs/operations/drop_table.mdx b/docs/operations/drop_table.mdx index 01b83f000..01b49375f 100644 --- a/docs/operations/drop_table.mdx +++ b/docs/operations/drop_table.mdx @@ -5,12 +5,9 @@ description: A drop table operation drops a table. ## Structure -```json -{ - "drop_table": { - "name": "name of table to drop" - } -} +```yaml +drop_table: + name: name of table to drop ``` The table is not visible in the new version of the schema created when the migration is started, but remains visible to the old version of the schema. The table is dropped on migration completion. diff --git a/docs/operations/raw_sql.mdx b/docs/operations/raw_sql.mdx index 00715915f..6659f159e 100644 --- a/docs/operations/raw_sql.mdx +++ b/docs/operations/raw_sql.mdx @@ -12,13 +12,10 @@ This is intended as an 'escape hatch' to allow a migration to perform operations result in application downtime. -```json -{ - "sql": { - "up": "SQL expression", - "down": "SQL expression" - } -} +```yaml +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`. @@ -27,13 +24,10 @@ The `onComplete` flag will make this operation run the `up` expression on the co `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 - } -} +```yaml +sql: + up: SQL expression + onComplete: true ``` ## Examples diff --git a/docs/tutorial.md b/docs/tutorial.md index 1da7cb15d..aba966aed 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -40,39 +40,26 @@ You should see a success message indicating that `pgroll` has been configured. With `pgroll` initialized, let's run our first migration. Here is a migration to create a table: -```json -{ - "name": "01_create_users_table", - "operations": [ - { - "create_table": { - "name": "users", - "columns": [ - { - "name": "id", - "type": "serial", - "pk": true - }, - { - "name": "name", - "type": "varchar(255)", - "unique": true - }, - { - "name": "description", - "type": "text", - "nullable": true - } - ] - } - } - ] -} -``` - -Take this file and save it as `sql/01_create_users_table.json`. - -> Note: The `name` field is optional. If not provided, `pgroll` will use the filename (without the `.json` extension) as the migration name. In this example, the file is saved as `sql/01_create_users_table.json`, so the name would be `01_create_users_table` if not explicitly provided. +```yaml +name: "01_create_users_table" +operations: + - create_table: + name: users + columns: + - name: id + type: serial + pk: true + - name: name + type: varchar(255) + unique: true + - name: description + type: text + nullable: true +``` + +Take this file and save it as `sql/01_create_users_table.yaml`. + +> Note: The `name` field is optional. If not provided, `pgroll` will use the filename (without the `.yaml` extension) as the migration name. In this example, the file is saved as `sql/01_create_users_table.yaml`, so the name would be `01_create_users_table` if not explicitly provided. The migration will create a `users` table with three columns. It is equivalent to the following SQL DDL statement: @@ -87,7 +74,7 @@ CREATE TABLE users( To apply the migration to the database run: ``` -pgroll start sql/01_create_users_table.json --complete +pgroll start sql/01_create_users_table.yaml --complete ```
@@ -132,29 +119,23 @@ There are two things that make this migration difficult: Here is the `pgroll` migration that will perform the migration to make the `description` column `NOT NULL`: -```json -{ - "name": "02_user_description_set_nullable", - "operations": [ - { - "alter_column": { - "table": "users", - "column": "description", - "nullable": false, - "up": "SELECT CASE WHEN description IS NULL THEN 'description for ' || name ELSE description END", - "down": "description" - } - } - ] -} +```yaml +name: "02_user_description_set_nullable" +operations: + - alter_column: + table: users + column: description + nullable: false + up: "SELECT CASE WHEN description IS NULL THEN 'description for ' || name ELSE description END" + down: description ``` -> As mentioned earlier, the `name` field is optional. If the file is saved as `sql/02_user_description_set_nullable.json`, `pgroll` will use `02_user_description_set_nullable` as the migration name if the name field is not provided. +> As mentioned earlier, the `name` field is optional. If the file is saved as `sql/02_user_description_set_nullable.yaml`, `pgroll` will use `02_user_description_set_nullable` as the migration name if the name field is not provided. -Save this migration as `sql/02_user_description_set_nullable.json` and start the migration: +Save this migration as `sql/02_user_description_set_nullable.yaml` and start the migration: ``` -pgroll start 02_user_description_set_nullable.json +pgroll start 02_user_description_set_nullable.yaml ``` After some progress updates you should see a message saying that the migration has been started successfully. @@ -191,10 +172,10 @@ You should see something like this: +----+---------+------------------------+-------------------------+------------------------+ ``` -This is the "expand" phase of the [expand/contract pattern](https://openpracticelibrary.com/practice/expand-and-contract-pattern/) in action; `pgroll` has added a `_pgroll_new_description` field to the table and populated the field for all rows using the `up` SQL from the `02_user_description_set_nullable.json` file: +This is the "expand" phase of the [expand/contract pattern](https://openpracticelibrary.com/practice/expand-and-contract-pattern/) in action; `pgroll` has added a `_pgroll_new_description` field to the table and populated the field for all rows using the `up` SQL from the `02_user_description_set_nullable.yaml` file: -```json -"up": "SELECT CASE WHEN description IS NULL THEN 'description for ' || name ELSE description END", +```yaml +up: "SELECT CASE WHEN description IS NULL THEN 'description for ' || name ELSE description END" ``` This has copied over all `description` values into the `_pgroll_new_description` field, rewriting any `NULL` values using the provided SQL. @@ -441,23 +422,16 @@ The expand/contract approach to migrations means that the old version of the dat Looking at the second of these items, rollbacks, let's see how to roll back a `pgroll` migration. We can start another migration now that our last one is complete: -```json -{ - "name": "03_add_is_active_column", - "operations": [ - { - "add_column": { - "table": "users", - "column": { - "name": "is_atcive", - "type": "boolean", - "nullable": true, - "default": "true" - } - } - } - ] -} +```yaml +name: "03_add_is_active_column" +operations: + - add_column: + table: users + column: + name: is_atcive + type: boolean + nullable: true + default: "true" ``` > Again, the `name` field is optional. The filename will be used as the default name if not specified. @@ -467,7 +441,7 @@ Looking at the second of these items, rollbacks, let's see how to roll back a `p This migration adds a new column to the `users` table. As before, we can start the migration with this command: ``` -pgroll start 03_add_is_active_column.json +pgroll start 03_add_is_active_column.yaml ``` Once again, this creates a new version of the schema: