Show HN: Jetbase – A Python database migration tool (Alembic alternative)(github.com)
github.com
Show HN: Jetbase – A Python database migration tool (Alembic alternative)
https://github.com/jetbase-hq/jetbase
2 comments
the sql-first thing is interesting. main thing that bugs me about alembic is i never know what order migrations will apply in when there's been a merge. how does jetbase handle branching?
Branching is less of an issue than with alembic because each alembic migration is tied to a down revision which causes multiple heads.
In jetbase, migrations are linear. They're applied in ascending version order. So there will always only be one head. any versions introduced that are the same or lower than the current head will fail their migration.
In alembic:
- Current head is A - dev1 adds migration B (A -> B) - dev2 adds migration C (A -> C) - This now causes multiple heads
In jetbase:
- Current head is 1 - dev1 adds migration 2 - dev2 adds migration 2 (but different file contents then branch 1) - The second migration will fail. its version will have to be updated to be > 2 to pass.
jetbase example 2:
- Current head is 1 - dev1 adds migration 2 - dev2 adds migration 3 - if dev1 runs first, then all migrations will be successful. if dev2 runs first, then dev1 will fail because its version is lower than the new head (3)
(sidenote - you can also use 'jetbase new "migration_description"' to automatically generate a new migration file using a timestamp as the version. This can also help stop version conflicts)
In jetbase, it's also easy to see in what order any pending migrations will apply using 'jetbase status'. Below I've listed the migration order related commands.
jetbase status - shows all applied migrations (in order) vs. pending migrations (in order)
jetbase history - shows all applied migrations in order and when they were applied
jetbase current - shows latest migration (head)
In jetbase, migrations are linear. They're applied in ascending version order. So there will always only be one head. any versions introduced that are the same or lower than the current head will fail their migration.
In alembic:
- Current head is A - dev1 adds migration B (A -> B) - dev2 adds migration C (A -> C) - This now causes multiple heads
In jetbase:
- Current head is 1 - dev1 adds migration 2 - dev2 adds migration 2 (but different file contents then branch 1) - The second migration will fail. its version will have to be updated to be > 2 to pass.
jetbase example 2:
- Current head is 1 - dev1 adds migration 2 - dev2 adds migration 3 - if dev1 runs first, then all migrations will be successful. if dev2 runs first, then dev1 will fail because its version is lower than the new head (3)
(sidenote - you can also use 'jetbase new "migration_description"' to automatically generate a new migration file using a timestamp as the version. This can also help stop version conflicts)
In jetbase, it's also easy to see in what order any pending migrations will apply using 'jetbase status'. Below I've listed the migration order related commands.
jetbase status - shows all applied migrations (in order) vs. pending migrations (in order)
jetbase history - shows all applied migrations in order and when they were applied
jetbase current - shows latest migration (head)
Jetbase has: - strict validation to detect altered or removed migration files after they’ve been applied (prevents drift, fails fast) - database locking so multiple migration processes can’t run at the same time - full rollback support - ascending version numbers enforced directly in filenames so migration history is obvious - uses raw sql instead of ORMs
The main Python tool is Alembic, but it’s mainly used with an ORM and doesn’t include things like validation checks. So I built Jetbase to add the features I was looking for.
Some other things I ran into:
- tools with more validation checks than Alembic were usually Java-based, not Python - some tools gate rollback support behind paid tiers - wanted a way to easily see migrations history
Moved off ORMs to raw SQL, which made Alembic’s ORM integration not necessary. Why I moved off: - explored queries directly in DB UI tools (DBeaver, Snowflake) and didn’t want to rewrite them in ORM syntax - ORMs didn’t make sense for Python data pipelines (S3 → Snowflake → Postgres) - raw SQL was more efficient for things beyond basic CRUD - shared a database with a sister team and didn’t want to create extra ORM models in API to query their stuff
Repo (with a quick start guide): https://github.com/jetbase-hq/jetbase
It currently supports Postgres and SQLite (planning to add more databases)
Would love to hear any feedback!