Timescale Logo

PostgreSQL Extensions: Database Testing With pgTAP

pgTAP is a unit testing framework for PostgreSQL. This extension is written in PL/pgSQL and PL/SQL, two procedural languages for SQL. The main purpose of pgTAP is to facilitate easy and effective unit testing within PostgreSQL databases.

Unit tests allow you to verify the behavior of small parts of a system, such as functions or procedures, in isolation. They are essential for ensuring that individual components of your software work as expected and can help catch bugs early in the development process.

pgTAP includes a comprehensive collection of TAP-emitting assertion functions. TAP, or Test Anything Protocol, is a simple text-based interface between testing modules in a test harness. pgTAP makes it easy to write TAP-emitting unit tests in psql scripts or xUnit-style test functions.

The benefits of using a tool like pgTAP include:

  • Code quality: unit testing helps ensure code correctness, improve design, and prevent code regressions, leading to higher overall code quality.

  • Ease of use: pgTAP is designed to be easy to use, with a wide range of assertion functions for testing database behavior.

  • Compatibility: since pgTAP is an extension for PostgreSQL, it integrates seamlessly with PostgreSQL databases, making it easier to implement and manage tests.

  • Flexibility: with pgTAP, you can write tests in the same language as your application code, enabling more flexible and efficient testing.

Installing the pgTAP Extension

​Before you can use pgTAP, you need to install it. Here are the steps to install the extension:​

1. Download the latest version of pgTAP from the official website. 2. Extract the downloaded file. 3. Navigate to the extracted directory in your terminal. 4. Run the following commands:

​$ make
$ make install
$ make installcheck

If you encounter any problems running the above commands, please follow the troubleshooting here.

5. Connect to your PostgreSQL database and run the following command to enable the pgTAP extension:


​On Timescale, you can find available extensions by going to Operations > Extensions from your service overview, which will also give you installation instructions.

Using the pgTAP Extension

​Once you have installed pgTAP, you can write tests for your PostgreSQL applications. Here is a simple example of how to use pgTAP:

SELECT plan(2);

SELECT ok(1 = 1, 'One equals one');
SELECT is('PostgreSQL', 'PostgreSQL', 'PostgreSQL is PostgreSQL');

SELECT * FROM finish();

In this example, we first call the plan function to specify the number of tests we will run. Then, we use the ok and is functions to run our tests. Finally, we call the finish function to complete our test suite.

Testing Your PostgreSQL Application

pgTAP can be used to test any PostgreSQL application, including those that work with time-series data. For example, you can use pgTAP to test functions that aggregate time-series data, calculate moving averages, or perform other time-series analyses.

​If you are using the Timescale extension for time-series data, you can use pgTAP to test your Timescale functions and queries. Here is an example of how to use pgTAP with Timescale:

SELECT plan(1);

(SELECT avg(value) FROM measurements WHERE time > NOW() - interval '1 hour') IS NOT NULL,
 'Average value for the last hour is not null'

SELECT * FROM finish();

In this example, we are testing that the average value for the last hour of measurements is not null. This is a simple example, but you can create more complex tests based on your specific needs.


In conclusion, pgTAP is a powerful tool for anyone looking to implement unit testing in their PostgreSQL databases, providing a robust, flexible, and efficient means of ensuring code quality and correctness.

And speaking of testing, If you want to learn more about testing performance improvements on your production databasevements-on-up-to-date-production-data-in-timescale-cloud/, including advice on designing and writing your own tests, check out this article.

Timescale Logo

Subscribe to the Timescale Newsletter

By submitting, I acknowledge Timescale’s Privacy Policy
2024 © Timescale Inc. All rights reserved.