db-git

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

Features

• 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.

Supported databases

See the database guides for required privileges, client tools, and engine-specific limitations.

Quick start

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 command

Install 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.

Learn more

• Choose shared or per-branch mode
• Run applications and migrations
• Work with Git worktrees
• Save checkpoints and inspect history
• Command reference
• Configuration
• Troubleshooting
• Recovery

Contributing

See the development guide for dependencies and tests, and the documentation guide for local preview and publishing.

License

MIT