pytest-postgresql

What it is and what it does

pytest-postgresql is a pytest plugin that automates PostgreSQL database setup and teardown for tests. It provides fixtures that either start a PostgreSQL instance on demand (session-scoped) or connect to an existing one, and manage test database creation, isolation, and cleanup. The plugin uses psycopg 3 to handle connections and database operations, returning a connected psycopg.Connection object to your test functions.

The plugin supports pre-populating test databases via SQL files or Python functions, with a template-cloning strategy that speeds up test runs by building a template database once per session and cloning it for each test. You can customize fixtures through factory functions, configure connection parameters via command-line options or pytest.ini, and chain multiple fixtures to layer data pre-population. It handles both managed PostgreSQL processes and connections to external instances (e.g., Docker containers).

Use it for:

• Unit testing code that queries or modifies PostgreSQL tables without needing manual database setup or teardown.
• Integration testing with pre-populated schemas and seed data, using template cloning to avoid repeated setup overhead.
• Testing against an external PostgreSQL instance in CI/CD by using the noproc fixture to connect to a running server.
• Layering test data through chained fixtures, where each fixture adds its own schema or data on top of a previous layer.
• Testing SQLAlchemy ORM code by creating a session fixture that wraps the postgresql connection.
• Ensuring test isolation by automatically dropping test databases and terminating leftover connections after each test.

Worth the install?

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

A pytest plugin that provides fixtures to manage PostgreSQL database instances and connections for testing, handling both process lifecycle and client connection setup.

Yes. The plugin is actively maintained, has no known vulnerabilities, and solves a common testing problem with low install friction. Use it if you need to test code that interacts with PostgreSQL and want automated database lifecycle management. The copyleft license does not restrict your application code, only derivative works of the plugin itself.

Install

pytest-postgresql on PyPI

pip install pytest-postgresql

uv add pytest-postgresql

poetry add pytest-postgresql

Installing pytest-postgresql

Before you install

Low install friction with a pure-Python wheel. Active maintenance (last commit 2026-08-14) and stable production status. Requires psycopg 3 for the plugin itself, though application code can use psycopg 2.

License in practice

Licensed under LGPLv3+, a copyleft license. Derivative works and modifications must be distributed under compatible terms; using the plugin in a project does not impose copyleft on your own code.

Quickstart

pip install pytest-postgresql psycopg

import pytest
from pytest_postgresql import factories

postgresql_proc = factories.postgresql_proc()
postgresql = factories.postgresql('postgresql_proc')

def test_example(postgresql):
    with postgresql.cursor() as cur:
        cur.execute("CREATE TABLE test (id serial PRIMARY KEY);")
        postgresql.commit()

Requires PostgreSQL >= 14 to be installed on the system; the plugin manages the process but does not bundle PostgreSQL itself.

Verify before relying

• Whether the plugin works with PostgreSQL versions between 14 and the current release date (2026-08-14).
• Performance characteristics when chaining multiple fixture layers or pre-populating large schemas.

Package facts

Evidence: pytest_postgresql-8.1.0-py3-none-any.whl

Keywords: tests, pytest, fixture, postgresql

Tags

More Python Modules packages