Skip to content

Commit 034cb1e

Browse files
authored
Simplify README.md (#825)
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.
1 parent d4f007b commit 034cb1e

File tree

1 file changed

+21
-18
lines changed

1 file changed

+21
-18
lines changed

README.md

Lines changed: 21 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,11 @@
33
</div>
44

55
<p align="center">
6-
<a href="https://github.com/xataio/pgroll/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-green" alt="License - Apache 2.0"></a>&nbsp;
6+
<a href="https://github.com/xataio/pgroll/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-green" alt="License - Apache 2.0"></a> &nbsp;
77
<a href="https://github.com/xataio/pgroll/actions?query=branch%3Amain"><img src="https://github.com/xataio/pgroll/actions/workflows/build.yml/badge.svg" alt="CI Build"></a> &nbsp;
88
<a href="https://github.com/xataio/pgroll/releases"><img src="https://img.shields.io/github/release/xataio/pgroll.svg?label=Release" alt="Release"></a> &nbsp;
9+
<img alt="GitHub Downloads (all assets, all releases)" src="https://img.shields.io/github/downloads/xataio/pgroll/total"> &nbsp;
10+
<img alt="Static Badge" src="https://img.shields.io/badge/pgroll-documentation-page?style=flat&link=https%3A%2F%2Fpgroll.com%2Fdocs%2Flatest%2Fgetting-started"> &nbsp;
911
<a href="https://xata.io/discord"><img src="https://img.shields.io/discord/996791218879086662?label=Discord" alt="Discord"></a> &nbsp;
1012
<a href="https://twitter.com/xata"><img src="https://img.shields.io/twitter/follow/xata?style=flat" alt="X (formerly Twitter) Follow" /> </a>
1113
</p>
@@ -27,27 +29,11 @@ See the [introductory blog post](https://pgroll.com/blog/introducing-pgroll-zero
2729
- Works with any Postgres service (including RDS and Aurora).
2830
- Written in Go, cross-platform single binary with no external dependencies.
2931

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.
33-
34-
![Multiple schema versions with pgroll](docs/img/[email protected])
35-
36-
37-
`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-
![Multiple schema versions with pgroll](docs/img/[email protected]?c=0)
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-
4732
## Table of Contents
4833

4934
- [Installation](#installation)
5035
- [Usage](#usage)
36+
- [How pgroll works](#how-pgroll-works)
5137
- [Documentation](#documentation)
5238
- [Benchmarks](#benchmarks)
5339
- [Contributing](#contributing)
@@ -161,6 +147,23 @@ At any point during a migration, it can be rolled back to the previous version.
161147
pgroll --postgres-url postgres://user:password@host:port/dbname rollback
162148
```
163149

150+
## How pgroll works
151+
152+
`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.
153+
154+
![Multiple schema versions with pgroll](docs/img/[email protected])
155+
156+
157+
`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+
![Multiple schema versions with pgroll](docs/img/[email protected]?c=0)
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+
164167
## Documentation
165168

166169
For more advanced usage, tutorials, and detailed options refer to the guides and references in the [Documentation](https://pgroll.com/docs/).

0 commit comments

Comments
 (0)