Keep your database in sync with your Git branches.
db-git is a developer tool for schema migrations, seed data, experimental
features, and branch switching during reviews. Its post-checkout hook keeps
your local database aligned with the branch you are working on.
Documentation · Browse docs in GitHub · Release notes
- Automatic database handling on Git checkout.
- Shared mode: save and restore branch-specific snapshots.
- Per-branch mode: keep an independent database for each branch.
- Launch applications and migrations with
db-git run -- <command>. - Named checkpoints, history, and explicit retention in shared mode.
- Git worktrees in per-branch mode.
- Read-only diagnostics and recoverable database operations.
- Checkout still completes if database handling fails, with recovery guidance.
| Database | Modes | Strategy |
|---|---|---|
| PostgreSQL | Shared and per-branch | template or pgdump |
| MySQL 8.0 / 8.4 | Shared and per-branch | mysqldump |
| SQLite | Per-branch | Online backup |
See the database guides for required privileges, client tools, and engine-specific limitations.
Requires Python 3.12+, Git, and an existing local development database. For PostgreSQL:
uv tool install db-git # or pip install db-git
# Run inside your application's Git repository.
db-git init --database-url postgresql://localhost/myapp --mode per-branch
git checkout -b feature/auth
db-git run -- npm run dev # replace with your application's commandInstall the hook during initialization. Your application must read DATABASE_URL;
restart it through db-git run after switching branches. The default branch keeps
the seed database, while other branches receive separate copies.
For MySQL, install uv tool install 'db-git[mysql]' and follow the
MySQL guide.
For SQLite, follow the SQLite guide.
- Choose shared or per-branch mode
- Run applications and migrations
- Work with Git worktrees
- Save checkpoints and inspect history
- Command reference
- Configuration
- Troubleshooting
- Recovery
See the development guide for dependencies and tests, and the documentation guide for local preview and publishing.