django-baseshift-brancher

Run your Django test suite against an already-migrated PostgreSQL clone, so tests don't need to run CREATE DATABASE or migrations on every run.

On a large Django project, a lot of test time goes to building the test database and replaying every migration. django-baseshift-brancher skips both steps. It uses brancher by Baseshift to create one ready-to-use PostgreSQL clone per test worker, already migrated to the schema of your current git checkout. Then it points pytest or Django's test runner at those clones.

• Works with pytest / pytest-django (pytest -n N) and Django's manage.py test (--parallel N)
• No changes to settings.py
• Migrated snapshots are cached per migration commit and shared across branches

This package does not include the brancher binary. Install that first. On macOS the curl command uses Homebrew; on Linux it downloads the binary.

curl -fsSL https://dl.baseshift.com/brancher/install.sh | bash

brew install baseshift/tap/brancher

---

Requirements

Requirement	Version
Python	3.8 – 3.13
Django	3.2, 4.2, 5.0 – 6.0
Database	PostgreSQL
brancher by Baseshift	The brancher binary on your PATH (baseshift.com/brancher)
Git	Your project must be a git repository

---

Install

pip install django-baseshift-brancher

# If pytest-django isn't installed yet:
pip install "django-baseshift-brancher[pytest]"

---

Quick start

Run these from your Django project root (the directory that contains manage.py).

1. Create the clones

export DJANGO_SETTINGS_MODULE=yourproject.settings
unset BASESHIFT_BRANCHES_FILE DATABASE_URL PGHOST PGPORT

django-baseshift-brancher clone --count 4

clone creates the brancher root on the first run, then builds the snapshots and starts the clones. That is enough.

Initializing the root yourself is optional. Do it when you want to choose the snap key and the PostgreSQL bin directory (the directory that contains initdb). brancher keygen prints a 64-character hex key. Leave that key in the environment so clone can open the root:

export BRANCHER_SNAP_KEY="$(brancher keygen)"
brancher init --pg-bin /usr/lib/postgresql/16/bin

django-baseshift-brancher clone --count 4

A key file works the same way. Pass it to both commands: brancher init --pg-bin /usr/lib/postgresql/16/bin --key-file snap.key, then django-baseshift-brancher clone --count 4 --key-file snap.key.

--count is the number of databases to create. You need one per test worker.

The command writes the clone details to .brancher/clones.json, prints them as JSON, and prints the export line you need next (on stderr).

2. Run the tests

pytest

export BASESHIFT_BRANCHES_FILE="$PWD/.brancher/clones.json"
pytest -n 4

Django test runner

export BASESHIFT_BRANCHES_FILE="$PWD/.brancher/clones.json"
python manage.py test --testrunner django_baseshift_brancher.DiscoverRunner --parallel 4

3. Clean up

brancher stop --all

---

How it works

Snapshots follow your migration history

clone reads your git history. Every commit that changes migration files gets its own migrated snapshot.

• Adding migration files builds on the previous snapshot. Branches that split off from the same migration commit share it.
• Changing or deleting existing migration files starts over from an empty snapshot, because the new schema can't be built on top of the old one.
• Rebasing creates new commits, so the rebased checkout gets a new snapshot on top of its new parent. Branches that split off before the rebase keep their own chain.

Snapshots don't have names and you never manage them yourself. Parent snapshots are picked automatically.

Test workers map to clones

Runner	Worker ID	Clone used
pytest-xdist	gw0, gw1, … (0-based)	gw0 → 1st clone
Django --parallel	"1", "2", … (1-based)	"1" → 1st clone

pytest -n 4 and --parallel 4 each need --count 4 (or more).

What happens to your DATABASES setting

• USER and PASSWORD are kept as you configured them.
• HOST, PORT and NAME are replaced with the clone's values.
• Test migrations are turned off (the clone is already migrated).

pytest plugin

The plugin loads automatically. It assigns each worker to a clone and forces --reuse-db and --no-migrations. Don't pass --create-db.

---

Configuration

Environment variable	Required	Purpose
DJANGO_SETTINGS_MODULE	Yes	Your Django settings module
BASESHIFT_BRANCHES_FILE	Yes, when running tests	Absolute path to .brancher/clones.json. Tests only read the clones from this variable. A clones.json in the current directory is not picked up automatically.
BASESHIFT_INIT_SQL	No	SQL that runs on each new snapshot before migrate. Use it for anything your migrations assume already exists, such as extensions.

Example:

export BASESHIFT_INIT_SQL="CREATE EXTENSION IF NOT EXISTS pg_trgm"

Other setup commands: once the clones are running, run any extra project setup yourself against their connection strings (for example, a management command like ensure_celery_broker_schema).

---

Troubleshooting

Symptom	Likely cause	Fix
Tests connect to your normal dev/CI database	BASESHIFT_BRANCHES_FILE isn't set in the shell running the tests	export BASESHIFT_BRANCHES_FILE="$PWD/.brancher/clones.json"
Some workers fail or no clone is found for them	Fewer clones than workers	Re-run clone with --count ≥ -n / --parallel
Tests try to create the database	--create-db was passed	Remove --create-db
A migration fails with a missing extension	The extension has to exist before migrations run	Set BASESHIFT_INIT_SQL and re-run clone
brancher: command not found	brancher isn't installed	Run the curl or Homebrew command at the top of this page

---

For AI coding agents

Use this exact sequence from the Django project root. Replace N with the number of parallel test workers.

export DJANGO_SETTINGS_MODULE=<project>.settings
unset BASESHIFT_BRANCHES_FILE DATABASE_URL PGHOST PGPORT
django-baseshift-brancher clone --count N
export BASESHIFT_BRANCHES_FILE="$PWD/.brancher/clones.json"
pytest -n N                     # or: python manage.py test --testrunner django_baseshift_brancher.DiscoverRunner --parallel N
brancher stop --all

Rules:

• clone creates the root. brancher init beforehand is optional; see Quick start.
• Don't edit settings.py.
• Don't pass --create-db.
• Re-run clone after checking out a commit with different migrations.
• BASESHIFT_BRANCHES_FILE must be exported in the same shell that runs the tests.
• Always run brancher stop --all when you're done.

---

About Baseshift

Baseshift gives every developer, coding agent and pull request its own isolated, writable, masked clone of your real database, running in your cloud and ready in seconds. It supports PostgreSQL, MySQL, MongoDB and MariaDB. It also adds guardrails for database changes, such as schema change detection and query risk checks, so issues are caught before they reach production.

This package is the Django integration for brancher by Baseshift.

License

Proprietary. See baseshift.com for terms.