Pytest Databases

pytest-databases

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](references/databases.md)
• Examples for PostgreSQL, MySQL, Oracle with service/connection fixtures.
• [Complete Reference](references/reference.md)
• Fixture tables for all supported SQL, KV, Search, and Object Storage databases.
• [Xdist Parallel Testing](references/xdist.md)
• Isolation levels (database vs server) and helper functions.
• [Configuration](references/config.md)
• Fixture overrides and environment variable support.
• [Troubleshooting](references/troubleshooting.md)
• 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-testing/SKILL.md) — 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](../litestar-styleguide/references/general.md)
• [Testing](../litestar-styleguide/references/testing.md)
• [Python](../litestar-styleguide/references/python.md)
• Keep this skill focused on tool-specific workflows, edge cases, and integration details.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: litestar-org
• Source: litestar-org/litestar-skills
• License: MIT
• Homepage: https://github.com/litestar-org/litestar-skills

Install and usage instructions live in the source repository linked above.