You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This PR simplifies the readme of `pgroll`.
I moved the section "How pgroll works" lower, before the documentation
link. Now installation and basic tutorial are easier to find. It does
not get lost in the 1000 lines long readme.
I also added two new badges: documentation and download count.
@@ -27,27 +29,11 @@ See the [introductory blog post](https://pgroll.com/blog/introducing-pgroll-zero
27
29
- Works with any Postgres service (including RDS and Aurora).
28
30
- Written in Go, cross-platform single binary with no external dependencies.
29
31
30
-
## How pgroll works
31
-
32
-
`pgroll` works by creating virtual schemas by using views on top of the physical tables. This allows for performing all the necessary changes needed for a migration without affecting the existing clients.
`pgroll` follows a [expand/contract workflow](https://openpracticelibrary.com/practice/expand-and-contract-pattern/). On migration start, it will perform all the additive changes (create tables, add columns, etc) in the physical schema, without breaking it.
38
-
39
-
When a breaking change is required on a column, it will create a new column in the physical schema, and backfill it from the old column. Also, configure triggers to make sure all writes to the old/new column get propagated to its counterpart during the whole active migration period. The new column will be then exposed in the new version of the schema.
40
-
41
-
Once the start phase is complete, the new schema version is ready, mapping all the views to the proper tables & columns. Client applications can then access the new schema version, while the old one is still available. This is the moment to start rolling out the new version of the client application.
42
-
43
-

44
-
45
-
When no more client applications are using the old schema version, the migration can be completed. This will remove the old schema, and the new one will be the only one available. No longer needed tables & columns will be removed (no client is using this at this point), and the new ones will be renamed to their final names. Client applications still work during this phase, as the views are still mapping to the proper tables & columns.
46
-
47
32
## Table of Contents
48
33
49
34
-[Installation](#installation)
50
35
-[Usage](#usage)
36
+
-[How pgroll works](#how-pgroll-works)
51
37
-[Documentation](#documentation)
52
38
-[Benchmarks](#benchmarks)
53
39
-[Contributing](#contributing)
@@ -161,6 +147,23 @@ At any point during a migration, it can be rolled back to the previous version.
`pgroll` works by creating virtual schemas by using views on top of the physical tables. This allows for performing all the necessary changes needed for a migration without affecting the existing clients.
`pgroll` follows a [expand/contract workflow](https://openpracticelibrary.com/practice/expand-and-contract-pattern/). On migration start, it will perform all the additive changes (create tables, add columns, etc) in the physical schema, without breaking it.
158
+
159
+
When a breaking change is required on a column, it will create a new column in the physical schema, and backfill it from the old column. Also, configure triggers to make sure all writes to the old/new column get propagated to its counterpart during the whole active migration period. The new column will be then exposed in the new version of the schema.
160
+
161
+
Once the start phase is complete, the new schema version is ready, mapping all the views to the proper tables & columns. Client applications can then access the new schema version, while the old one is still available. This is the moment to start rolling out the new version of the client application.
162
+
163
+

164
+
165
+
When no more client applications are using the old schema version, the migration can be completed. This will remove the old schema, and the new one will be the only one available. No longer needed tables & columns will be removed (no client is using this at this point), and the new ones will be renamed to their final names. Client applications still work during this phase, as the views are still mapping to the proper tables & columns.
166
+
164
167
## Documentation
165
168
166
169
For more advanced usage, tutorials, and detailed options refer to the guides and references in the [Documentation](https://pgroll.com/docs/).
0 commit comments