sqltest

Documentation

Overview

Package sqltest makes it easy to write tests using pgx and tern.

Index

• Variables
• func SQLTestName(t testing.TB) string
• type Migration
  • func New(t testing.TB, o Options) *Migration
  • func (m *Migration) Setup(ctx context.Context, connString string) *pgxpool.Pool
  • func (m *Migration) Teardown(ctx context.Context)
• type Options

Variables

var (
	// DatabasePrefix defines a prefix for the database name.
	// It is used to mitigate the risk of running migration and tests on the wrong database.
	DatabasePrefix = "test"

	// SchemaVersionTable where tern saves the version of the current migration in PostgreSQL.
	SchemaVersionTable = "schema_version"
)

Functions

func SQLTestName

func SQLTestName(t testing.TB) string

SQLTestName normalizes a test name to a database name. It lowercases the test name and converts / to underscore.

Types

type Migration

type Migration struct {
	Options Options
	// contains filtered or unexported fields
}

Migration simplifies avlidadting the migration process, and setting up a test database for executing your PostgreSQL-based tests on.

func New

func New(t testing.TB, o Options) *Migration

New migration to use with a test.

func (*Migration) Setup

func (m *Migration) Setup(ctx context.Context, connString string) *pgxpool.Pool

Setup the migration. This function returns a pgx pool that can be used to connect to the database. If something fails, t.Fatal is called.

It register the Teardown function with testing.TB to clean up the database once the tests are over by default, but this can be disabled by setting the SkipTeardown option.

If the UseExisting option is set, a temporary database is used for running the tests.

If you're using PostgreSQL environment variables, you should pass an empty string as the connection string, as in:

pool := m.Setup(context.Background(), "")

Reference for configuring the PostgreSQL client with environment variables: https://www.postgresql.org/docs/current/libpq-envars.html

Reference for using connString: https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING

func (*Migration) Teardown

func (m *Migration) Teardown(ctx context.Context)

Teardown database after running the tests. This function is registered by Setup to be called automatically by the testing package during testing cleanup.

In case this is not called, you can use the Force option to reset the database.

type Options

type Options struct {
	// Force clean the database if it's dirty.
	Force bool

	// SkipTeardown stops the Teardown function being registered with testing cleanup.
	// You can use this to debug migration after running a specific test.
	//
	// Be aware that you'll encounter errors if you try to run a migration multiple times without
	// a proper cleaning up. To forcefully clean up the database, you can use the force option.
	SkipTeardown bool

	// UseExisting database from connection instead of creating a temporary one.
	// If set, the database isn't dropped after the tests.
	UseExisting bool

	// TemporaryDatabasePrefix for namespacing the temporary database name created for the test function.
	// Useful if you're running multiple tests in parallel to avoid flaky tests due to naming clashes.
	// Ignore if using UseExisting.
	TemporaryDatabasePrefix string

	// Path to the migration files.
	Path string
}

Options for the migration.