How to Isolate a Database Per Parallel Test Worker

Parallel workers hitting one shared database race on the same rows, so give each worker its own database or schema.

Derive a unique database name from the worker id (for example PYTEST_XDIST_WORKER) so each worker migrates and mutates its own isolated store.

Steps

• Read the worker id from the runner (xdist exposes PYTEST_XDIST_WORKER).
• Create or select a database/schema named after that worker.
• Run migrations per worker before its tests start.

Terminal

# example: derive a DB name per xdist worker
WORKER=${PYTEST_XDIST_WORKER:-gw0}
export DATABASE_URL="postgres://ci@localhost/app_${WORKER}"
createdb "app_${WORKER}" || true
pytest -n auto

Gotchas

• Creating a database per worker adds setup time; template databases speed this up.
• Tear down per-worker databases after the run so CI storage does not fill up.

Related guides