Registry / testing / pytest-postgresql

pytest-postgresql

library8.1.0pypypi✓ verified 26d ago

pytest-postgresql is a pytest plugin that enables you to test code relying on a running PostgreSQL database. It provides fixtures for managing both the PostgreSQL process and client connections, automatically cleaning up temporary databases after tests. The current version is 8.0.0, and it is actively maintained.

testing database

pip install pytest-postgresql psycopg

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · PYTEST-POSTGRESQL

pytest-postgresql

testingpythonv8.1.0

Install

3.2s avg

Import

—

Disk

33MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v8.1.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 34.1MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.2s · import 0.000s · 35MB

33MB installed

● package 33MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

postgresql

✓ def test_something(postgresql):

The primary fixture providing a psycopg.Connection object.

postgresql_proc

✓ def test_something_with_proc(postgresql_proc, postgresql):

A session-scoped fixture managing the PostgreSQL server lifecycle.

factories

✓ from pytest_postgresql import factories

Used for creating custom PostgreSQL client and process fixtures.

Demonstrates a basic test using the `postgresql` fixture to interact with a temporary PostgreSQL database. The fixture provides a `psycopg.Connection` object, automatically handling database setup and teardown for isolation.

import pytest from psycopg import Connection def test_example(postgresql: Connection): """Check main postgresql fixture.""" with postgresql.cursor() as cur: cur.execute("CREATE TABLE test (id serial PRIMARY KEY, num integer, data varchar);") postgresql.commit() # Optional: Verify data insertion with postgresql.cursor() as cur: cur.execute("INSERT INTO test (num, data) VALUES (1, 'test_data');") postgresql.commit() with postgresql.cursor() as cur: cur.execute("SELECT num, data FROM test WHERE id = 1;") result = cur.fetchone() assert result == (1, 'test_data')

Debug

Known issues

breakingVersion 8.0.0 has dropped support for Python 3.9 (which reached End-of-Life) and now only supports PostgreSQL versions 14 and up.

fix

Ensure your test environment uses Python >= 3.10 and PostgreSQL >= 14.

affects: >=8.0.0

breakingThe minimum supported `pytest` version has been bumped to 8.2. Older `pytest` versions might exhibit flaky behavior with fixture chaining on Python 3.12-3.13 when used with `xdist`.

fix

Upgrade `pytest` to version 8.2 or newer: `pip install -U pytest`.

affects: >=8.0.0

breaking`psycopg` (version 3) is now a mandatory requirement. Previously, `psycopg2` was optional.

fix

Install `psycopg` alongside `pytest-postgresql`: `pip install pytest-postgresql psycopg`.

affects: >=8.0.0

gotchaUsing `COMMIT` statements within tests relying on the `transacted_postgresql_db` fixture can lead to non-deterministic bugs. This fixture assumes tests run within a single transaction and will reset the database, but explicit commits break this isolation.

fix

Avoid `COMMIT` in `transacted_postgresql_db` tests. If `COMMIT` is strictly necessary, use the `postgresql_db` fixture instead, which provides full isolation by dropping and recreating the database after each test, though this is slower.

affects: *

Upgrade

Version history

8.1.0latest on PyPI · released May 15, 2026

Audit

Dependencies

pytestrequiredCore testing framework that this plugin extends.

psycopgrequiredMandatory PostgreSQL adapter (version 3).

Agent activity

14 hits · last 30 days

node

Resources

githubhttps://github.com/dbfixtures/pytest-postgresql ↗

packagehttps://pypi.org/project/pytest-postgresql/ ↗

changeloghttps://github.com/dbfixtures/pytest-postgresql/blob/v8.1.0/CHANGES.rst ↗