Skip to main content

Testing utility for PostgreSQL and its extensions

Project description

[![Build Status](](
[![PyPI version](](


# testgres

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

## Installation

To install `testgres`, run:

pip install testgres

We encourage you to use `virtualenv` for your testing environment.

## Usage

### 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

### Examples

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

### Logging

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

### 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'))

### Benchmarks

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

## Authors

[Ildar Musin]( <i.musin(at)> Postgres Professional Ltd., Russia
[Dmitry Ivanov]( <d.ivanov(at)> Postgres Professional Ltd., Russia
[Ildus Kurbangaliev]( <i.kurbangaliev(at)> Postgres Professional Ltd., Russia
[Yury Zhuravlev]( <stalkerg(at)>

Project details

Download files

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

Filename, size & hash SHA256 hash help File type Python version Upload date
testgres-1.8.2.tar.gz (33.9 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page