# pytest-postgresql > Postgresql fixtures and fixture factories for Pytest. - **URL**: https://www.freshcrate.ai/projects/pytest-postgresql - **Author**: pypi - **Category**: Databases - **Latest version**: `main@2026-06-01` (2026-06-01) - **License**: Unknown - **Source**: https://github.com/dbfixtures/pytest-postgresql/issues - **Homepage**: https://pypi.org/project/pytest-postgresql/ - **Language**: Python - **GitHub**: 519 stars, 53 forks - **Registry**: pypi (`pytest-postgresql`) - **Tags**: `fixture`, `postgresql`, `pypi`, `pytest`, `tests` ## Description .. image:: https://raw.githubusercontent.com/dbfixtures/pytest-postgresql/main/logo.png :width: 100px :height: 100px pytest-postgresql ================= .. image:: https://img.shields.io/pypi/v/pytest-postgresql.svg :target: https://pypi.python.org/pypi/pytest-postgresql/ :alt: Latest PyPI version .. image:: https://img.shields.io/pypi/wheel/pytest-postgresql.svg :target: https://pypi.python.org/pypi/pytest-postgresql/ :alt: Wheel Status .. image:: https://img.shields.io/pypi/pyversions/pytest-postgresql.svg :target: https://pypi.python.org/pypi/pytest-postgresql/ :alt: Supported Python Versions .. image:: https://img.shields.io/pypi/l/pytest-postgresql.svg :target: https://pypi.python.org/pypi/pytest-postgresql/ :alt: License What is this? ============= This 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 the client connections. Quick Start =========== 1. **Install the plugin:** .. code-block:: sh pip install pytest-postgresql You will also need to install ``psycopg`` (version 3). See `its installation instructions `_. .. note:: While this plugin requires ``psycopg`` 3 to manage the database, your application code can still use ``psycopg`` 2. 2. **Run a test:** Simply include the ``postgresql`` fixture in your test. It provides a connected ``psycopg.Connection`` object. .. code-block:: python def test_example(postgresql): """Check main postgresql fixture.""" with postgresql.cursor() as cur: cur.execute("CREATE TABLE test (id serial PRIMARY KEY, num integer, data varchar);") postgresql.commit() How to use ========== .. warning:: Tested on PostgreSQL versions >= 14. See tests for more details. How does it work ---------------- .. image:: https://raw.githubusercontent.com/dbfixtures/pytest-postgresql/main/docs/images/architecture.svg :alt: Project Architecture Diagram :align: center The plugin provides two main types of fixtures: **1. Client Fixtures** These provide a connection to a database for your tests. * **postgresql** - A function-scoped fixture. It returns a connected ``psycopg.Connection``. After each test, it terminates leftover connections and drops the test database to ensure isolation. **2. Process Fixtures** These manage the PostgreSQL server lifecycle. * **postgresql_proc** - A session-scoped fixture that starts a PostgreSQL instance on its first use and stops it when all tests are finished. * **postgresql_noproc** - A fixture for connecting to an already running PostgreSQL instance (e.g., in Docker or CI). Customizing Fixtures -------------------- You can create additional fixtures using factories: .. code-block:: python from pytest_postgresql import factories # Create a custom process fixture postgresql_my_proc = factories.postgresql_proc( port=None, unixsocketdir='/var/run') # Create a client fixture that uses the custom process postgresql_my = factories.postgresql('postgresql_my_proc') .. note:: Each process fixture can be configured independently through factory arguments. Pre-populating the database for tests ------------------------------------- If you want the database to be automatically pre-populated with your schema and data, there are two levels you can achieve it: #. **Per test:** In a client fixture, by using an intermediary fixture. #. **Per session:** In a process fixture. The process fixture accepts a ``load`` parameter, which supports: * **SQL file paths:** Loads and executes the SQL files. * **Loading functions:** A callable or an import string (e.g., ``"path.to.module:function"``). These functions receive **host**, **port**, **user**, **dbname**, and **password** and must perform the connection themselves (or use an ORM). The process fixture pre-populates the database once per session into a **template database**. The client fixture then clones this template for each test, which significantly **speeds up your tests**. .. code-block:: python from pathlib import Path postgresql_my_proc = factories.postgresql_proc( load=[ Path("schemafile.sql"), "import.path.to.function", load_this_callable ] ) Defining pre-population on the command line: .. code-block:: sh pytest --postgresql-populate-template=path/to/file.sql --postgresql-populate-template=path.to.function Connecting to an existing PostgreSQL database ---------------------------------------------- To connect to an external server (e.g., running in Docker), use the ``postgresql_noproc`` fixture. .. code-block:: python postgresql_external = factories.postgresql('postgresql_noproc') By default, it connects to ``127.0.0.1:5432``. Chaining fixtures ## Recent releases | Version | Date | Urgency | Changes | | --- | --- | --- | --- | | `main@2026-06-01` | 2026-06-01 | High | Latest activity on main branch | | `8.0.0` | 2026-04-21 | Low | Imported from PyPI (8.0.0) | | `v8.0.0` | 2026-01-23 | Low | Tag v8.0.0 | | `v7.0.2` | 2025-05-17 | Low | Tag v7.0.2 | | `v7.0.1` | 2025-03-19 | Low | Tag v7.0.1 | | `v7.0.0` | 2025-02-23 | Low | Tag v7.0.0 | | `v6.1.1` | 2024-09-05 | Low | Tag v6.1.1 | | `v6.1.0` | 2024-09-04 | Low | Tag v6.1.0 | | `v6.0.1` | 2024-08-14 | Low | Tag v6.0.1 | | `v6.0.0` | 2024-03-11 | Low | Tag v6.0.0 | ## Citation - HTML: https://www.freshcrate.ai/projects/pytest-postgresql - Markdown: https://www.freshcrate.ai/projects/pytest-postgresql.md - Dependencies JSON: https://www.freshcrate.ai/api/projects/pytest-postgresql/deps _Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._