postgrestest

README

zombiezen.com/go/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 zombiezen.com/go/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"

	"zombiezen.com/go/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 Server
  • func Start(ctx context.Context) (_ *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 Server

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

A Server represents a running PostgreSQL server.

func Start

func Start(ctx context.Context) (_ *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.