-
Notifications
You must be signed in to change notification settings - Fork 67
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add a proper readme with getting started info, license and a few more pointers.
- Loading branch information
Showing
1 changed file
with
116 additions
and
32 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,48 +1,132 @@ | ||
| # pg-roll | ||
| [](https://opensource.org/licenses/MIT) | ||
| [](https://github.com/xataio/pg-roll/actions?query=branch%3Amain) | ||
| [](https://github.com/xataio/pg-roll/releases) | ||
|
|
||
| :warning: Under development :warning: | ||
| # pg-roll - Zero-downtime schema migrations for PostgreSQL | ||
|
|
||
| PostgreSQL zero-downtime migrations made easy. | ||
| `pg-roll` is a command-line tool that radically simplifies schema migrations in PostgreSQL. It takes care of the complex migration operations to ensure that client applications continue working while the database schema is being updated. This includes ensuring changes are applied without locking the database, and that both old and new schema versions work simultaneously (even when breaking changes are being made!). This removes risks related to schema migrations, and greatly simplifies client application rollout, also allowing for instant rollbacks. | ||
|
|
||
| ## Getting started (development) | ||
| Written in Go, pg-roll is a single binary with no external dependencies. It is designed to be simple to use and work across platforms. | ||
|
|
||
| * Bring a development PostgreSQL up: | ||
| ## How pg-roll works | ||
|
|
||
| ```sh | ||
| docker compose up | ||
| ``` | ||
| TODO | ||
|
|
||
| * Initialize pg-roll (first time only): | ||
| ## Features | ||
|
|
||
| ```sh | ||
| go run . init | ||
| ``` | ||
| - Simple to use, single binary with no external dependencies. | ||
| - Zero-downtime migrations (no database locking, no breaking changes). | ||
| - Keep old and new schema versions working simultaneously. | ||
| - Instant rollback in case of issues during migration. | ||
| - Works with PostgreSQL 14.0 or later. | ||
|
|
||
| * Start a migration: | ||
| ## Table of Contents | ||
|
|
||
| ```sh | ||
| go run . start examples/01_create_tables.json | ||
| ``` | ||
| - [Installation](#installation) | ||
| - [Usage](#usage) | ||
| - [Contributing](#contributing) | ||
| - [License](#license) | ||
| - [Support](#support) | ||
|
|
||
| * Inspect the results: | ||
| ## Installation | ||
|
|
||
| ```sh | ||
| psql postgres://localhost -U postgres | ||
| ``` | ||
| ### Binaries | ||
|
|
||
| ```sql | ||
| \d+ public.* | ||
| \d+ 01_create_tables.* | ||
| ``` | ||
| Binaries are available for Linux, macOS & Windows, check our [Releases](releases). | ||
|
|
||
| * (Optional) Rollback the migration (undo): | ||
| ### From source | ||
|
|
||
| ```sh | ||
| go run . rollback | ||
| ``` | ||
| To install pg-roll from source, run the following command (requires Go 1.21 or later): | ||
|
|
||
| * Complete the migration: | ||
| ```sh | ||
| go install github.com/xataio/pg-roll | ||
| ``` | ||
|
|
||
| ```sh | ||
| go run . complete | ||
| ``` | ||
| ## Usage | ||
|
|
||
| To perform a schema migration using pg-roll, follow these steps: | ||
|
|
||
| ### Prepare the database | ||
|
|
||
| pg-roll needs to store some state in the database. A table is created to track the current schema versions and store version history. To prepare the database, run the following command: | ||
|
|
||
| ```bash | ||
| pg-roll init postgres://user:password@host:port/dbname | ||
| ``` | ||
|
|
||
| ### Start a migration | ||
|
|
||
| Create a migration file, check the [examples](examples) folder for some examples. For instance, to create a new `customers` table: | ||
|
|
||
| <details> | ||
| <summary>initial_migration.json</summary> | ||
|
|
||
| ```json | ||
| { | ||
| "name": "initial_migration", | ||
| "operations": [ | ||
| { | ||
| "create_table": { | ||
| "name": "customers", | ||
| "columns": [ | ||
| { | ||
| "name": "id", | ||
| "type": "integer", | ||
| "pk": true | ||
| }, | ||
| { | ||
| "name": "name", | ||
| "type": "varchar(255)", | ||
| "unique": true | ||
| }, | ||
| { | ||
| "name": "bio", | ||
| "type": "text", | ||
| "nullable": true | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
| </details> | ||
|
|
||
| Then run the following command to start the migration: | ||
|
|
||
| ```sh | ||
| pg-roll --postgres-url postgres://user:password@host:port/dbname start initial_migration.json | ||
| ``` | ||
|
|
||
| ### Complete the migration | ||
|
|
||
| TODO | ||
|
|
||
| ### Rolling back a migration | ||
|
|
||
| TODO | ||
|
|
||
| ### Advanced Usage | ||
|
|
||
| For more advanced usage and detailed options, refer to the [Documentation](). | ||
|
|
||
| ## Contributing | ||
|
|
||
| We welcome contributions from the community! If you'd like to contribute to pg-roll, please follow these guidelines: | ||
|
|
||
| * Fork the repository. | ||
| * Create a new branch for your feature or bug fix. | ||
| * Make your changes and write tests if applicable. | ||
| * Ensure your code passes linting and tests. | ||
| * Submit a pull request. | ||
| [TODO]:* Please see our Contribution Guidelines for more details. | ||
|
|
||
| ## License | ||
| This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. | ||
|
|
||
| ## Support | ||
| If you have any questions, encounter issues, or need assistance, please feel free to open an issue on this repository, and our community will be happy to help. | ||
|
|
||
|
|
||
| <br> | ||
| <p align="center">Made with :heart: by <a href="https://xata.io">Xata</a></p> |