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

See 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. 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.
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.
• 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 names an existing module from reference.md.
• Every requested fixture exists in that module's 0.19.0 fixture row.
• Service-only backends use the project's own client rather than a fabricated *_connection fixture.
• PostgreSQL connection examples use synchronous psycopg calls.
• Configuration uses an actual fixture or environment variable from config.md.
• Xdist overrides use the backend's exact isolation-fixture name.
• Container-backed tests run against a Docker-compatible daemon.

</validation> <example>

Example: synchronous PostgreSQL connection

import psycopg

pytest_plugins = ["pytest_databases.docker.postgres"]


def test_postgres_is_ready(
    postgres_connection: psycopg.Connection,
) -> None:
    row = postgres_connection.execute("SELECT 1").fetchone()

    assert row == (1,)

postgres_connection is a synchronous psycopg.Connection. Use an async driver only by constructing it separately from postgres_service.

</example>

---

References Index

• Supported database patterns — ready-client and service-only examples.

• Complete fixture matrix — exact 0.19.0 modules, classes, service fixtures, and client/provider fixtures.

• Xdist parallel testing — supported isolation fixture names and helper functions.

• Configuration — fixture overrides and environment variables implemented by 0.19.0.

• Troubleshooting — runtime, plugin, client, and port failures.

• Litestar testing — integrate container-backed services with Litestar test clients and dependency overrides.

Official References

• https://pypi.org/project/pytest-databases/0.19.0/
• https://github.com/litestar-org/pytest-databases/tree/v0.19.0
• https://github.com/litestar-org/pytest-databases/tree/v0.19.0/src/pytest_databases/docker
• https://github.com/litestar-org/pytest-databases/tree/v0.19.0/tests

Shared Styleguide Baseline

• General Principles
• Testing
• Python