1 unstable release
0.3.0 | Jan 5, 2022 |
---|
#9 in #conflict
23KB
436 lines
Regrate migration management
Introduction
Manage migrations, apply them in order, deal with merge conflicts.
# create a new shell-based migration
regrate init --shell
# Edit the up and down scripts (bash since --shell was used)
edit regrate/latest/up.sh
edit regrate/latest/down.sh
# Run the current migration (to test it out) by passing them to bash in order
regrate run -- bash {}
# Once the migration is working right, we can commit it.
regrate commit -m "add two columns"
# With our migrations complete, we can push it up!
git add -A && git commit -m "initial migration"
# Try to push it. first rebase onto latest...
git rebase main ## ERROR, conflicts!
# Someone else already pushed a migration. you can either:
# 1. merge the migrations together (you're in dev and willing to reset your db)
# 2. better idea would be to move your local changes to a new migration:
regrate resolve
# regrate-resolve moves your local changes into a new migration,
# leaving your peer's as the base.
edit regrate/latest/up.sh # your peer added one of your columns!
regrate commit -m "add one column"
git add -A && git rebase --continue
git push # Yay!
In summary, if anyone claims the next migration name you get a merge conflict with their change. Regrate can help resolve your conflict markers into a new migration.
Your scripts should be idempotent as they will be executed in order
from the start every time.
The current runtime version is not tracked by regrate.
To help, regrate-run
will set REGRATE_INDEX
for each step of the migration,
which can help with keeping track of whether a given script should run in a stateful
environment (on completion, script would update a shared variable to REGRATE_INDEX
).
regrate
will derive names from the contents of the migration scripts.
This means migration scripts are no longer editable once committed. regrate-valid
will complain about hash mismatches.
This can be used in a pre-commit hook to detect bad changes.
Also provided is a library that can be used to iterate migrations in the current directory. This is helpful for runtime. In this case, it is your responsibility to invoke the scripts as you see fit. Packages for other languages also exist and let you run migrations.
Installation
Cargo
- Install the rust toolchain in order to have cargo installed by following this guide.
- Run
cargo install regrate
How it works
The "current version" is left open. You can make changes to it, and its name is always well known. If two people try to change the open version, it will be a merge conflict. To compute the next version from the current version, take the current version string, compute the hash of all migration scripts in that version, and concatenate the version and the hash. Hash the result and this is your next version name. This sequence can be repeated to generate a list of names.
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
See CONTRIBUTING.md.
Dependencies
~8–17MB
~208K SLoC