Skip to main content

Testing utility for PostgreSQL and its extensions

Project description

Build Status codecov PyPI version



PostgreSQL testing utility. Both Python 2.7 and 3.3+ are supported.


To install testgres, run:

pip install testgres

We encourage you to use virtualenv for your testing environment.



Note: by default testgres runs initdb, pg_ctl, psql provided by PATH.

There are several ways to specify a custom postgres installation:

  • export PG_CONFIG environment variable pointing to the pg_config executable;
  • export PG_BIN environment variable pointing to the directory with executable files.


export PG_BIN=$HOME/pg_10/bin


Here is an example of what you can do with testgres:

# create a node with random name, port, etc
with testgres.get_new_node() as node:

    # run inidb

    # start PostgreSQL

    # execute a query in a default DB
    print(node.execute('select 1'))

# ... node stops and its files are about to be removed

There are four API methods for runnig queries:

Command Description
node.psql(query, ...) Runs query via psql command and returns tuple (error code, stdout, stderr).
node.safe_psql(query, ...) Same as psql() except that it returns only stdout. If an error occures during the execution, an exception will be thrown.
node.execute(query, ...) Connects to PostgreSQL using psycopg2 or pg8000 (depends on which one is installed in your system) and returns two-dimensional array with data.
node.connect(dbname, ...) Returns connection wrapper (NodeConnection) capable of running several queries within a single transaction.

The last one is the most powerful: you can use begin(isolation_level), commit() and rollback():

with node.connect() as con:
    print(con.execute('select %s', 1))


By default, cleanup() removes all temporary files (DB files, logs etc) that were created by testgres' API methods. If you'd like to keep logs, execute configure_testgres(node_cleanup_full=False) before running any tests.

Note: context managers (aka with) call stop() and cleanup() automatically.

testgres supports python logging, which means that you can aggregate logs from several nodes into one file:

import logging

# write everything to /tmp/testgres.log

# enable logging, and create two different nodes
node1 = testgres.get_new_node().init().start()
node2 = testgres.get_new_node().init().start()

# execute a few queries
node1.execute('select 1')
node2.execute('select 2')

# disable logging

Look at tests/ file for a complete example of the logging configuration.

Backup & replication

It's quite easy to create a backup and start a new replica:

with testgres.get_new_node('master') as master:

    # create a backup
    with master.backup() as backup:

        # create and start a new replica
        replica = backup.spawn_replica('replica').start()

        # catch up with master node

        # execute a dummy query
        print(replica.execute('postgres', 'select 1'))


testgres is also capable of running benchmarks using pgbench:

with testgres.get_new_node('master') as master:
    # start a new node

    # initialize default DB and run bench for 10 seconds
    res = master.pgbench_init(scale=2).pgbench_run(time=10)

Custom configuration

It's often useful to extend default configuration provided by testgres.

testgres has default_conf() function that helps control some basic options. The append_conf() function can be used to add custom lines to configuration lines:

ext_conf = "shared_preload_libraries = 'postgres_fdw'"

# initialize a new node
with testgres.get_new_node().init() as master:

    # ... do something ...
    # reset main config file

    # add a new config line
    master.append_conf('postgresql.conf', ext_conf)

Note that default_conf() is called by init() function; both of them overwrite the configuration file, which means that they should be called before append_conf().


Ildar Musin
Dmitry Ivanov
Ildus Kurbangaliev
Yury Zhuravlev

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for testgres, version 1.8.4
Filename, size File type Python version Upload date Hashes
Filename, size testgres-1.8.4.tar.gz (32.1 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page