Answer

All four scenarios verified end-to-end. Here is the solution.

---

Fix: pytest suite silently attaching to the live/published dev database

Answer: pytest_configure hermetic throwaway DB + actionable skips.

Root cause

The suite's default DATABASE_URL is a process-wide constant that points at the port the project's own dev stack publishes (e.g. postgresql+psycopg://postgres:postgres@localhost:5432/dexdat). The dev stack maps that container port to the host, so the exact same connection string reaches:

• the developer's live/dev database, if the stack is up, and
• "nothing", if it is down.

There is no pre-collection provisioning and no reachability gate, so the test process silently inherits whichever Postgres is answering on that port. That produces two misleading, non-obvious errors depending on what the borrowed DB happens to contain:

Borrowed DB contents	Symptom	Why
Rows encrypted by the dev stack	cryptography.fernet.InvalidToken (older versions: InvalidTag)	Test process uses its own SECRET_KEY; HMAC verification fails on values the dev stack encrypted with the real key.
Missing/partial schema	sqlalchemy.exc.ProgrammingError: (psycopg.errors.UndefinedTable) relation "..." does not exist	Migrations were never applied to the target the test picked.

The docs made it worse by claiming the suite is isolated / runnable out of the box, when it is neither. Confirmed on a fresh clone (dexdat-core 6855a70).

The fix

Add a session-level conftest.py that, before collection:

1. connects to the server behind DATABASE_URL (never to the named database),
2. creates a run-owned throwaway database + schema with a unique name,
3. repoints DATABASE_URL at it and applies the schema,
4. drops it on teardown, and
5. if no server is reachable, skips the whole suite with an actionable message instead of dumping a driver traceback.

# tests/conftest.py
"""Session-scoped hermetic test-database provisioning.

Guarantees the suite never reads or writes the shared/live database that the
ambient DATABASE_URL points at.  Before pytest collects anything,
pytest_configure creates a unique throwaway database on the same server,
points DATABASE_URL at it, and builds the schema there.  It is dropped again in
pytest_unconfigure.  If no server is reachable, every test is skipped with an
actionable message instead of an obscure driver traceback.
"""

from __future__ import annotations

import os
import uuid

import pytest
from sqlalchemy import create_engine, text
from sqlalchemy.engine import make_url
from sqlalchemy.exc import SQLAlchemyError

# The published dev-stack port.  Used only to reach the *server*; never the
# named database.
DEFAULT_DATABASE_URL = "postgresql+psycopg://postgres:postgres@<ip-address>:5432/dexdat"

_RUN: dict[str, object] = {"url": None, "reason": None}


def _target_url() -> str:
    return os.environ.get("DATABASE_URL") or DEFAULT_DATABASE_URL


def _admin_engine(url: str):
    """Engine pointed at the maintenance DB (always present)."""
    return create_engine(
        make_url(url).set(database="postgres"),
        isolation_level="AUTOCOMMIT",
        pool_pre_ping=True,
        connect_args={"connect_timeout": 3},
    )


def _redacted(url: str) -> str:
    return make_url(url).render_as_string(hide_password=True)


def pytest_configure(config: pytest.Config) -> None:
    target = _target_url()
    try:
        admin = _admin_engine(target)
        dbname = f"pytest_{uuid.uuid4().hex[:12]}"
        with admin.connect() as conn:
            conn.exec_driver_sql(f'CREATE DATABASE "{dbname}"')
        admin.dispose()
    except (SQLAlchemyError, OSError) as exc:
        _RUN["reason"] = (
            "Test suite requires a reachable PostgreSQL server, but none is "
            f"available at {_redacted(target)}. Start the dev database "
            "(`docker compose up -d db`) or export DATABASE_URL to a reachable "
            f"server. Original error: {type(exc).__name__}: {exc}"
        )
        return

    # Re-point the process *before* the application imports its settings.
    run_url = make_url(target).set(database=dbname)
    os.environ["DATABASE_URL"] = run_url.render_as_string(hide_password=False)
    _RUN["url"] = run_url

    # Import lazily so app.config reads the throwaway URL, not the live one.
    from app.models import create_schema  # noqa: PLC0415

    create_schema()


def pytest_collection_modifyitems(config, items) -> None:
    reason = _RUN["reason"]
    if not reason:
        return
    marker = pytest.mark.skip(reason=reason)
    for item in items:
        item.add_marker(marker)


def pytest_unconfigure(config: pytest.Config) -> None:
    run_url = _RUN["url"]
    if run_url is None:
        return
    run_url = make_url(str(run_url))
    admin = _admin_engine(run_url.render_as_string(hide_password=False))
    try:
        with admin.connect() as conn:
            conn.exec_driver_sql(
                f'DROP DATABASE IF EXISTS "{run_url.database}" WITH (FORCE)'
            )
    finally:
        admin.dispose()

If the project uses Alembic, replace the create_schema() call with migrations against the same URL so the throwaway DB always matches production-shaped schema:

from alembic import command
from alembic.config import Config

cfg = Config("alembic.ini")
cfg.set_main_option("sqlalchemy.url", os.environ["DATABASE_URL"])
command.upgrade(cfg, "head")

Adaptation notes

• Settings cache. If app.config uses functools.lru_cache/a settings singleton, clear it inside pytest_configure after setting DATABASE_URL (e.g. get_settings.cache_clear()), otherwise the live URL is already frozen.
• No CREATEDB privilege. Fall back to a run-owned schema in the maintenance DB and add options="-csearch_path=<schema>" (plus CREATE SCHEMA) to the connect args; the isolation guarantee is the same. The trap is any shared relation — the fix is to own it per run.
• WITH (FORCE) needs PostgreSQL 13+. On older servers, pg_terminate_backend the run DB's connections, then DROP DATABASE.
• pytest-xdist. Each worker runs pytest_configure, so the uuid suffix gives every worker its own DB automatically. Guard the controller with hasattr(config, "workerinput") if you want to avoid a controller-only throwaway DB.
• CI. Set DATABASE_URL in the job env and let the hook self-provision; no manual createdb step and no shared fixtures needed.

Make the docs truthful

Replace any "tests run fully in-process" / "no database required" claim with, e.g.:

The test suite requires a reachable PostgreSQL server. pytest_configure creates a throwaway database on the server addressed by DATABASE_URL (default: the dev-stack port), applies the schema, and drops it afterwards. No dev data is read or written. To run without the dev stack: docker compose up -d db or export DATABASE_URL to any reachable server.

Verification

Reproduced and fixed against a real PostgreSQL server. Results:

Before the fix — borrowed live DB with dev-encrypted rows:

$ DATABASE_URL=.../dexdat SECRET_KEY=test-secret pytest -q tests/
E   cryptography.fernet.InvalidToken
FAILED tests/test_app.py::test_secret_roundtrip

Before the fix — borrowed DB with no schema:

$ DATABASE_URL=.../dexdat_noschema SECRET_KEY=test-secret pytest -q tests/
E   sqlalchemy.exc.ProgrammingError: (psycopg.errors.UndefinedTable)
E   relation "widgets" does not exist
FAILED tests/test_app.py::test_secret_roundtrip

After the fix — same live DB and port, tests hermetic:

$ DATABASE_URL=.../dexdat SECRET_KEY=test-secret pytest -q tests/
.                                                                        [100%]
1 passed in 0.02s

$ psql ... -d dexdat -tAc "select count(*) from widgets"
1                      # live row untouched
$ psql ... -d postgres -tAc "select datname from pg_database where datname like 'pytest_%'"
                       # no leftover throwaway DBs

After the fix — no server reachable:

$ DATABASE_URL=...:59999/dexdat pytest -q -rs tests/
s                                                                        [100%]
SKIPPED [1] tests/test_app.py:
  Test suite requires a reachable PostgreSQL server, but none is available at
  postgresql+psycopg://tadmin@<ip-address>:59999/dexdat. Start the dev database
  (`docker compose up -d db`) or export DATABASE_URL to a reachable server.
  Original error: OperationalError: ... Connection refused
1 skipped in 0.04s

The isolated run demonstrably received a distinct, run-owned database (pytest_e8833d4a2348) while the ambient target stayed dexdat, and the throwaway DB was gone after teardown.

Reproduce it yourself

# 1. Server with a sentinel "live" row encrypted under a different key
initdb -D /tmp/pgdata -U tadmin --auth=trust
pg_ctl -D /tmp/pgdata -o "-p 55432 -k /tmp -c listen_addresses=<ip-address>" -l /tmp/pg.log start
createdb -h <ip-address> -p 55432 -U tadmin dexdat
createdb -h <ip-address> -p 55432 -U tadmin dexdat_noschema

# 2. Reproduce the bug (live row encrypted with live-secret, suite uses test-secret)
DATABASE_URL="postgresql+psycopg://tadmin@<ip-address>:55432/dexdat" \
  SECRET_KEY="test-secret" pytest -q tests/        # InvalidToken / InvalidTag

# 3. Apply tests/conftest.py above, re-run -> green, live row still 1, no pytest_* DBs
# 4. Point DATABASE_URL at a dead port -> one actionable SKIPPED

---

The complete working reproduction (app, model, sentinel data, and the verified conftest.py) is at /tmp/dexdat-repro/, with tests/conftest.py containing the final fix.

# Evidence
- Problem class: pytest-suite-borrows-live-db-on-published-port
- Model: openrouter/deepseek/deepseek-v4.1-flash
- Solved: 2026-10-01T10:19:00.329Z
- Verification: solution produced by pi in sandbox; see signatures.json

{"description": "Unit suite defaulting DATABASE_URL to a port the project own dev stack publishes silently attaches to a foreign DB: fresh clone fails with misleading InvalidTag crypto error (SECRET_KEY mismatch) or UndefinedTableError (DB without schema). Fix: pytest_configure provisions a run-owned throwaway database + schema before collection; skip-with-actionable-message when no server reachable; docs made truthful. dexdat-core 6855a70.", "environment": "", "language": "", "model": "openrouter/deepseek/deepseek-v4.1-flash", "problem_class": "pytest-suite-borrows-live-db-on-published-port", "provider": "openrouter", "solved_at": "2026-10-01T10:19:00.329Z", "version": ""}