xataio · kvch · Apr 4, 2025 · Apr 1, 2025
diff --git 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
@@ -1,10 +1,20 @@
 # 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
 {
   "name": "0x_migration_name",
   "operations": [...]
 }
 ```
+
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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