postgrespro / testgres Goto Github PK

View Code? Open in Web Editor NEW

139.0 32.0 32.0 848 KB

Testing framework for PostgreSQL and its extensions

Home Page: https://postgrespro.github.io/testgres

License: Other

Python 99.20% Shell 0.80%

postgresql postgres testing replication testgres pathman

testgres's Introduction

Documentation

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.

Example:

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

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
    node.init()

    # start PostgreSQL
    node.start()

    # 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:
    con.begin('serializable')
    print(con.execute('select %s', 1))
    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:

import logging

# write everything to /tmp/testgres.log
logging.basicConfig(filename='/tmp/testgres.log')

# enable logging, and create two different nodes
testgres.configure_testgres(use_python_logging=True)
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
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:

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

    # 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
        replica.catchup()

        # 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
    master.init().start()

    # initialize default DB and run bench for 10 seconds
    res = master.pgbench_init(scale=2).pgbench_run(time=10)
    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:

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
    master.default_conf(fsync=True,
                        allow_streaming=True)

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

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:

from testgres import ConnectionParams, RemoteOperations, TestgresConfig, get_remote_node

# Set up connection params
conn_params = ConnectionParams(
    host='your_host',  # replace with your host
    username='user_name',  # replace with your username
    ssh_key='path_to_ssh_key'  # replace with your SSH key path
)
os_ops = RemoteOperations(conn_params)

# Add remote testgres config before test
TestgresConfig.set_os_ops(os_ops=os_ops)

# Proceed with your test
def test_basic_query(self):
    with get_remote_node(conn_params=conn_params) as node:
        node.init().start()
        res = node.execute('SELECT 1')
        self.assertEqual(res, [(1,)])

Authors

Ildar Musin
Dmitry Ivanov
Ildus Kurbangaliev
Yury Zhuravlev

testgres's People

Contributors

Stargazers

Watchers

testgres's Issues

Version detection fails on Ubuntu (Mint) installation

On Linux Mint (an Ubuntu derivative), the version string produced by postgres isn't parsed correctly by get_pg_version() in utils.py:

$ /usr/lib/postgresql/15/bin/postgres --version
postgres (PostgreSQL) 15.5 (Ubuntu 15.5-1.pgdg22.04+1)

$ python ./tests/test_simple.py 
Traceback (most recent call last):
  File "testgres/env/lib/python3.10/site-packages/testgres/utils.py", line 31, in __init__
    super().__init__(version)
  File "testgres/env/lib/python3.10/site-packages/packaging/version.py", line 200, in __init__
    raise InvalidVersion(f"Invalid version: '{version}'")
packaging.version.InvalidVersion: Invalid version: '15.5-1.pgdg22.04+1)'

There appears to be a fairly simple fix in get_pg_version(), line 185:

    # Remove "(Homebrew)" and "(Ubuntu <version>)" if present
    raw_ver = raw_ver.replace('(Homebrew)', '').strip()
    raw_ver = re.sub('\(Ubuntu[^)]*\)', '', raw_ver).strip()

Node-depend binaries and pg_upgrade support

For example:
node_old = get_new_node(prefix='/path/to/old/pg/prefix')
node_old.init()
node_new=get_new_node(prefix='/path/to/new/pg/prefix')
node_new.init()
node_new.upgade_from(old=node_old)

safe_psql() method returns byte string

Previously it was returning text, so now you have to manually decode it.

TypeError: Can't convert 'bytes' object to str implicitly

I get this error if safe_psql() fails:

----------------------------------------------------------------------
Traceback (most recent call last):
  File "/home/artur/source/pg/rum/tests/pglist_tests.py", line 94, in test_order_by
    "  FROM pglist "
  File "/home/artur/source/pg/rum/tests/pglist_tests.py", line 83, in test_order_by
    try:
  File "/home/artur/source/pg/rum/tests/rum/lib/python3.5/site-packages/testgres/testgres.py", line 379, in safe_psql
    raise ClusterException("psql failed:\n" + err)
TypeError: Can't convert 'bytes' object to str implicitly

----------------------------------------------------------------------

Question: comparison to

Thanks for creating and publishing testgres as Free Software.

What are the differences to https://github.com/tk0miya/testing.postgresql especially when would one use the one or the other?

What license is testgres under?
(Assuming that publication on https://pypi.python.org/pypi/testgres/0.2.0 means that it shall be Free Software.)

Testing a DB installed on remote host

Hi,

This is not an issue but just a quick question about the tool. Can I use testgres to test a DB cluster installed on remote host ?

Thanks,
Kapil.

Error 'ProgrammingError: no results to fetch' under 'NodeConnection.execute' method call that executes utility query that doesn't return any result

This fragment:

with node.connect() as con:
      con.execute('create table range_partitioned as select generate_series(1, 1e4) i')

fails with error:

Traceback (most recent call last):
  ...
  File ".../lib/python2.7/site-packages/testgres/testgres.py", line 132, in execute
    return self.cursor.fetchall()
ProgrammingError: no results to fetch

Testgres unavailable on conda-forge

Dear Maintainers,

Thank you very much for this project.

Could you please make the package also available on conda-forge?

PG13 support

TODO:

wal_keep_segments parameter is obsolete

PostgresNode.safe_psql(filename) does not detect syntax errors

It took me some time to discover that a syntax error was being not being reported by node.safe_psql(filename='some.sql'). I tracked it down to behavior in psql. It seems worth raising, though I'm not certain it is something that testgres is necessarily responsible for handling.

$ psql --version
psql (PostgreSQL) 9.6.4

and/or

$ psql --version
psql (PostgreSQL) 10.4

psql reports errors differently depending on how input is passed:

$ psql -h 127.0.0.1 -U cbandy -X -A -t -q -c 'whoops' -p 34751 postgres ; echo $?
ERROR:  syntax error at or near "whoops"
LINE 1: whoops
        ^
1

N.B. exit code is zero here:

$ psql -h 127.0.0.1 -U cbandy -X -A -t -q -f <( echo 'whoops' ) -p 34751 postgres ; echo $?
psql:/dev/fd/63:1: ERROR:  syntax error at or near "whoops"
LINE 1: whoops
        ^
0

$ psql -h 127.0.0.1 -U cbandy -X -A -t -q -v ON_ERROR_STOP=1 -f <( echo 'whoops' ) -p 34751 
postgres ; echo $?
psql:/dev/fd/63:1: ERROR:  syntax error at or near "whoops"
LINE 1: whoops
        ^
3

Directory cached_data_dir did not cleanup after test finished

cleanup backward compatibility broken in 1.8.3

In 1.8.2 cleanup() method always removed data directory, 1.8.3 removes data directory only in case of custom base path:

-        # choose directory to be removed
-        if testgres_config.node_cleanup_full:
-            rm_dir = self.base_dir    # everything
-        else:
-            rm_dir = self.data_dir    # just data, save logs
+        # only remove if base directory was temporary
+        if not self._custom_base_dir:
+            # choose directory to be removed
+            if testgres_config.node_cleanup_full:
+                rm_dir = self.base_dir    # everything
+            else:
+                rm_dir = self.data_dir    # just data, save logs
 
-        rmtree(rm_dir, ignore_errors=True)
+            rmtree(rm_dir, ignore_errors=True)

get_pg_version fails for Postgres installed with homebrew

The output of postgres --version is postgres (PostgreSQL) 14.9 (Homebrew) when Postgres has been installed with Homebrew. As a result, function get_pg_version in testgres/utils.py raises and prevents running tests.

'TypeError: decode() argument 'encoding' when node.init()

Hi,
When I try to create a node on port 5435 and execute init(), I get an error 'TypeError: decode() argument 'encoding' must be str, not None'.
Maybe I'm missing some parameter? How can I troubleshoot this error?

python version: 3.11.4
testgres version: 1.9.2

Here is my code.

import testgres
with testgres.get_new_node('test', port = 5435) as node:
    print(node)

    node.init()
    node.start()

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

    node.stop()
    node.clean()

Error message:

[update]
I can excute init() with testgres version 1.8.9.