@@ -2,54 +2,54 @@
22
33[](https://github.com/fabianlindfors/reshape/actions/workflows/test.yaml) [](https://github.com/fabianlindfors/reshape/releases)
44
5−> Also check out [ReshapeDB](https://reshapedb.com), a new database built from the ground up to make zero-downtime schema and data migrations as simple and safe as possible. If you'd like to chat about it, please [reach out](contact@reshapedb.com)!
6−
75Reshape is an easy-to-use, zero-downtime schema migration tool for Postgres. It automatically handles complex migrations that would normally require downtime or manual multi-step changes. During a migration, Reshape ensures both the old and new schema are available at the same time, allowing you to gradually roll out your application. It will also perform all changes without excessive locking, avoiding downtime caused by blocking other queries. For a more thorough introduction to Reshape, check out the [introductory blog post](https://fabianlindfors.se/blog/schema-migrations-in-postgres-using-reshape/).
86
97Designed for Postgres 12 and later.
108
9+*Note: Reshape is **experimental** and should not be used in production. It can (and probably will) break your application.*
10+
1111- [How it works](#how-it-works)
1212- [Getting started](#getting-started)
13− - [Installation](#installation)
14− - [Creating your first migration](#creating-your-first-migration)
15− - [Preparing your application](#preparing-your-application)
16− - [Running your migration](#running-your-migration)
17− - [Using during development](#using-during-development)
13+ - [Installation](#installation)
14+ - [Creating your first migration](#creating-your-first-migration)
15+ - [Preparing your application](#preparing-your-application)
16+ - [Running your migration](#running-your-migration)
17+ - [Using during development](#using-during-development)
1818- [Writing migrations](#writing-migrations)
19− - [Basics](#basics)
20− - [Tables](#tables)
21− - [Create table](#create-table)
22− - [Rename table](#rename-table)
23− - [Remove table](#remove-table)
24− - [Add foreign key](#add-foreign-key)
25− - [Remove foreign key](#remove-foreign-key)
26− - [Columns](#columns)
27− - [Add column](#add-column)
28− - [Alter column](#alter-column)
29− - [Remove column](#remove-column)
30− - [Indices](#indices)
31− - [Add index](#add-index)
32− - [Remove index](#remove-index)
33− - [Enums](#enums)
34− - [Create enum](#create-enum)
35− - [Remove enum](#remove-enum)
36− - [Custom](#custom)
37− - [Complex changes across tables](#complex-changes-across-tables)
19+ - [Basics](#basics)
20+ - [Tables](#tables)
21+ - [Create table](#create-table)
22+ - [Rename table](#rename-table)
23+ - [Remove table](#remove-table)
24+ - [Add foreign key](#add-foreign-key)
25+ - [Remove foreign key](#remove-foreign-key)
26+ - [Columns](#columns)
27+ - [Add column](#add-column)
28+ - [Alter column](#alter-column)
29+ - [Remove column](#remove-column)
30+ - [Indices](#indices)
31+ - [Add index](#add-index)
32+ - [Remove index](#remove-index)
33+ - [Enums](#enums)
34+ - [Create enum](#create-enum)
35+ - [Remove enum](#remove-enum)
36+ - [Custom](#custom)
3837- [Commands and options](#commands-and-options)
39− - [`reshape migration start`](#reshape-migration-start)
40− - [`reshape migration complete`](#reshape-migration-complete)
41− - [`reshape migration abort`](#reshape-migration-abort)
42− - [`reshape schema-query`](#reshape-schema-query)
43− - [Connection options](#connection-options)
38+ - [`reshape migration start`](#reshape-migration-start)
39+ - [`reshape migration complete`](#reshape-migration-complete)
40+ - [`reshape migration abort`](#reshape-migration-abort)
41+ - [`reshape schema-query`](#reshape-schema-query)
42+ - [Connection options](#connection-options)
4443- [License](#license)
4544
45+
4646## How it works
4747
4848Reshape works by creating views that encapsulate the underlying tables, which your application will interact with. During a migration, Reshape will automatically create a new set of views and set up triggers to translate inserts and updates between the old and new schema. This means that every deployment is a three-phase process:
4949
50501. **Start migration** (`reshape migration start`): Sets up views and triggers to ensure both the new and old schema are usable at the same time.
51512. **Roll out application**: Your application can be gradually rolled out without downtime. The existing deployment will continue using the old schema whilst the new deployment uses the new schema.
52−3. **Complete migration** (`reshape migration complete`): Removes the old schema and any intermediate data and triggers.
52+3. **Complete migration** (`reshape migration complete`): Removes the old schema and any intermediate data and triggers.
5353
5454If the application deployment fails, you should run `reshape migration abort` which will roll back any changes made by `reshape migration start` without losing data.
5555
@@ -71,7 +71,7 @@ cargo install reshape
7171
7272#### Docker
7373
74−Reshape is available as a Docker image on [Docker Hub](https://hub.docker.com/repository/docker/fabianlindfors/reshape).
74+Reshape is available as a Docker image on [Docker Hub](https://hub.docker.com/repository/docker/fabianlindfors/reshape).
7575
7676```shell
7777docker run -v $(pwd):/usr/share/app fabianlindfors/reshape reshape migration start
@@ -107,8 +107,6 @@ Reshape relies on your application using a specific schema. When establishing th
107107
108108- [Rust](https://github.com/fabianlindfors/reshape-helper)
109109- [Ruby (and Rails)](https://github.com/fabianlindfors/reshape-ruby)
110−- [Python (and Django)](https://github.com/fabianlindfors/reshape-python)
111−- [Go](https://github.com/leourbina/reshape-helper)
112110
113111If your application is not using one of the languages with an available helper library, you can instead generate the query with the command: `reshape schema-query`. To pass it along to your application, you can for example use an environment variable in your run script: `RESHAPE_SCHEMA_QUERY=$(reshape schema-query)`. Then in your application:
114112
@@ -167,9 +165,9 @@ Every action has a `type`. The supported types are detailed below.
167165
168166#### Create table
169167
170−The `create_table` action will create a new table with the specified columns, indices and constraints. You can optionally provide an `up` option to backfill values from an existing table.
168+The `create_table` action will create a new table with the specified columns, indices and constraints.
171169
172−_Example: create a `customers` table with a few columns and a primary key_
170+*Example: create a `customers` table with a few columns and a primary key*
173171
174172```toml
175173[[actions]]
@@ -187,13 +185,13 @@ primary_key = ["id"]
187185 type = "TEXT"
188186
189187 # Columns default to nullable
190− nullable = false
188+ nullable = false
191189
192190 # default can be any valid SQL value, in this case a string literal
193− default = "'PLACEHOLDER'"
191+ default = "'PLACEHOLDER'"
194192```
195193
196−_Example: create `users` and `items` tables with a foreign key between them_
194+*Example: create `users` and `items` tables with a foreign key between them*
197195
198196```toml
199197[[actions]]
@@ -226,34 +224,11 @@ primary_key = ["id"]
226224 referenced_columns = ["id"]
227225```
228226
229−_Example: create `profiles` table based on existing `users` table_
230−
231−```toml
232−[[actions]]
233−type = "create_table"
234−name = "profiles"
235−primary_key = ["user_id"]
236−
237− [[actions.columns]]
238− name = "user_id"
239− type = "INTEGER"
240−
241− [[actions.columns]]
242− name = "user_email"
243− type = "TEXT"
244−
245− # Backfill from `users` table and copy `users.email` to `user_email` column
246− # This will perform an upsert based on the primary key to avoid duplicate rows
247− [actions.up]
248− table = "users"
249− values = { user_id = "id", user_email = "email" }
250−```
251−
252227#### Rename table
253228
254229The `rename_table` action will change the name of an existing table.
255230
256−_Example: change name of `users` table to `customers`_
231+*Example: change name of `users` table to `customers`*
257232
258233```toml
259234[[actions]]
@@ -266,7 +241,7 @@ new_name = "customers"
266241
267242The `remove_table` action will remove an existing table.
268243
269−_Example: remove `users` table_
244+*Example: remove `users` table*
270245
271246```toml
272247[[actions]]
@@ -278,7 +253,7 @@ table = "users"
278253
279254The `add_foreign_key` action will add a foreign key between two existing tables. The migration will fail if the existing column values aren't valid references.
280255
281−_Example: create foreign key from `items` to `users` table_
256+*Example: create foreign key from `items` to `users` table*
282257
283258```toml
284259[[actions]]
@@ -295,7 +270,7 @@ table = "items"
295270
296271The `remove_foreign_key` action will remove an existing foreign key. The foreign key will only be removed once the migration is completed, which means that your new application must continue to adhere to the foreign key constraint.
297272
298−_Example: remove foreign key `items_user_id_fkey` from `users` table_
273+*Example: remove foreign key `items_user_id_fkey` from `users` table*
299274
300275```toml
301276[[actions]]
@@ -308,9 +283,9 @@ foreign_key = "items_user_id_fkey"
308283
309284#### Add column
310285
311−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)).
286+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.
312287
313−_Example: add a new column `reference` to table `products`_
288+*Example: add a new column `reference` to table `products`*
314289
315290```toml
316291[[actions]]
@@ -324,7 +299,7 @@ table = "products"
324299 default = "10"
325300```
326301
327−_Example: replace an existing `name` column with two new columns, `first_name` and `last_name`_
302+*Example: replace an existing `name` column with two new columns, `first_name` and `last_name`*
328303
329304```toml
330305[[actions]]
@@ -360,7 +335,7 @@ column = "name"
360335down = "first_name || ' ' || last_name"
361336```
362337
363−_Example: extract nested value from unstructured JSON `data` column to new `name` column_
338+*Example: extract nested value from unstructured JSON `data` column to new `name` column*
364339
365340```toml
366341[[actions]]
@@ -375,25 +350,6 @@ up = "data['path']['to']['value'] #>> '{}'"
375350 type = "TEXT"
376351```
377352
378−_Example: duplicate `email` column from `users` to `profiles` table_
379−
380−```toml
381−# `profiles` has `user_id` column which maps to `users.id`
382−[[actions]]
383−type = "add_column"
384−table = "profiles"
385−
386− [actions.column]
387− name = "email"
388− type = "TEXT"
389− nullable = false
390−
391− # When `users` is updated in the old schema, we write the email value to `profiles`
392− [actions.up]
393− table = "users"
394− value = "email"
395− where = "user_id = id"
396−```
397353
398354#### Alter column
399355
@@ -401,7 +357,7 @@ The `alter_column` action enables many different changes to an existing column,
401357
402358When performing more complex changes than a rename, `up` and `down` should be provided. These should be SQL expressions which determine how to transform between the new and old version of the column. Inside those expressions, you can reference the current column value by the column name.
403359
404−_Example: rename `last_name` column on `users` table to `family_name`_
360+*Example: rename `last_name` column on `users` table to `family_name`*
405361
406362```toml
407363[[actions]]
@@ -413,7 +369,7 @@ column = "last_name"
413369 name = "family_name"
414370```
415371
416−_Example: change the type of `reference` column from `INTEGER` to `TEXT`_
372+*Example: change the type of `reference` column from `INTEGER` to `TEXT`*
417373
418374```toml
419375[[actions]]
@@ -428,7 +384,7 @@ down = "CAST(reference AS INTEGER)" # Converts from text value to integer
428384 type = "TEXT" # Previous type was 'INTEGER'
429385```
430386
431−_Example: increment all values of an `index` column by one_
387+*Example: increment all values of an `index` column by one*
432388
433389```toml
434390[[actions]]
@@ -443,7 +399,7 @@ down = "index - 1" # Decrement to revert for old schema
443399 name = "index"
444400```
445401
446−_Example: make `name` column not nullable_
402+*Example: make `name` column not nullable*
447403
448404```toml
449405[[actions]]
@@ -458,7 +414,7 @@ up = "COALESCE(name, 'N/A')"
458414 nullable = false
459415```
460416
461−_Example: change default value of `created_at` column to current time_
417+*Example: change default value of `created_at` column to current time*
462418
463419```toml
464420[[actions]]
@@ -472,11 +428,11 @@ column = "created_at"
472428
473429#### Remove column
474430
475−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.
431+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.
476432
477433Any indices that cover the column will be removed.
478434
479−_Example: remove column `name` from table `users`_
435+*Example: remove column `name` from table `users`*
480436
481437```toml
482438[[actions]]
@@ -488,29 +444,13 @@ column = "name"
488444down = "'N/A'"
489445```
490446
491−_Example: remove `email` column from `users` table and use column from `profiles` table instead_
492−
493−```toml
494−[[actions]]
495−type = "remove_column"
496−table = "users"
497−column = "email"
498−
499− # Our application will use the `profiles.email` column instead
500− # For backwards compatibility, we will write back to the removed `email` column whenever `profiles` is changed
501− [actions.down]
502− table = "profiles"
503− value = "profiles.email"
504− where = "users.id = profiles.user_id"
505−```
506−
507447### Indices
508448
509449#### Add index
510450
511451The `add_index` action will add a new index to an existing table.
512452
513−_Example: create a `users` table with a unique index on the `name` column_
453+*Example: create a `users` table with a unique index on the `name` column*
514454
515455```toml
516456[[actions]]
@@ -539,7 +479,7 @@ table = "users"
539479 unique = true
540480```
541481
542−_Example: add GIN index to `data` column on `products` table_
482+*Example: add GIN index to `data` column on `products` table*
543483
544484```toml
545485[[actions]]
@@ -558,7 +498,7 @@ table = "products"
558498
559499The `remove_index` action will remove an existing index. The index won't actually be removed until the migration is completed.
560500
561−_Example: remove the `name_idx` index_
501+*Example: remove the `name_idx` index*
562502
563503```toml
564504[[actions]]
@@ -572,7 +512,7 @@ index = "name_idx"
572512
573513The `create_enum` action will create a new [enum type](https://www.postgresql.org/docs/current/datatype-enum.html) with the specified values.
574514
575−_Example: add a new `mood` enum type with three possible values_
515+*Example: add a new `mood` enum type with three possible values*
576516
577517```toml
578518[[actions]]
@@ -585,7 +525,7 @@ values = ["happy", "ok", "sad"]
585525
586526The `remove_enum` action will remove an existing [enum type](https://www.postgresql.org/docs/current/datatype-enum.html). Make sure all usages of the enum has been removed before running the migration. The enum will only be removed once the migration is completed.
587527
588−_Example: remove the `mood` enum type_
528+*Example: remove the `mood` enum type*
589529
590530```toml
591531[[actions]]
@@ -603,7 +543,7 @@ There are three optional settings available which all accept SQL queries. All qu
603543- `complete`: run when a migration is completed using `reshape migration complete`
604544- `abort`: run when a migration is aborted using `reshape migration abort`
605545
606−_Example: enable PostGIS and pg_stat_statements extensions_
546+*Example: enable PostGIS and pg_stat_statements extensions*
607547
608548```toml
609549[[actions]]
@@ -615,97 +555,11 @@ start = """
615555"""
616556
617557abort = """
618− DROP EXTENSION IF EXISTS postgis;
619− DROP EXTENSION IF EXISTS pg_stat_statements;
558+ DROP EXTENSION IF NOT EXISTS postgis;
559+ DROP EXTENSION IF NOT EXISTS pg_stat_statements;
620560"""
621561```
622562
623−### Complex changes across tables
624−
625−The `up` and `down` options available when creating tables, adding columns and removing columns can also perform more complex changes that span tables.
626−
627−_Example: move `email` column from `users` to `profiles` table_
628−
629−```toml
630−[[actions]]
631−type = "add_column"
632−table = "profiles"
633−
634− [actions.column]
635− name = "email"
636− type = "TEXT"
637− nullable = false
638−
639− # When `users` is updated in the old schema, we write the email value to `profiles`
640− [actions.up]
641− table = "users"
642− value = "users.email"
643− where = "profiles.user_id = users.id"
644−
645−[[actions]]
646−type = "remove_column"
647−table = "users"
648−column = "email"
649−
650− # When `profiles` is changed in the new schema, we write the email address back to the removed column
651− [actions.down]
652− table = "profiles"
653− value = "profiles.email"
654− where = "users.id = profiles.user_id"
655−```
656−
657−_Example: turn a 1:N relationship between `users` and `accounts` into N:M and change the format of the associated `role`_
658−
659−```toml
660−# Add `user_account_connections` as a junction table
661−[[actions]]
662−type = "create_table"
663−name = "user_account_connections"
664−primary_key = ["account_id", "user_id"]
665−
666− [[actions.columns]]
667− name = "account_id"
668− type = "INTEGER"
669−
670− [[actions.columns]]
671− name = "user_id"
672− type = "INTEGER"
673−
674− # `role` is currently stored directly on the `users` table but is part of the relationship
675− [[actions.columns]]
676− name = "role"
677− type = "TEXT"
678− nullable = false
679−
680− # Backfill the new table from `users` and uppercase the `role`
681− [actions.up]
682− table = "users"
683− values = { user_id = "id", account_id = "account_id", role = "UPPER(account_role)" }
684− where = "user_account_connections.user_id = users.id"
685−
686−[[actions]]
687−type = "remove_column"
688−table = "users"
689−column = "account_id"
690−
691− # When `user_account_connections` is updated, we write the `account_id` back to `users`
692− [actions.down]
693− table = "user_account_connections"
694− value = "user_account_connections.account_id"
695− where = "users.id = user_account_connections.user_id"
696−
697−[[actions]]
698−type = "remove_column"
699−table = "users"
700−column = "account_role"
701−
702− # When `user_account_connections` is updated, we write the lowercase role back to `users`
703− [actions.down]
704− table = "user_account_connections"
705− value = "LOWER(user_account_connections.role)"
706− where = "users.id = user_account_connections.user_id"
707−```
708−
709563## Commands and options
710564
711565### `reshape migration start`
@@ -714,16 +568,16 @@ Starts a new migration, applying all migrations under `migrations/` that haven't
714568
715569#### Options
716570
717−_See also [Connection options](#connection-options)_
571+*See also [Connection options](#connection-options)*
718572
719−| Option | Default | Description |
720−| ------------------ | ------------- | --------------------------------------------------------------------------------------------------------------- |
721−| `--complete`, `-c` | `false` | Automatically complete migration after applying it. |
722−| `--dirs` | `migrations/` | Directories to search for migration files. Multiple directories can be specified using `--dirs dir1 dir2 dir3`. |
573+| Option | Default | Description |
574+| ------ | ------- | ----------- |
575+| `--complete`, `-c` | `false` | Automatically complete migration after applying it. |
576+| `--dirs` | `migrations/` | Directories to search for migration files. Multiple directories can be specified using `--dirs dir1 dir2 dir3`. |
723577
724578### `reshape migration complete`
725579
726−Completes migrations previously started with `reshape migration complete`.
580+Completes migrations previously started with `reshape migration complete`.
727581
728582#### Options
729583
@@ -731,7 +585,7 @@ See [Connection options](#connection-options)
731585
732586### `reshape migration abort`
733587
734−Aborts any migrations which haven't yet been completed.
588+Aborts any migrations which haven't yet been completed.
735589
736590#### Options
737591
@@ -747,8 +601,8 @@ The query should look something like `SET search_path TO migration_1_initial_mig
747601
748602#### Options
749603
750−| Option | Default | Description |
751−| -------- | ------------- | --------------------------------------------------------------------------------------------------------------- |
604+| Option | Default | Description |
605+| ------ | ------- | ----------- |
752606| `--dirs` | `migrations/` | Directories to search for migration files. Multiple directories can be specified using `--dirs dir1 dir2 dir3`. |
753607
754608### Connection options
@@ -757,14 +611,14 @@ The options below can be used with all commands that communicate with Postgres.
757611
758612All options can also be set using environment variables instead of flags. If a `.env` file exists, then variables will be automatically loaded from there.
759613
760−| Option | Default | Environment variable | Description |
761−| ------------ | ----------- | -------------------- | ------------------------------------------- |
762−| `--url` | | `DB_URL` | URL to your Postgres database |
763−| `--host` | `localhost` | `DB_HOST` | Hostname to use when connecting to Postgres |
764−| `--port` | `5432` | `DB_PORT` | Port which Postgres is listening on |
765−| `--database` | `postgres` | `DB_NAME` | Database name |
766−| `--username` | `postgres` | `DB_USERNAME` | Postgres username |
767−| `--password` | `postgres` | `DB_PASSWORD` | Postgres password |
614+| Option | Default | Environment variable | Description |
615+| ------ | ------- | -------------------- | ----------- |
616+| `--url` | | `DB_URL` | URL to your Postgres database |
617+| `--host` | `localhost` | `DB_HOST` | Hostname to use when connecting to Postgres |
618+| `--port` | `5432` | `DB_PORT` | Port which Postgres is listening on |
619+| `--database` | `postgres` | `DB_NAME` | Database name |
620+| `--username` | `postgres` | `DB_USERNAME` | Postgres username |
621+| `--password` | `postgres` | `DB_PASSWORD` | Postgres password |
768622
769623## License
770624