dbfork

dbfork

Fast local PostgreSQL database branching for migrations, schema testing, and isolated development workflows.

dbfork is a Go CLI for local Postgres development. It creates instant database branches with PostgreSQL's native CREATE DATABASE ... TEMPLATE feature, so you can clone your development database in seconds, test migrations safely, inspect schema drift, and tear branches down when you are done.

• Clone a local PostgreSQL database in seconds instead of waiting on pg_dump | pg_restore
• Give each feature or migration its own disposable database branch
• Diff branch schema against the source database before you merge changes

Why dbfork?

• Fast local branching: CREATE DATABASE ... TEMPLATE is a server-side copy, so PostgreSQL duplicates the database on disk without moving rows through the client.
• Faster than pg_dump | pg_restore: for a 1 GB development database, pg_dump plus restore usually takes 2 to 5 minutes. Template cloning typically finishes in 1 to 3 seconds on the same machine.
• No extra infrastructure: no cloud account, no custom storage layer, and no fleet of extra Docker containers.

Compared to Other Local Workflows

dbfork is best when you want Git-style branching semantics for a local PostgreSQL database without paying the time cost of repeated dumps and restores.

Installation

Go install

go install github.com/Meru143/dbfork/cmd/dbfork@latest

Homebrew

Homebrew support is planned and will be published after the first tagged release.

Binary download

Download a release archive from the GitHub Releases page and unpack the binary for your platform.

Quick Start

docker-compose up -d
go install github.com/Meru143/dbfork/cmd/dbfork@latest
dbfork init
dbfork create feature-add-users
dbfork list

Typical next steps:

dbfork use feature-add-users
dbfork diff feature-add-users
dbfork drop feature-add-users --force

Command Reference

Config Reference

dbfork reads configuration from ~/.dbfork/config.toml by default:

default_host     = "localhost"
default_port     = 5432
default_user     = "postgres"
default_password = ""
default_database = "myapp_development"

Environment variables override file values:

• DBFORK_HOST
• DBFORK_PORT
• DBFORK_USER
• DBFORK_PASSWORD
• DBFORK_DATABASE
• DBFORK_CONFIG to point at an alternate TOML file

How It Works

1. dbfork create <name> connects to the maintenance database (postgres).
2. It terminates idle sessions on the source database so PostgreSQL can use the source as a template.
3. It runs CREATE DATABASE <branch> TEMPLATE <source>.
4. It stores branch metadata in ~/.dbfork/state.json.
5. Later commands reuse that local state to list, connect, diff, switch, and drop branches.

Limitations

• PostgreSQL refuses template cloning while other sessions are connected to the source database. dbfork terminates idle sessions automatically, but active writers can still block the clone.
• Branching uses whole-database copies inside one PostgreSQL instance, so disk usage grows with each branch.
• dbfork diff is schema-focused in v1. It reports table, column, and index changes rather than row-level data drift.

Development

See CONTRIBUTING.md for local setup, test commands, and release workflow details. Regenerate the README demo GIF from WSL with wsl bash ./scripts/generate-demo.sh.