testgres

library1.14.2pypypi✓ verified 85d ago

testgres is a testing utility for PostgreSQL and its extensions, providing a simple API to manage temporary PostgreSQL instances, create databases, execute queries, and test replication. Current version 1.13.7, PyPI release with monthly cadence.

testing database

pip install testgres

github ↗package ↗

INSTALL

IMPORT

SIG · TESTGRES

testgres

testingpythonv1.14.2

Install

2.5s avg

Import

381ms

Disk

21MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.14.2 · 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.390s · 22.4MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.5s · import 0.372s · 23MB

21MB installed

● package 21MB

Code

Verified usage

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

testgres

✓ import testgres

Direct import of the module; no submodule import needed.

Quickstart demonstrating starting a temporary PostgreSQL node, initializing, starting, creating a database, and executing a query.

import testgres def test_postgres(): # Start a temporary PostgreSQL instance with testgres.get_new_node('test_node') as node: node.init() node.start() # Create a database and execute a query db = node.execute('CREATE DATABASE testdb') result = node.execute('SELECT 1') print(result) # Node is automatically stopped and cleaned up

Debug

Known issues

gotchatestgres.get_new_node() requires a node name that is unique per test session. Reusing names across tests may cause conflicts.

fix

Use unique names (e.g., with test name or random suffix) for each node.

affects: all

gotchaThe temporary PostgreSQL instance uses a port assigned by the OS. If multiple tests run concurrently, port collisions can occur. Use the 'port' parameter to specify a range or fixed port.

fix

Specify port range via `port=50432` or use `testgres.get_new_node('node', port=50432)`.

affects: all

deprecatedThe `execute()` method returns a list of tuples by default; in older versions it returned a string. If you rely on string output, update your code.

fix

Use `node.execute('query', returns='text')` to get string output, or adapt to list-of-tuples.

affects: < 1.13.0

gotchatestgres nodes do not automatically clean up the data directory if the context manager exits due to an exception. Use explicit cleanup or catch exceptions.

fix

Wrap in try/finally or use `with` context manager which handles cleanup on normal exit, but on exception you may need manual `node.stop()` and `node.cleanup()`.

affects: all

Errors

Common errors & fixes

ImportError: No module named 'testgres'

testgres is not installed or the virtual environment does not include it.

fix

Run `pip install testgres` and ensure the correct virtual environment is activated.

psycopg2.OperationalError: could not connect to server: Connection refused

The PostgreSQL node may not have started fully before attempting a connection.

fix

Ensure you call `node.start()` and wait for readiness, e.g., `node.wait_for_ready()`.

FileNotFoundError: [Errno 2] No such file or directory: 'initdb'

PostgreSQL binaries (initdb, pg_ctl) are not in the system PATH.

fix

Install PostgreSQL server and ensure its bin directory is in PATH, or set `pg_bindir` parameter to the PostgreSQL bin directory.

Upgrade

Version history

1.14.2latest on PyPI · released Jun 19, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

26 hits · last 30 days

node