Metadata-Version: 2.4
Name: django-baseshift-brancher
Version: 0.12.0
Summary: Run Django and pytest against a Baseshift clone of an already-migrated PostgreSQL database.
Author: Baseshift
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://baseshift.io
Keywords: django,pytest,postgresql,baseshift
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=3.2
Provides-Extra: pytest
Requires-Dist: pytest>=6.2; extra == "pytest"
Requires-Dist: pytest-django>=4.5; extra == "pytest"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-django>=4.5; extra == "dev"
Requires-Dist: psycopg[binary]>=3.1; extra == "dev"
Dynamic: license-file

# django-baseshift-brancher

Run Django and pytest against a PostgreSQL database that is already migrated. Tests do not `CREATE DATABASE` and do not run migrations again.

This package applies migrations. Each new snapshot runs `BASESHIFT_INIT_SQL` before migrate when a migration needs an extension. Seed data and project management commands run on the clones afterwards.

This package does not include the `baseshift` program that creates those databases. Install that binary separately and put it on `PATH`. `django-baseshift-brancher clone` asks that program for one snapshot per git commit that changes migrations, reuses snapshots this checkout shares with other branches, and starts one Postgres per test worker. That program is not the PyPI project named `baseshift`.

```bash
pip install django-baseshift-brancher
# if pytest-django is not already installed:
pip install 'django-baseshift-brancher[pytest]'
```

## Clone the current checkout

From the Django project directory:

```bash
export DJANGO_SETTINGS_MODULE=yourproject.settings
unset BASESHIFT_BRANCHES_FILE DATABASE_URL PGHOST PGPORT

django-baseshift-brancher clone --count 4
```

`clone` looks at git. Each commit that adds, removes, or replaces migration files is a snapshot. Adding files continues the previous snapshot, so two branches that diverged from the same migration commit share it. Replacing or removing a migration file starts again from the empty snapshot, because that schema cannot be applied on top of the previous one. A rebase writes a new commit, so that checkout gets a new snapshot on the new parent. A branch that left before the rebase keeps its own chain. You do not name snapshots or parents.

The command prints clone JSON and writes it to `.brancher/clones.json`. stderr prints the `BASESHIFT_BRANCHES_FILE` export. `--count` is the number of databases (one per pytest worker).

```bash
export BASESHIFT_BRANCHES_FILE="$PWD/.brancher/clones.json"
pytest -n 4
baseshift stop --all
```

`clones.json` is not picked up from the working directory. The `BASESHIFT_BRANCHES_FILE` export is what the tests read.

pytest needs no `settings.py` change. The plugin loads itself, points each worker at one clone, and forces `--reuse-db` and `--no-migrations`. Do not pass `--create-db`.

Django's runner needs one flag:

```bash
python manage.py test --testrunner django_baseshift_brancher.DiscoverRunner --parallel 4
```

`--parallel 4` and `pytest -n 4` both need four clones. pytest worker `gw0` uses the first clone. Django's worker suffix is 1-based: `"1"` uses the first clone.

Existing `DATABASES` `USER` and `PASSWORD` are kept. `HOST`, `PORT`, and `NAME` are rewritten onto the clone, and migrations during tests are turned off.

```bash
export BASESHIFT_INIT_SQL="CREATE EXTENSION IF NOT EXISTS pg_trgm"   # when a migration needs it
```

That SQL runs on each new snapshot before migrate. After the clones are up, run project commands yourself — for example `ensure_celery_broker_schema` — against those DSNs.
