pytest-databases

What it is and what it does

pytest-databases is a pytest plugin that provides ready-made fixtures for running database services in Docker containers during tests. Instead of mocking or using in-memory databases, it lets you test against real database instances—Postgres, MySQL, Oracle, SQL Server, Redis, Elasticsearch, and others—each isolated in its own container. The plugin handles container startup, configuration, and teardown automatically.

You declare which database you want in your conftest.py, then inject the service fixture into your test functions. The fixture exposes connection details (host, port, user, password, database name) so you can connect with your normal database client library. This approach trades setup time for test fidelity: your tests run against the actual database engine, not a mock, catching real schema and driver issues before production.

Use it for:

• Integration testing a web application against a real Postgres or MySQL database without manual container management.
• Testing database migrations and schema changes against multiple database versions in parallel CI jobs.
• Validating ORM queries and raw SQL against Oracle or SQL Server in a containerized test environment.
• Testing Redis or Elasticsearch client code with a real service instance isolated per test run.
• Verifying multi-database support in a library by running the same test suite against Postgres, MySQL, and CockroachDB fixtures.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides pytest fixtures that spin up isolated database services in Docker containers for testing, supporting Postgres, MySQL, Oracle, SQL Server, Redis, Elasticsearch, and other databases.

Yes, if you need real database testing in a containerized environment. The low install friction, active maintenance, permissive license, and broad database support make it a solid choice for integration tests. The main gotcha is the Docker dependency—you must have Docker running, and container startup adds latency per test. For unit tests or projects that cannot use Docker, this is not the right tool.

Install

pytest-databases on PyPI

pip install pytest-databases

uv add pytest-databases

poetry add pytest-databases

Installing pytest-databases

Before you install

Low friction installation with a pure Python wheel. Maintenance is active with a recent release; the package is in Beta status and depends on docker, filelock, and pytest—all stable, widely-used libraries.

License in practice

MIT license is permissive; you can use, modify, and distribute this package freely in commercial or private projects with minimal restrictions.

Quickstart

pip install pytest-databases[postgres]

# In conftest.py:
pytest_plugins = ["pytest_databases.docker.postgres"]

# In test file:
from pytest_databases.docker.postgres import PostgresService

def test_example(postgres_service: PostgresService):
    # Use postgres_service.host, .port, .user, .password, .database

Requires Docker to be installed and running on the system; the package manages database container lifecycle but does not provide Docker itself.

Verify before relying

• Whether all listed database versions (Postgres 12–18, MySQL 5.6–8, Oracle 18c/23c, SQL Server 2022) are actively maintained in the fixture set.
• Performance characteristics and overhead of spinning up containers per test or per session.
• Whether the package handles cleanup and resource limits to prevent orphaned containers in CI/CD environments.

Package facts

Evidence: pytest_databases-0.19.0-py3-none-any.whl

Keywords: alloydb, alloydbomni, azure, bigquery, cockroachdb, database, doltdb, dragonflydb, duckdb, elasticsearch, flightsql, gizmosql, migration, mongodb, mssql, mysql, oracle, postgres, redis, spanner, valkey

Tags

More Testing packages