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) MigrateTo(ctx context.Context, targetVersion int32)
  • func (m *Migration) Setup(ctx context.Context, connString string) *pgxpool.Pool
  • func (m *Migration) SetupVersion(ctx context.Context, connString string, targetVersion int32) *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) MigrateTo

func (m *Migration) MigrateTo(ctx context.Context, targetVersion int32)

MigrateTo migrates to targetVersion.

You probably only need this if you need to test code against an older version of your database, or if you are testing a migration process.

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) SetupVersion

func (m *Migration) SetupVersion(ctx context.Context, connString string, targetVersion int32) *pgxpool.Pool

SetupVersion of the migrations is similar to the Setup version, but migrates to the given target version.

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. Use the SkipTeardown option to disable this.

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 during teardown / test cleanup.
	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

	// Files to use in the migration.
	// e.g., os.DirFS("migrations/")
	Files fs.FS
}

Options for the migration.