testgres package

testgres.api

Testing framework for PostgreSQL and its extensions

This module was created under influence of Postgres TAP test feature (PostgresNode.pm module). It can manage Postgres clusters: initialize, edit configuration files, start/stop cluster, execute queries. The typical flow may look like:

>>> with get_new_node() as node:
...     node.init().start()
...     result = node.safe_psql('postgres', 'select 1')
...     print(result.decode('utf-8').strip())
...     node.stop()
PostgresNode(name='...', port=..., base_dir='...')
1
PostgresNode(name='...', port=..., base_dir='...')
Or:
>>> with get_new_node() as master:
...     master.init().start()
...     with master.backup() as backup:
...         with backup.spawn_replica() as replica:
...             replica = replica.start()
...             master.execute('postgres', 'create table test (val int4)')
...             master.execute('postgres', 'insert into test values (0), (1), (2)')
...             replica.catchup()  # wait until changes are visible
...             print(replica.execute('postgres', 'select count(*) from test'))
PostgresNode(name='...', port=..., base_dir='...')
[(3,)]
testgres.api.get_new_node(name=None, base_dir=None, **kwargs)

Simply a wrapper around PostgresNode constructor. See PostgresNode.__init__() for details.

testgres.backup

class testgres.backup.NodeBackup(node, base_dir=None, username=None, xlog_method=<XLogMethod.fetch: 'fetch'>)

Bases: object

Smart object responsible for backups

cleanup()

Remove all files that belong to this backup. No-op if it’s been converted to a PostgresNode (destroy=True).

log_file
spawn_primary(name=None, destroy=True)

Create a primary node from a backup.

Parameters:
  • name – primary’s application name.
  • destroy – should we convert this backup into a node?
Returns:

New instance of PostgresNode.

spawn_replica(name=None, destroy=True, slot=None)

Create a replica of the original node from a backup.

Parameters:
  • name – replica’s application name.
  • slot – create a replication slot with the specified name.
  • destroy – should we convert this backup into a node?
Returns:

New instance of PostgresNode.

testgres.config

class testgres.config.GlobalConfig(**options)

Bases: object

Global configuration object which allows user to override default settings.

copy()

Return a copy of this object.

items()

Return setting-value pairs.

keys()

Return a list of all available settings.

update(config)

Extract setting-value pairs from ‘config’ and assign those values to corresponding settings of this GlobalConfig object.

cache_initdb = True

shall we use cached initdb instance?

cache_pg_config = True

shall we cache pg_config results?

cached_initdb_dir

path to a temp directory for cached initdb.

cached_initdb_unique = False

shall we give new node a unique system id?

error_log_lines = 20

N of log lines to be shown in exceptions (0=inf).

node_cleanup_full = True

shall we remove EVERYTHING (including logs)?

node_cleanup_on_bad_exit = False

remove base_dir on __exit__() via exception.

node_cleanup_on_good_exit = True

remove base_dir on nominal __exit__().

temp_dir

path to temp dir containing nodes with default ‘base_dir’.

use_python_logging = False

enable python logging subsystem (see logger.py).

testgres.config.configure_testgres(**options)

Adjust current global options. Look at the GlobalConfig to learn about existing settings.

testgres.config.pop_config()

Set previous GlobalConfig options from stack.

testgres.config.push_config(**options)

Permanently set custom GlobalConfig options and put previous settings on top of the config stack.

testgres.config.scoped_config(**options)

Temporarily set custom GlobalConfig options for this context. Previous options are pushed to the config stack.

Example

>>> from .api import get_new_node
>>> with scoped_config(cache_initdb=False):
...     # create a new node with fresh initdb
...     with get_new_node().init().start() as node:
...         print(node.execute('select 1'))
[(1,)]

testgres.connection

class testgres.connection.NodeConnection(node, dbname=None, username=None, password=None, autocommit=False)

Bases: object

Transaction wrapper returned by Node

begin(isolation_level=<IsolationLevel.ReadCommitted: 'read committed'>)
close()
commit()
connection
cursor
execute(query, *args)
node
pid
rollback()

testgres.enums

class testgres.enums.DumpFormat

Bases: enum.Enum

Available dump formats

Custom = 'custom'
Directory = 'directory'
Plain = 'plain'
Tar = 'tar'
class testgres.enums.IsolationLevel

Bases: enum.Enum

Transaction isolation level for NodeConnection

ReadCommitted = 'read committed'
ReadUncommitted = 'read uncommitted'
RepeatableRead = 'repeatable read'
Serializable = 'serializable'
class testgres.enums.NodeStatus

Bases: enum.IntEnum

Status of a PostgresNode

Running = 0
Stopped = 1
Uninitialized = 2
class testgres.enums.ProcessType

Bases: enum.Enum

Types of processes

AutovacuumLauncher = 'autovacuum launcher'
BackgroundWriter = 'background writer'
Checkpointer = 'checkpointer'
LogicalReplicationLauncher = 'logical replication launcher'
Startup = 'startup'
StatsCollector = 'stats collector'
Unknown = 'unknown'
WalReceiver = 'wal receiver'
WalSender = 'wal sender'
WalWriter = 'wal writer'
class testgres.enums.XLogMethod

Bases: enum.Enum

Available WAL methods for NodeBackup

fetch = 'fetch'
none = 'none'
stream = 'stream'

testgres.exceptions

exception testgres.exceptions.BackupException

Bases: testgres.exceptions.TestgresException

exception testgres.exceptions.CatchUpException(message=None, query=None)

Bases: testgres.exceptions.QueryException

exception testgres.exceptions.ExecUtilException(message=None, command=None, exit_code=0, out=None)

Bases: