pytest_pg 0.0.27

A tiny plugin for pytest which runs PostgreSQL in Docker

pytest-pg

A pytest plugin that provides session-scoped fixtures for running PostgreSQL inside Docker containers. It automatically spins up a container, waits for PostgreSQL to become ready, exposes connection details (host, port, user, password, database) via a PG dataclass, and tears the container down after the test session. Pre-built fixtures are available for PostgreSQL versions 11 through 18 as well as latest.

Readiness checks work with any of the common drivers — asyncpg, psycopg2, or psycopg3.

To speed up tests, pytest-pg does the following tweaks:

1. fsync=off
2. full_page_writes=off
3. synchronous_commit=off
4. jit=off
5. bgwriter_lru_maxpages=0
6. data directory is mounted to a tmpfs

How to use?

You can use the following fixtures:

• pg – the latest PostgreSQL image available
• pg_11 – PostgreSQL 11
• pg_12 – PostgreSQL 12
• pg_13 – PostgreSQL 13
• pg_14 – PostgreSQL 14
• pg_15 – PostgreSQL 15
• pg_16 – PostgreSQL 16
• pg_17 – PostgreSQL 17
• pg_18 – PostgreSQL 18

import asyncpg


async def test_asyncpg_query(pg):
    conn = await asyncpg.connect(
        user=pg.user,
        password=pg.password,
        database=pg.database,
        host=pg.host,
        port=pg.port,
    )

    await conn.execute("CREATE TABLE test_table (id serial PRIMARY KEY, value text);")
    await conn.execute("INSERT INTO test_table (value) VALUES ($1)", "hello")
    row = await conn.fetchrow("SELECT value FROM test_table WHERE id = $1", 1)

    assert row["value"] == "hello"

    await conn.close()

Also run_pg context manager is available, you can use it to create your own fixture, using docker image you need:

import os

import pytest
import pytest_pg


@pytest.fixture(scope='session', autouse=True)
def postgres_env_vars() -> Generator[None]:
    docker_image = 'postgres:18'
    with pytest_pg.run_pg(docker_image) as pg:
        os.environ['POSTGRES_USER'] = pg.user
        os.environ['POSTGRES_PASSWORD'] = pg.password
        os.environ['POSTGRES_HOST'] = pg.host
        os.environ['POSTGRES_PORT'] = str(pg.port)
        os.environ['POSTGRES_DBNAME'] = pg.database
        yield


# or like so:
@pytest.fixture(scope='session', autouse=True)
def postgres_env_vars(pg_18: pytest_pg.PG) -> Generator[None]:
    os.environ['POSTGRES_USER'] = pg_18.user
    os.environ['POSTGRES_PASSWORD'] = pg_18.password
    os.environ['POSTGRES_HOST'] = pg_18.host
    os.environ['POSTGRES_PORT'] = str(pg_18.port)
    os.environ['POSTGRES_DBNAME'] = pg_18.database
    yield

v0.0.27 (2026-05-01)

• Resolve DOCKER_HOST from docker context

v0.0.26 (2026-02-23)

• Time calculation fix
• Add pg_18 fixture
• Updated README, dropped python 3.9 support, added python 3.14 support

v0.0.25 (2025-05-18)

• Add pg_17 fixture

v0.0.24 (2025-05-11)

• Downgrade pytest

v0.0.23 (2025-04-11)

• Do not pull if we have an image locally

v0.0.22 (2025-04-03)

• Override docker host with env variable

v0.0.17 (2024-04-03)

• Override docker host with env variable

v0.0.15 (2023-05-04)

• Pin version of urllib3 (see for more details)
• Add pg_15 fixture

v0.0.14 (2022-09-19)

• Disable jit by default
• Set bgwriter_lru_maxpages

v0.0.12 (2022-01-18)

• Ditch logging because it seems to be useless

v0.0.11 (2022-01-09)

• Move volume to tmpfs

v0.0.10 (2022-01-08)

• Volumes used to remain after running test consuming disk space

v0.0.9 (2021-12-28)

• Disable fsync, full_page_writes, synchronous_commit to speedup the tests

v0.0.8 (2021-12-26)

• Add typing marker, mypy. Run tests in CI

v0.0.7 (2021-12-25)

• Fix is_ready based on psycopg2

v0.0.6 (2021-12-25)

• Add all recent major versions of PG

v0.0.4 (2021-12-10)

• Fix is_postgres_ready usage

v0.0.3 (2021-12-10)

• Fix uuid generation

v0.0.2 (2021-12-10)

• Follow pytest guide for plugins

v0.0.1 (2021-12-10)

• A first version