Package: testgres
DocumentationtestgresPostgreSQL testing utility. Both Python 2.7 and 3.3+ are supported.InstallationTo installtestgres, run:pip install testgresWe encourage you to usevirtualenvfor your testing environment.UsageEnvironmentNote: by default testgres runsinitdb,pg_ctl,psqlprovided byPATH.There are several ways to specify a custom postgres installation:exportPG_CONFIGenvironment variable pointing to thepg_configexecutable;exportPG_BINenvironment variable pointing to the directory with executable files.Example:exportPG_BIN=$HOME/pg_10/bin
pythonmy_tests.pyExamplesHere is an example of what you can do withtestgres:# create a node with random name, port, etcwithtestgres.get_new_node()asnode:# run inidbnode.init()# start PostgreSQLnode.start()# execute a query in a default DBprint(node.execute('select 1'))# ... node stops and its files are about to be removedThere are four API methods for runnig queries:CommandDescriptionnode.psql(query, ...)Runs query viapsqlcommand and returns tuple(error code, stdout, stderr).node.safe_psql(query, ...)Same aspsql()except that it returns onlystdout. If an error occures during the execution, an exception will be thrown.node.execute(query, ...)Connects to PostgreSQL usingpsycopg2orpg8000(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 usebegin(isolation_level),commit()androllback():withnode.connect()ascon:con.begin('serializable')print(con.execute('select%s',1))con.rollback()LoggingBy default,cleanup()removes all temporary files (DB files, logs etc) that were created by testgres' API methods.
If you'd like to keep logs, executeconfigure_testgres(node_cleanup_full=False)before running any tests.Note: context managers (akawith) callstop()andcleanup()automatically.testgressupportspython logging,
which means that you can aggregate logs from several nodes into one file:importlogging# write everything to /tmp/testgres.loglogging.basicConfig(filename='/tmp/testgres.log')# enable logging, and create two different nodestestgres.configure_testgres(use_python_logging=True)node1=testgres.get_new_node().init().start()node2=testgres.get_new_node().init().start()# execute a few queriesnode1.execute('select 1')node2.execute('select 2')# disable loggingtestgres.configure_testgres(use_python_logging=False)Look attests/test_simple.pyfile for a complete example of the logging
configuration.Backup & replicationIt's quite easy to create a backup and start a new replica:withtestgres.get_new_node('master')asmaster:master.init().start()# create a backupwithmaster.backup()asbackup:# create and start a new replicareplica=backup.spawn_replica('replica').start()# catch up with master nodereplica.catchup()# execute a dummy queryprint(replica.execute('postgres','select 1'))Benchmarkstestgresis also capable of running benchmarks usingpgbench:withtestgres.get_new_node('master')asmaster:# start a new nodemaster.init().start()# initialize default DB and run bench for 10 secondsres=master.pgbench_init(scale=2).pgbench_run(time=10)print(res)Custom configurationIt's often useful to extend default configuration provided bytestgres.testgreshasdefault_conf()function that helps control some basic
options. Theappend_conf()function can be used to add custom
lines to configuration lines:ext_conf="shared_preload_libraries = 'postgres_fdw'"# initialize a new nodewithtestgres.get_new_node().init()asmaster:# ... do something ...# reset main config filemaster.default_conf(fsync=True,allow_streaming=True)# add a new config linemaster.append_conf('postgresql.conf',ext_conf)Note thatdefault_conf()is called byinit()function; both of them overwrite
the configuration file, which means that they should be called beforeappend_conf().Remote modeTestgres 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:fromtestgresimportConnectionParams,RemoteOperations,TestgresConfig,get_remote_node# Set up connection paramsconn_params=ConnectionParams(host='your_host',# replace with your hostusername='user_name',# replace with your usernamessh_key='path_to_ssh_key'# replace with your SSH key path)os_ops=RemoteOperations(conn_params)# Add remote testgres config before testTestgresConfig.set_os_ops(os_ops=os_ops)# Proceed with your testdeftest_basic_query(self):withget_remote_node(conn_params=conn_params)asnode:node.init().start()res=node.execute('SELECT 1')self.assertEqual(res,[(1,)])AuthorsIldar MusinDmitry IvanovIldus KurbangalievYury Zhuravlev