/pytest-databases

name: pytest-databases
description: "Use when working with pytest_databases, Docker DB fixtures, PostgreSQL/pgvector/ParadeDB, MySQL/MariaDB, Oracle/SQL Server, CockroachDB, MongoDB, Redis/Valkey, BigQuery/Spanner, MinIO, or RustFS. Not for mocked DBs."

pytest-databases

`pytest-databases` provides session-scoped, container-backed service fixtures. This guidance targets the immutable `v0.19.0` tag. Load only the plugin modules the test suite uses. Consume a ready client fixture where one exists; otherwise connect with the client already used by the project.

Code Style Rules

• Keep database I/O consistent with the project driver. The package's

PostgreSQL connection fixtures use synchronous `psycopg`; do not `await` their methods.

• Type service fixtures with the service class from the same plugin module.
• Prefer ready client fixtures when provided. For service-only plugins, build

the project's existing client from the service object's host, port, and credentials.

• Keep plugin declarations in the nearest `conftest.py`; do not load every

backend globally.

Quick Reference

Install and enable

pip install "pytest-databases[postgres]"

In `conftest.py`:

pytest_plugins = ["pytest_databases.docker.postgres"]

The core `pytest_databases` pytest entry point supplies `docker_client` and `docker_service`. Each database module supplies its own fixtures.

Choose the fixture shape

| Need | Use | | --- | --- | | A ready `psycopg` connection | `postgres_connection`, a versioned PostgreSQL-family connection, or `cockroachdb_connection` | | A ready vendor client | `bigquery_client`, `spanner_connection`, `mongodb_connection`, an Oracle connection, a GizmoSQL connection, or an Azure Blob container client | | Service coordinates for the project's own client | The backend's `*_service` fixture | | A specific PostgreSQL-family release | Matching `*_NN_service`, `*_NN_connection`, and `*_NN_port` fixtures | | Parallel worker isolation | The backend's exact `*_xdist_isolation_level` fixture from [xdist.md](references/xdist.md) |

See [reference.md](references/reference.md) for the exact plugin, service, and ready-client matrix. Do not infer a `*_connection` fixture from a `*_service` fixture's name.

<workflow>

Workflow

1. Install the extra matching the selected backend. Backends with no bundled Python client, such as MySQL, MariaDB, SQL Server, and YugabyteDB, expose service fixtures and expect the project to supply its own driver. 2. Add only the required `pytest_databases.docker.<module>` entries to `pytest_plugins`. 3. Prefer a ready client fixture listed in [reference.md](references/reference.md). Otherwise construct the project's existing client from the typed service fixture. 4. Override session-scoped configuration fixtures in `conftest.py`. Use environment variables only where 0.19.0 explicitly reads them; see [config.md](references/config.md). 5. For `pytest-xdist`, keep the default `"database"` isolation when the service supports logical namespaces. Override the backend's exact isolation fixture to `"server"` when each worker needs its own container. 6. Run the focused integration tests against a Docker-compatible daemon.

</workflow>

<guardrails>

Guardrails

• **Connection fixtures vs service fixtures**: Ready-client fixtures

(`*_connection`, `*_client`) exist for PostgreSQL-family, CockroachDB, Oracle, GizmoSQL, BigQuery, Spanner, MongoDB, and Azure Blob. Service-only backends (MySQL, MariaDB, SQL Server, YugabyteDB, Dolt, Redis, Dragonfly, KeyDB, Valkey, Elasticsearch, MinIO, and RustFS) export `*_service` fixtures but no ready client fixture. Note that `redis`, `valkey`, and `elastic_search` still import their Python client package at module load time for readiness checks, whereas `mysql`, `mariadb`, `mssql`, `yugabyte`, `dolt`, `minio`, and `rustfs` require no Python client dependency to start the service.

• **Avoid broken alias fixtures in `v0.19.0`**:

`elasticsearch_service` requests an undefined `elasticsearch8_service` fixture (missing underscore) — request `elasticsearch_8_service` or `elasticsearch_7_service` directly. `oracle_startup_connection` requests an undefined `oracle_23ai_startup_connection` fixture — request `oracle_23ai_connection` or `oracle_18c_connection` instead.

• **Use exact `pytest_databases.docker.*` module names.** AlloyDB Omni,

pgvector, and ParadeDB live in `pytest_databases.docker.postgres` (not `alloydb`); Azurite / Azure Blob lives in `pytest_databases.docker.azure_blob` (not `azurite`, with `AzureBlobService`, `azure_blob_container_client`, and `azure_blob_async_container_client`); Elasticsearch lives in `pytest_databases.docker.elastic_search` (not `elasticsearch` or `ElasticSearch`); Dragonfly and KeyDB live in `pytest_databases.docker.redis`.

• **Keep synchronous fixtures synchronous.** `postgres_connection` is a

`psycopg.Connection`; call `execute()` directly.

• **Do not assume every backend uses the same xdist fixture name.** Azure Blob

uses `azure_blob_xdist_isolation_level`; most others use `xdist_<backend>_isolation_level`.

• **Do not pass custom `pytest` CLI flags.** Version `0.19.0` registers no

`pytest_addoption` flags; configure services via session-scoped fixture overrides or the environment variables in [config.md](references/config.md).

• **Do not hand-roll container teardown.** The package owns labelled container

lifecycle through `docker_service`.

• **Do not pin a host port without a reason.** Dynamic ports avoid conflicts.

Use the 0.19.0 PostgreSQL-family `*_port` fixture or matching environment variable only when a rootless/container-network constraint requires it (`redis_port`, `dragonfly_port`, `keydb_port`, and `valkey_port` only read `*_service.port`).

</guardrails>

<validation>

Validation Checkpoint

• [ ] Installed version is `pytest-databases>=0.19.0`.
• [ ] `pytest_plugins