项目作者: postgrespro

项目描述 :
Testing framework for PostgreSQL and its extensions
高级语言: Python
项目地址: git://github.com/postgrespro/testgres.git
创建时间: 2016-08-12T18:36:30Z
项目社区:https://github.com/postgrespro/testgres

开源协议:Other

下载


Build Status
codecov
PyPI version

Documentation

testgres

PostgreSQL testing utility. Python 3.8+ is supported.

Installation

To install testgres, run:

  1. 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.

Example:

  1. export PG_BIN=$HOME/pg_10/bin
  2. python my_tests.py

Examples

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

  1. # create a node with random name, port, etc
  2. with testgres.get_new_node() as node:
  3. # run inidb
  4. node.init()
  5. # start PostgreSQL
  6. node.start()
  7. # execute a query in a default DB
  8. print(node.execute('select 1'))
  9. # ... node stops and its files are about to be removed

There are four API methods for running 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 occurs 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():

  1. with node.connect() as con:
  2. con.begin('serializable')
  3. print(con.execute('select %s', 1))
  4. con.rollback()

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:

  1. import logging
  2. # write everything to /tmp/testgres.log
  3. logging.basicConfig(filename='/tmp/testgres.log')
  4. # enable logging, and create two different nodes
  5. testgres.configure_testgres(use_python_logging=True)
  6. node1 = testgres.get_new_node().init().start()
  7. node2 = testgres.get_new_node().init().start()
  8. # execute a few queries
  9. node1.execute('select 1')
  10. node2.execute('select 2')
  11. # disable logging
  12. testgres.configure_testgres(use_python_logging=False)

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

Backup & replication

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

  1. with testgres.get_new_node('master') as master:
  2. master.init().start()
  3. # create a backup
  4. with master.backup() as backup:
  5. # create and start a new replica
  6. replica = backup.spawn_replica('replica').start()
  7. # catch up with master node
  8. replica.catchup()
  9. # execute a dummy query
  10. print(replica.execute('postgres', 'select 1'))

Benchmarks

testgres is also capable of running benchmarks using pgbench:

  1. with testgres.get_new_node('master') as master:
  2. # start a new node
  3. master.init().start()
  4. # initialize default DB and run bench for 10 seconds
  5. res = master.pgbench_init(scale=2).pgbench_run(time=10)
  6. print(res)

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:

  1. ext_conf = "shared_preload_libraries = 'postgres_fdw'"
  2. # initialize a new node
  3. with testgres.get_new_node().init() as master:
  4. # ... do something ...
  5. # reset main config file
  6. master.default_conf(fsync=True,
  7. allow_streaming=True)
  8. # add a new config line
  9. 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().

Remote mode

Testgres supports the creation of PostgreSQL nodes on a remote host. This is useful when you want to run distributed tests involving multiple nodes spread across different machines.

To use this feature, you need to use the RemoteOperations class. This feature is only supported with Linux.
Here is an example of how you might set this up:

  1. from testgres import ConnectionParams, RemoteOperations, TestgresConfig, get_remote_node
  2. # Set up connection params
  3. conn_params = ConnectionParams(
  4. host='your_host', # replace with your host
  5. username='user_name', # replace with your username
  6. ssh_key='path_to_ssh_key' # replace with your SSH key path
  7. )
  8. os_ops = RemoteOperations(conn_params)
  9. # Add remote testgres config before test
  10. TestgresConfig.set_os_ops(os_ops=os_ops)
  11. # Proceed with your test
  12. def test_basic_query(self):
  13. with get_remote_node(conn_params=conn_params) as node:
  14. node.init().start()
  15. res = node.execute('SELECT 1')
  16. self.assertEqual(res, [(1,)])

Authors

Ildar Musin
Dmitry Ivanov
Ildus Kurbangaliev
Yury Zhuravlev