pglive

README

pglive

PostgreSQL live database unit testing

Installation

go get github.com/n-r-w/pglive@latest

Introduction

pglive is a Go package designed to simplify PostgreSQL database testing by providing:

• Isolated test databases for parallel test execution
• Automatic database creation and cleanup
• Flexible configuration options for both Docker and external database setups
• Support for multiple migration tools (gomigrate, goose) with custom migration support
• Comprehensive connection pooling configuration
• Detailed logging capabilities

Features

• Parallel Test Support: Each test runs in its own isolated database instance
• Automatic Cleanup: Databases are automatically created and removed
• Migration Support:
  • Built-in support for gomigrate and goose
  • Custom migration tool integration via WithMigratorFactory
• Connection Management:
  • Configurable connection pooling
  • Connection health checks
  • Timeout and lifetime settings
• Logging:
  • Built-in structured logging
  • Custom logger support
• Configuration Options:
  • Docker and external database support
  • Environment variable and direct parameter configuration
  • GitLab CI integration

There are two operating modes: using Docker and using an external database.

Using Docker

In this case, the default mapping for PostgreSQL on the host is to port 5433 to avoid conflicts with local PostgreSQL. For Docker Desktop on Linux or macOS, you should define DOCKER_SOCKET_ENDPOINT environment variable with:

• Linux: unix:///home/<user>/.docker/desktop/docker.sock
• macOS: unix:///Users/<USER>/.docker/run/docker.sock

Using an external database

This mode is activated in the following cases:

• at least one parameter in Option are used: WithHost, WithPort, WithDatabase, WithUser, WithPassword
• at least one environment variable is set: POSTGRES_HOST, POSTGRES_PORT, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD.

Can be activated in GitLab CI with the following settings in .gitlab-ci.yml. Setting POSTGRES_DB in GitLab environment variables doesn't make sense because the default database won't be used. Example of .gitlab-ci.yml file with PostgreSQL service and environment variables for go tests:

go tests:
  services:
    - name: postgres:16.2 # PostgreSQL image name from <https://hub.docker.com/_/postgres>
      alias: test-postgres
      command: ["-c", "max_connections=200"] # Increasing the number of connections (if you have a lot of parallel tests)
  variables: # Environment variables
    POSTGRES_USER: postgres # Username
    POSTGRES_PASSWORD: secret # Password
    POSTGRES_HOST: test-postgres # Hostname
    POSTGRES_HOST_AUTH_METHOD: trust
    GOFLAGS: # Flags for go test if needed (-tags=xxxx)

Known limitations in external database mode:

• The test database will not be deleted if the test execution is stopped on a breakpoint and not continued.

Parameter filling priority

• If specific value parameters are set (Host, Port, Database, User, Password), the values from these parameters are used.
• If environment variables are set and specific value parameters are not set, the values from the environment variables are used.
• If neither environment variables nor specific value parameters are set, default values are used.

Default values:

PostrgreSQL image: postgres:latest
PostrgreSQL Host: 127.0.0.1
PostrgreSQL port: 5432
PostrgreSQL mapping port: 5433 (Docker mode)
User: postgres
Password: secret

Usage example

Basic Usage

import (
  "testing"
  "context"

  "github.com/jackc/pgx/v5/pgxpool"
  "github.com/n-r-w/pglive"
)

func Test_Example(t *testing.T) {
    t.Parallel()
    
    // Create test database, run migrations and return a database connection
    db := pglive.GetPool(t, "./migrations")
    defer db.Close()

    // Example query
    rows, err := db.Query(context.Background(), "SELECT name FROM test_table")
    if err != nil {
        t.Fatalf("error: %s", err)
    }
    defer rows.Close()
    
    for rows.Next() {
        var name string
        if err := rows.Scan(&name); err != nil {
            t.Fatalf("error: %s", err)
        }
        if name != "test" {
            t.Fatalf("expected 'test', got '%s'", name)
        }
    }
}

Using Specific Migration Tool

import (
  "testing"
  "time"

  "github.com/jackc/pgx/v5/pgxpool"
  "github.com/n-r-w/pglive"
)

func Test_WithGooseMigrations(t *testing.T) {
    t.Parallel()
    
    db := pglive.GetPool(t, "./migrations/goose", 
        pglive.WithMigratorFactory(pglive.GooseMigratorFactory),        
    )
    defer db.Close()
    
    // Test code...
}

func Test_WithGoMigrateMigrations(t *testing.T) {
    t.Parallel()
    
    db := pglive.GetPool(t, "./migrations/gomigrate", 
        pglive.WithMigratorFactory(pglive.GolangMigrateFactory),        
    )
    defer db.Close()
    
    // Test code...
}

Documentation

Index

• func GetPool(tb testing.TB, migrationsDir string, opt ...Option) *pgxpool.Pool
• type Logger
• type Migrator
  • func GolangMigrateFactory(dsn, migrationsDir string, logger Logger) (Migrator, error)
  • func GooseMigratorFactory(dsn, migrationsDir string, logger Logger) (Migrator, error)
• type MigratorFactory
• type Option
  • func WithDatabase(database string) Option
  • func WithDockerImage(dockerImage string) Option
  • func WithDockerPortMapping(dockerPortMapping string) Option
  • func WithDockerSocketEndpoint(dockerSocketEndpoint string) Option
  • func WithForceDockerMode() Option
  • func WithHost(host string) Option
  • func WithLogger(logger Logger) Option
  • func WithMigratorFactory(migratorFactory MigratorFactory) Option
  • func WithPassword(password string) Option
  • func WithPort(port string) Option
  • func WithRetryTimeout(retryTimeout time.Duration) Option
  • func WithUser(user string) Option
• type TestDB
  • func NewTDB(tb testing.TB, opt ...Option) (*TestDB, error)
  • func (d *TestDB) Close() (err error)
  • func (d *TestDB) DSN() string
  • func (d *TestDB) MigrationsUp(migrationsDir, schema string) error

Functions

func GetPool

func GetPool(tb testing.TB, migrationsDir string, opt ...Option) *pgxpool.Pool

GetPool inits a test database, applies migrations, and returns a connection pool to the database.

Types

type Logger

type Logger interface {
	Fatalf(format string, args ...any)
	Logf(format string, args ...any)
}

Logger interface for custom logging.

type Migrator

type Migrator interface {
	Up(ctx context.Context) error
}

Migrator interface for applying migrations.

func GolangMigrateFactory

func GolangMigrateFactory(dsn, migrationsDir string, logger Logger) (Migrator, error)

GolangMigrateFactory creates a new migrator for https://github.com/golang-migrate/migrate.

func GooseMigratorFactory

func GooseMigratorFactory(dsn, migrationsDir string, logger Logger) (Migrator, error)

GooseMigratorFactory creates a new migrator for https://github.com/pressly/goose.

type MigratorFactory

type MigratorFactory func(dsn string, migrationsDir string, logger Logger) (Migrator, error)

MigratorFactory creates a new migrator.

type Option

type Option func(*testDBOptions)

Option option for creating a test database.

func WithDatabase

func WithDatabase(database string) Option

WithDatabase sets the database name. The default is a randomly generated name.

func WithDockerImage

func WithDockerImage(dockerImage string) Option

WithDockerImage sets the name of the postgres image from https://hub.docker.com/_/postgres when running locally in docker. The default is latest.

func WithDockerPortMapping

func WithDockerPortMapping(dockerPortMapping string) Option

WithDockerPortMapping sets the port for mapping postgres to the host when running locally in docker. The default is 5433.

func WithDockerSocketEndpoint

func WithDockerSocketEndpoint(dockerSocketEndpoint string) Option

WithDockerSocketEndpoint sets the docker socket endpoint for connecting to the docker daemon.

func WithForceDockerMode

func WithForceDockerMode() Option

WithForceDockerMode forces the tests to run in docker.

func WithHost

func WithHost(host string) Option

WithHost sets the host for connecting to the database. The default is 127.0.0.1

func WithLogger

func WithLogger(logger Logger) Option

WithLogger sets the logger for the test database.

func WithMigratorFactory

func WithMigratorFactory(migratorFactory MigratorFactory) Option

WithMigratorFactory sets the migrator factory for the test database. The default is goose.

func WithPassword

func WithPassword(password string) Option

WithPassword sets the password. The default is "secret".

func WithPort

func WithPort(port string) Option

WithPort sets the port for connecting to the database. The default is 5432.

func WithRetryTimeout

func WithRetryTimeout(retryTimeout time.Duration) Option

WithRetryTimeout sets the timeout for connecting to the database. The default is 30 seconds.

func WithUser

func WithUser(user string) Option

WithUser sets the user name. The default is "postgres".

type TestDB

type TestDB struct {
	// contains filtered or unexported fields
}

TestDB creates a connection to a temporary test cluster databasepg, allows you to deploy migrations on it and run tests.

func NewTDB

func NewTDB(tb testing.TB, opt ...Option) (*TestDB, error)

NewTDB creates a new test database.

func (*TestDB) Close

func (d *TestDB) Close() (err error)

Close closes the test database.

func (*TestDB) DSN

func (d *TestDB) DSN() string

DSN returns the data source name for connecting to the database.

func (*TestDB) MigrationsUp

func (d *TestDB) MigrationsUp(migrationsDir, schema string) error

MigrationsUp applies migrations to the database.