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 on it.

Install

pytest-postgresql on PyPI

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.

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

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()

Package facts

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

Tags

More Python Modules packages

See also pytest-mysql · pytest-redis · pytest-rabbitmq · pytest-pgsql · py-pglite · testgres · fixtures · pytest-shutil · pytest-xprocess · pytest-docker-tools