pgtestdb

What pgtestdb is

pgtestdb is a free, open-source Go library for database-backed tests that use PostgreSQL. It prepares a migrated template database, then clones it so each test runs against its own isolated database. The project describes creating a test database from the template as taking on the order of 10 milliseconds, and says separate databases allow tests to run in parallel safely.

The library uses Go’s database/sql interface, with support for pgx, lib/pq, and other compatible drivers. Its built-in migration adapters cover pgmigrate, golang-migrate, goose, dbmate, Atlas, sql-migrate, Bun, and Tern; custom migrators can also be used. You provide a running Postgres server, which may be Docker-based, installed locally, or remote. The configured server user must be able to create databases and roles, and the project recommends using a dedicated testing server. Databases created for passing tests are removed automatically. When a test fails, its database is kept and a connection string is logged for inspection. pgtestdb is MIT licensed and maintained under the peterldowns GitHub account.

Who it suits

pgtestdb suits Go developers who need isolated PostgreSQL databases for schema migration tests or other database-backed tests. It is particularly relevant to teams running tests in parallel and using a supported migration tool or custom migrator.

Limits

The default test role has NOSUPERUSER, NOCREATEDB, and NOCREATEROLE capabilities, so it cannot create extensions by default. Highly parallel test suites can also exceed the Postgres server’s connection limit; the project suggests adjusting test parallelism or server capacity.

Getting started

1. Provide a running Postgres server, using Docker, a native installation, or a remote server.
2. Configure a server user that can create databases and roles; use a dedicated testing server.
3. Use Go’s database/sql interface with pgx, lib/pq, or another compatible driver.
4. Connect a built-in migration adapter or provide a custom migrator.
5. Run tests so pgtestdb can build a migrated template and clone a database for each test.

Verdict

Choose pgtestdb if your Go tests need isolated PostgreSQL databases, especially when you want parallel execution and integration with common migration tools. It requires a running Postgres server with database and role creation permissions, so teams without that infrastructure should look elsewhere.