pytest-databases

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

---

<workflow>

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

</workflow> <guardrails>

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.

</guardrails> <validation>

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

</validation> <example>

Example: PostgreSQL integration test

import pytest

pytest_plugins = ["pytest_databases.docker.postgres"]


@pytest.mark.asyncio
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"

</example>

---

Cross-References

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

Official References

• https://github.com/litestar-org/pytest-databases
• https://litestar-org.github.io/pytest-databases/latest/

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.