pytest-databases

name: pytest-databases description: "Auto-activate for pytest_databases, Docker DB fixtures, PostgreSQL/pgvector/AlloyDB Omni/MySQL/Oracle/MSSQL/CockroachDB/Yugabyte/MongoDB/GizmoSQL/Redis/Spanner/BigQuery/Azurite/MinIO tests. Not for mocked DBs."

A pytest plugin providing ready-made database fixtures for testing using Docker containers.

References Index

For detailed guides and code examples, refer to the following documents in references/:

Supported Databases
- Examples for PostgreSQL, MySQL, Oracle with service/connection fixtures.
Complete Reference
- Fixture tables for all supported SQL, KV, Search, and Object Storage databases.
Xdist Parallel Testing
- Isolation levels (database vs server) and helper functions.
Configuration
- Fixture overrides and environment variable support.
Troubleshooting
- ARM architecture tips, port conflicts, and health checks.

Quick Start

1. Enable in Project

Add to conftest.py:

pytest_plugins = ["pytest_databases.docker.postgres"]

2. Use Fixtures

def test_database(postgres_service):
    # Use postgres_service.host, .port, etc.
    pass

Guardrails

Keep fixtures container-based. Do not monkey-patch or mock the database client — prefer the real service fixture so tests cover driver behavior.
Use xdist isolation helpers. For parallel runs, select the database-level or server-level isolation fixtures from references/xdist.md instead of sharing one schema across workers.
Do not hand-roll container lifecycle. Rely on the plugin's fixtures; they handle startup, readiness, and teardown.
Scope fixtures to the smallest unit that works. A session-scoped Docker container with function-scoped schemas is almost always the right trade-off.

Validation Checkpoint

conftest.py declares only the database plugins you actually use (pytest_plugins = [...])
Tests pull the correct fixture (postgres_service, mysql_service, etc.) rather than opening raw connections
Parallel runs (pytest -n auto) produce isolated data — verified via references/xdist.md
CI runs Docker-in-Docker (or Podman) with enough resources for the requested fixtures

Example: PostgreSQL integration test

import pytest

pytest_plugins = ["pytest_databases.docker.postgres"]


@pytest.mark.anyio
async def test_user_insert(postgres_service, postgres_connection):
    await postgres_connection.execute(
        "INSERT INTO users (email) VALUES ($1)", "alice@example.com"
    )
    row = await postgres_connection.fetchrow(
        "SELECT email FROM users WHERE email = $1", "alice@example.com"
    )
    assert row["email"] == "alice@example.com"

Cross-References

litestar-testing — Litestar-specific testing patterns; integrates pytest-databases fixtures with AsyncTestClient.

Official References

Shared Styleguide Baseline

Use shared styleguides for generic language/framework rules to reduce duplication in this skill.
General Principles
Testing
Python
Keep this skill focused on tool-specific workflows, edge cases, and integration details.