pytest-databases

0.17.0 verified Fri May 01 auth: no python

Reusable pytest fixtures for spinning up and tearing down real database containers (PostgreSQL, MySQL, Redis, MongoDB, and more) using Docker or podman. Current version 0.17.0, actively maintained by Litestar-org with monthly releases.

pip install pytest-databases

Common errors

error docker: Error response from daemon: driver failed programming external connectivity on endpoint ↓

cause The Docker container could not bind to the required port (often due to port conflicts).

fix

Stop any containers using the same port, or set the environment variable PYTEST_DATABASES_PORT to an available port.

error pytest.fixture function has more than one 'yield' ↓

cause Incorrect usage of multiple yields in a fixture function; pytest-databases fixtures should yield only once.

fix

Use the fixture as a context manager: with postgresql_fixture() as url: or simply declare it as a parameter in the test function.

error ModuleNotFoundError: No module named 'pytest_databases' ↓

cause The package is not installed in the current environment.

fix

Run pip install pytest-databases. Ensure the environment is activated.

error RuntimeError: Docker is not running ↓

cause Docker daemon is not started.

fix

Start Docker Desktop or Docker Engine, or set PYTEST_DATABASES_DOCKER_CMD to a running podman socket.

Warnings

gotcha The fixture yields a connection URL string, not a database client. You must use it to create your own connection or integrate with an ORM (e.g., SQLAlchemy). ↓

fix Use the URL with your database library: `engine = create_engine(postgresql_fixture)`.

breaking From v0.13.0 onward, some fixtures (e.g., Redis) no longer use server isolation mode by default. If you relied on isolated containers per test, you may need to set `isolation_mode='server'` explicitly. ↓

fix Add `isolation_mode='server'` to the fixture decorator or mark test with `@pytest.mark.isolation_mode('server')`.

gotcha The library requires Docker or podman to be running. If the container runtime is unavailable, tests will fail with a connection error. ↓

fix Ensure Docker is installed and running, or set the environment variable `PYTEST_DATABASES_DOCKER_CMD` to your container runtime (e.g., `podman`).

breaking In v0.16.0, MongoDB support was added. The fixture name `mongodb_fixture` may conflict with other packages. Import using the full path if needed. ↓

fix Import as `from pytest_databases import mongodb_fixture` and avoid naming collisions by using aliasing.

gotcha Some fixtures (Oracle) require specific Docker images that may not be available on all architectures. In particular, Oracle 18c XE does not support ARM (Apple Silicon). ↓

fix Use a different database or emulate x86_64 with Rosetta 2. Alternatively, fall back to a cloud-hosted Oracle instance.

Imports

postgresql_fixture

wrong

from pytest_databases.fixtures import postgresql_fixture

correct

from pytest_databases import postgresql_fixture

Fixtures are exposed at the package level, not in a submodule.

redis_fixture

wrong

from pytest_databases.redis import redis_fixture

correct

from pytest_databases import redis_fixture

No separate redis module; import directly.

mysql_fixture

wrong

import pytest_databases.mysql_fixture

correct

from pytest_databases import mysql_fixture

Use a direct import, not module-level.

mongodb_fixture

wrong

from pytest_databases.mongo import mongodb_fixture

correct

from pytest_databases import mongodb_fixture

MongoDB fixture is at top-level since v0.16.0.

valkey_fixture

wrong

from pytest_databases.valkey import valkey_fixture

correct

from pytest_databases import valkey_fixture

Valkey was added in v0.13.0; import from package root.

Quickstart

Minimal test using the PostgreSQL fixture. The fixture automatically starts a container and yields the connection URL. No configuration needed if Docker is available.

import pytest
from pytest_databases import postgresql_fixture

# Use the fixture directly
pytest_plugins = ['pytest_databases']

def test_database(postgresql_fixture):
    # postgresql_fixture yields a connection URL string
    db_url = postgresql_fixture
    assert 'postgresql://' in db_url