postgrestest

README

github.com/stapelberg/postgrestest

Package postgrestest provides a test harness that starts an ephemeral PostgreSQL server. It is tested on macOS, Linux, and Windows. It can cut down the overhead of PostgreSQL in tests up to 90% compared to spinning up a postgres Docker container: starting a server with this package takes roughly 650 milliseconds and creating a database takes roughly 20 milliseconds.

Example

func TestApp(t *testing.T) {
	// Start up the PostgreSQL server. This can take a few seconds, so better to
	// do it once per test run.
	ctx := context.Background()
	srv, err := postgrestest.Start(ctx)
	if err != nil {
		t.Fatal(err)
	}
	t.Cleanup(srv.Cleanup)

	// Each of your subtests can have their own database:
	t.Run("Test1", func(t *testing.T) {
		db, err := srv.NewDatabase(ctx)
		if err != nil {
			t.Fatal(err)
		}
		if _, err := db.Exec(`CREATE TABLE foo (id SERIAL PRIMARY KEY);`); err != nil {
			t.Fatal(err)
		}
		// ...
	})

	t.Run("Test2", func(t *testing.T) {
		db, err := srv.NewDatabase(ctx)
		if err != nil {
			t.Fatal(err)
		}
		if _, err := db.Exec(`CREATE TABLE foo (id SERIAL PRIMARY KEY);`); err != nil {
			t.Fatal(err)
		}
		// ...
	})
}

Installation

PostgreSQL must be installed locally for this package to work. See the PostgreSQL Downloads page for instructions on how to obtain PostgreSQL for your operating system.

To install the package:

go get github.com/stapelberg/postgrestest

License

Apache 2.0

Documentation

Overview

Package postgrestest provides a test harness that starts an ephemeral PostgreSQL server. PostgreSQL must be installed locally for this package to work.

Example

package main

import (
	"context"
	"testing"

	"github.com/stapelberg/postgrestest"
)

func main() {
	var t *testing.T // passed into your testing function

	// Start up the PostgreSQL server. This can take a few seconds, so better to
	// do it once per test run.
	ctx := context.Background()
	srv, err := postgrestest.Start(ctx)
	if err != nil {
		t.Fatal(err)
	}
	t.Cleanup(srv.Cleanup)

	// Each of your subtests can have their own database:
	t.Run("Test1", func(t *testing.T) {
		db, err := srv.NewDatabase(ctx)
		if err != nil {
			t.Fatal(err)
		}
		if _, err := db.Exec(`CREATE TABLE foo (id SERIAL PRIMARY KEY);`); err != nil {
			t.Fatal(err)
		}
		// ...
	})

	t.Run("Test2", func(t *testing.T) {
		db, err := srv.NewDatabase(ctx)
		if err != nil {
			t.Fatal(err)
		}
		if _, err := db.Exec(`CREATE TABLE foo (id SERIAL PRIMARY KEY);`); err != nil {
			t.Fatal(err)
		}
		// ...
	})
}

Index

• type Config
• type DBCreator
  • func NewDBCreator(pgurl string) (*DBCreator, error)
  • func (c *DBCreator) CreateDatabase(ctx context.Context) (dsn string, _ error)
• type Option
  • func WithDir(dir string) Option
  • func WithSQLDriver(driver string) Option
• type Server
  • func Start(ctx context.Context, opts ...Option) (_ *Server, err error)
  • func (srv *Server) Cleanup()
  • func (srv *Server) CreateDatabase(ctx context.Context) (string, error)
  • func (srv *Server) DefaultDatabase() string
  • func (srv *Server) NewDatabase(ctx context.Context) (*sql.DB, error)

Examples

• Package

Types

type Config

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

A Config configures a PostgreSQL test server.

type DBCreator

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

DBCreator allows creating ephemeral databases (think CREATE DATABASE) within the ephemeral PostgreSQL instance. This functionality is decoupled from the Server so that it can work with a PostgreSQL instance that was created out of process.

func NewDBCreator

func NewDBCreator(pgurl string) (*DBCreator, error)

NewDBCreator returns a database creator for the PostgreSQL instance identified by the specified DSN.

func (*DBCreator) CreateDatabase

func (c *DBCreator) CreateDatabase(ctx context.Context) (dsn string, _ error)

CreateDatabase creates a new database on the server and returns its data source name.

type Option

type Option func(*Config)

A Option changes something in Config.

func WithDir

func WithDir(dir string) Option

WithDir specifies a directory in which postgrestest should set up PostgreSQL. By default, a temporary directory is used.

func WithSQLDriver

func WithSQLDriver(driver string) Option

WithSQLDriver sets the SQL driver that postgrestest should use to connect to the database. The default is "postgres" (implemented by github.com/lib/pq), another tested choice is "pgx" (implemented by github.com/jackc/pgx).

The general recommendation is to use the same driver as you already use for the rest of your non-test code, to keep dependencies minimal.

type Server

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

A Server represents a running PostgreSQL server.

func Start

func Start(ctx context.Context, opts ...Option) (_ *Server, err error)

Start starts a PostgreSQL server with an empty database and waits for it to accept connections.

Start looks for the programs "pg_ctl" and "initdb" in PATH. If these are not found, then Start searches for them in /usr/lib/postgresql/*/bin, preferring the highest version found.

func (*Server) Cleanup

func (srv *Server) Cleanup()

Cleanup shuts down the server and deletes any on-disk files the server used.

func (*Server) CreateDatabase

func (srv *Server) CreateDatabase(ctx context.Context) (string, error)

CreateDatabase creates a new database on the server and returns its data source name.

func (*Server) DefaultDatabase

func (srv *Server) DefaultDatabase() string

DefaultDatabase returns the data source name of the default "postgres" database.

func (*Server) NewDatabase

func (srv *Server) NewDatabase(ctx context.Context) (*sql.DB, error)

NewDatabase opens a connection to a freshly created database on the server.