git.iko.soy/reshape
on main help sign in
Add README section on cross-table migrations
42257befabianlindfors
README.md+37−2
compare with main
unifiedsplit
@@ -34,6 +34,7 @@ Designed for Postgres 12 and later.
34 - [Create enum](#create-enum)
34 - [Create enum](#create-enum)
35 - [Remove enum](#remove-enum)
35 - [Remove enum](#remove-enum)
36 - [Custom](#custom)
36 - [Custom](#custom)
37+ - [Complex changes across tables](#complex-changes-across-tables)
37- [Commands and options](#commands-and-options)
38- [Commands and options](#commands-and-options)
38 - [`reshape migration start`](#reshape-migration-start)
39 - [`reshape migration start`](#reshape-migration-start)
39 - [`reshape migration complete`](#reshape-migration-complete)
40 - [`reshape migration complete`](#reshape-migration-complete)
@@ -284,7 +285,7 @@ foreign_key = "items_user_id_fkey"
284
285
285#### Add column
286#### Add column
286
287
287−The `add_column` action will add a new column to an existing table. You can optionally provide an `up` setting. This should be an SQL expression which will be run for all existing rows to backfill the new column.
288+The `add_column` action will add a new column to an existing table. You can optionally provide an `up` setting. This should be an SQL expression which will be run for all existing rows to backfill the new column. `up` may also reference another table to perform cross-table migrations (see ["Complex changes across tables"](#complex-changes-across-tables)).
288
289
289_Example: add a new column `reference` to table `products`_
290_Example: add a new column `reference` to table `products`_
290
291
@@ -448,7 +449,7 @@ column = "created_at"
448
449
449#### Remove column
450#### Remove column
450
451
451−The `remove_column` action will remove an existing column from a table. You can optionally provide a `down` setting. This should be an SQL expression which will be used to determine values for the old schema when inserting or updating rows using the new schema. The `down` setting must be provided when the removed column is `NOT NULL` or doesn't have a default value.
452+The `remove_column` action will remove an existing column from a table. You can optionally provide a `down` setting. This should be an SQL expression which will be used to determine values for the old schema when inserting or updating rows using the new schema. `down` may also reference another table to perform cross-table migrations (see ["Complex changes across tables"](#complex-changes-across-tables)) . The `down` setting must be provided when the removed column is `NOT NULL` or doesn't have a default value.
452
453
453Any indices that cover the column will be removed.
454Any indices that cover the column will be removed.
454
455
@@ -596,6 +597,40 @@ abort = """
596"""
597"""
597```
598```
598
599
600+### Complex changes across tables
601+
602+The `up` and `down` options available for many actions can also perform more complex changes that span tables.
603+
604+_Example: move `email` column from `users` to `profiles` table_
605+
606+```toml
607+[[actions]]
608+type = "remove_column"
609+table = "users"
610+column = "email"
611+
612+ # When `profiles` is changed in the new schema, we write the email address back to the removed column
613+ [actions.down]
614+ table = "profiles"
615+ value = "email"
616+ where = "id = user_id"
617+
618+[[actions]]
619+type = "add_column"
620+table = "profiles"
621+
622+ [actions.column]
623+ name = "email"
624+ type = "TEXT"
625+ nullable = false
626+
627+ # When `users` is updated in the old schema, we write the email value to `profiles`
628+ [actions.up]
629+ table = "users"
630+ value = "email"
631+ where = "user_id = id"
632+```
633+
599## Commands and options
634## Commands and options
600
635
601### `reshape migration start`
636### `reshape migration start`