pytest-databases

References Index

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

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

• 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.