db-git 0.1.0

Keep your database in sync with your git branches.

git-db

Keep your database in sync with your git branches.

git-db is a developer tool for projects where database state follows code changes: schema migrations, seed data, experimental feature work, and branch switching during reviews. It installs a git post-checkout hook and keeps your local database aligned with the branch you are working on.

Status: PostgreSQL is supported today; support for additional database engines is planned.

Features

• Automatic database handling on git checkout
• Two workflows:
  • shared: one database, saved and restored per branch
  • per-branch: one database per branch
• PostgreSQL support today, with plans for more database backends
• Two PostgreSQL snapshot strategies:
  • template: fast database clones using CREATE DATABASE ... TEMPLATE
  • pgdump: portable snapshots using pg_dump and pg_restore
• Manual save, restore, create, reset, list, status, and prune commands
• Safe hook behavior: checkout is never blocked by git-db failures
• Rich terminal output and local state stored under .git/git-db/

Quick Start

uv tool install git-db # or pip install git-db

Run this from inside a git repository:

git-db init --database-url postgresql://postgres:postgres@localhost:5432/myapp

Interactive init will ask:

• Whether to use shared or per-branch mode
• Whether to use template or pgdump strategy
• What to do when active connections block database operations
• Whether to install the git post-checkout hook

After setup, switch branches normally:

git checkout feature/auth

In shared mode, git-db saves the previous branch database and restores the new branch snapshot if one exists.

In per-branch mode, git-db creates or selects a database named from the current branch, for example:

myapp__feature__auth

Because the database name changes per branch, your application server also needs to connect to the branch database. For example, when working on feature/auth, point your app's DATABASE_URL at myapp__feature__auth.

Choosing a Mode

Shared Mode

Shared mode keeps one database name from DATABASE_URL.

Use this when:

• You want one familiar local database name
• You want branch-specific snapshots
• You are comfortable with git-db dropping and restoring that local database during branch switches

Per-Branch Mode

Per-branch mode creates a separate database for each branch. The configured default branch keeps the original database name and acts as the seed database.

Use this when:

• You want branch databases to persist independently
• You prefer creating new databases over repeatedly restoring one shared database

Choosing a Strategy

template

The template strategy uses PostgreSQL database cloning:

CREATE DATABASE target TEMPLATE source;

It is usually fast, but requires sufficient PostgreSQL privileges and can be blocked by active connections to the source or target database.

pgdump

The pgdump strategy uses pg_dump and pg_restore.

It is slower than template, but can be a better fit when template cloning is not available. It requires PostgreSQL client tools to be installed locally.

Commands

Initialize

git-db init --database-url postgresql://user:password@localhost:5432/myapp

Useful options:

git-db init \
  --database-url postgresql://user:password@localhost:5432/myapp \
  --mode per-branch \
  --strategy template \
  --on-active-connections terminate

Skip hook installation:

git-db init --database-url postgresql://localhost/myapp --no-hook

Inspect State

git-db status
git-db list

Shared Mode Commands

Save the current branch database:

git-db save

Restore the current branch database:

git-db restore

Save or restore a specific branch:

git-db save main
git-db restore feature/auth

Per-Branch Commands

Create a branch database before checking out the branch:

git-db create feature/auth

Drop and recreate a branch database from the seed database:

git-db reset feature/auth

The default branch database cannot be reset because it is the seed for other branch databases.

Prune Deleted Branches

Preview stale snapshots or branch databases:

git-db prune --dry-run

Remove stale snapshots or branch databases:

git-db prune --yes

Hook Management

Install or reinstall the checkout hook:

git-db hook install

Remove the checkout hook:

git-db hook remove

Temporarily disable git-db without removing the hook:

git-db disable
git-db enable

You can also skip hook behavior for a single checkout:

GIT_DB_SKIP=1 git checkout other-branch

Configuration

git-db init writes .git-db.toml at the repository root.

Example:

database_url = "postgresql://postgres:postgres@localhost:5432/myapp"
mode = "per-branch"
default_branch = "main"
strategy = "template"
on_active_connections = "terminate"

Supported configuration keys:

Key	Description	Default
database_url	Database connection URL	required
mode	shared or per-branch	shared
default_branch	Seed branch for per-branch mode	main
strategy	template or pgdump	required
on_active_connections	terminate or fail	terminate
snapshot_dir	Shared-mode snapshot metadata/dump directory	.git/git-db/snapshots
max_snapshots	Snapshot count kept by prune logic	20
force_terminate_timeout_ms	Active connection termination timeout	5000

Configuration precedence:

1. Built-in defaults
2. .git-db.toml
3. Environment variables
4. CLI options

Environment variables:

DATABASE_URL
GIT_DB_DATABASE_URL
GIT_DB_MODE
GIT_DB_STRATEGY
GIT_DB_ON_ACTIVE_CONNECTIONS
GIT_DB_SNAPSHOT_DIR
GIT_DB_MAX_SNAPSHOTS
GIT_DB_FORCE_TERMINATE_TIMEOUT_MS

GIT_DB_DATABASE_URL takes precedence over DATABASE_URL.

Active connections block an operation

Stop your development server, database console, migration watcher, or GUI client, then retry.

Alternatively, configure:

on_active_connections = "terminate"

Your PostgreSQL user may need superuser privileges or membership in pg_signal_backend to terminate sessions owned by other users.

Temporarily skip git-db

git-db disable
git checkout some-branch
git-db enable

Or for one command:

GIT_DB_SKIP=1 git checkout some-branch

Show full tracebacks

GIT_DB_DEBUG=1 git-db status

Development

Install dependencies:

uv sync --group dev

Run checks:

uv run ruff check .
uv run mypy src tests
uv run pytest tests/unit

Run the full nox suite:

nox

License

MIT