@@ -34,6 +34,7 @@ Designed for Postgres 12 and later.
3434 - [Create enum](#create-enum)
3535 - [Remove enum](#remove-enum)
3636 - [Custom](#custom)
37+ - [Complex changes across tables](#complex-changes-across-tables)
3738- [Commands and options](#commands-and-options)
3839 - [`reshape migration start`](#reshape-migration-start)
3940 - [`reshape migration complete`](#reshape-migration-complete)
@@ -284,7 +285,7 @@ foreign_key = "items_user_id_fkey"
284285
285286#### Add column
286287
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)).
288289
289290_Example: add a new column `reference` to table `products`_
290291
@@ -448,7 +449,7 @@ column = "created_at"
448449
449450#### Remove column
450451
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.
452453
453454Any indices that cover the column will be removed.
454455
@@ -596,6 +597,40 @@ abort = """
596597"""
597598```
598599
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+
599634## Commands and options
600635
601636### `reshape migration start`