*.egg-info/

.eggs/

dist/

build/

docs/build/

env/

venv/

build/

ENV PYTHON=python${PYTHON_VERSION}

RUN if [ "${PYTHON_VERSION}" = "2" ] ; then \

apk add --no-cache curl python2 py-virtualenv py-pip; \

apk add --no-cache curl python2 python2-dev build-base musl-dev \

linux-headers py-virtualenv py-pip; \

fi

RUN if [ "${PYTHON_VERSION}" = "3" ] ; then \

apk add --no-cache curl python3 py-virtualenv; \

apk add --no-cache curl python3 python3-dev build-base musl-dev \

linux-headers py-virtualenv; \

fi

ENV LANG=C.UTF-8

testgres is released under the PostgreSQL License, a liberal Open Source license, similar to the BSD or MIT licenses.

Copyright (c) 2016-2017, Postgres Professional

Copyright (c) 2016-2018, Postgres Professional

Permission to use, copy, modify, and distribute this software and its documentation for any purpose, without fee, and without a written agreement is hereby granted, provided that the above copyright notice and this paragraph and the following two paragraphs appear in all copies.

include LICENSE

include README.md

include setup.cfg

recursive-include testgres *.py

recursive-include tests *.py

global-exclude *.pyc

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.

testgres supports[python logging](https://docs.python.org/3.6/library/logging.html),

which means that you can aggregate logs from several nodes into one file:

import logging

logging.basicConfig(filename='/tmp/testgres.log')

node1= testgres.get_new_node(use_logging=True).init().start()

node2= testgres.get_new_node(use_logging=True).init().start()

node1.execute('postgres','select 1')

node2.execute('postgres','select 2')

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

with testgres.get_new_node('test')as node:

node.init()# run initdb

node.start()# start PostgreSQL

print(node.execute('postgres','select 1'))

node.stop()# stop PostgreSQL

Let's walk through the code. First, you create a new node using:

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

or

with testgres.get_new_node('master','/path/to/DB')as node:

with testgres.get_new_node()as node:

where`master` is a node's application name. Name matters if you're testing something like replication.

Function`get_new_node()` only creates directory structure in specified directory (or somewhere in '/tmp' if

we did not specify base directory) for cluster. After that, we have to initialize the PostgreSQL cluster:

node.init()

node.init()

node.start()

This function runs`initdb` command and adds some basic configuration to`postgresql.conf` and`pg_hba.conf` files.

Function`init()` accepts optional parameter`allows_streaming` which configures cluster for streaming replication (default is`False`).

Now we are ready to start:

print(node.execute('select 1'))

node.start()

Finally, our temporary cluster is able to process queries.There are fourways to run them:

There are fourAPI methods for runnig queries:

| Command| Description|

|----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|

|`node.psql(dbname, query)`| Runs query via`psql` command and returns tuple`(error code, stdout, stderr)`.|

|`node.safe_psql(dbname, query)`| Same as`psql()` except that it returns only`stdout`. If an error occures during the execution, an exception will be thrown.|

|`node.execute(dbname, 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,username)`| Returns connection wrapper (`NodeConnection`) capable of running several queries within a single transaction.|

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

con.rollback()

To stop the server, run:

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.

`testgres` supports[python logging](https://docs.python.org/3.6/library/logging.html),

which means that you can aggregate logs from several nodes into one file:

node.stop()

import logging

logging.basicConfig(filename='/tmp/testgres.log')

testgres.configure_testgres(enable_python_logging=True)

node1= testgres.get_new_node().init().start()

node2= testgres.get_new_node().init().start()

node1.execute('select 1')

node2.execute('select 2')

testgres.configure_testgres(enable_python_logging=False)

Look at`tests/test_simple.py` file for a complete example of the logging

configuration.

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

master.init().start()

with master.backup()as backup:

replica= backup.spawn_replica('replica').start()

`testgres` alsocan help you to makebenchmarks using`pgbench` from postgres installation:

`testgres`isalsocapable of runningbenchmarks using`pgbench`:

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

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'"

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

master.default_conf(fsync=True,

allow_streaming=True)

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](https://github.com/zilder) <i.musin(at)postgrespro.ru> Postgres Professional Ltd., Russia

[Dmitry Ivanov](https://github.com/funbringer) <d.ivanov(at)postgrespro.ru> Postgres Professional Ltd., Russia

[Ildus Kurbangaliev](https://github.com/ildus) <i.kurbangaliev(at)postgrespro.ru> Postgres Professional Ltd., Russia

[Yury Zhuravlev](https://github.com/stalkerg) <stalkerg(at)gmail.com>

[Ildar Musin](https://github.com/zilder) <i.musin(at)postgrespro.ru> Postgres Professional Ltd., Russia

[Dmitry Ivanov](https://github.com/funbringer) <d.ivanov(at)postgrespro.ru> Postgres Professional Ltd., Russia

[Ildus Kurbangaliev](https://github.com/ildus) <i.kurbangaliev(at)postgrespro.ru> Postgres Professional Ltd., Russia

[Yury Zhuravlev](https://github.com/stalkerg) <stalkerg(at)gmail.com>

SPHINXOPTS =

SPHINXBUILD = sphinx-build

SPHINXPROJ = testgres

SOURCEDIR = source

BUILDDIR = build

help:

@$(SPHINXBUILD) -Mhelp"$(SOURCEDIR)""$(BUILDDIR)"$(SPHINXOPTS)$(O)

.PHONY: help Makefile

%: Makefile

@$(SPHINXBUILD) -M$@"$(SOURCEDIR)""$(BUILDDIR)"$(SPHINXOPTS)$(O)

Make sure you have`Sphinx` and`sphinxcontrib-napoleon` packages installed:

Then just run

Documentation will be built in`build/html` directory. Other output formats are also available; run`make` without arguments to see the options.