Documentation
¶
Overview ¶
Package sqltest makes it easy to write tests using pgx and tern.
Index ¶
- Variables
- func Quick(t testing.TB, files fs.FS) *pgxpool.Pool
- func SQLTestName(t testing.TB) string
- type 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
Constants ¶
This section is empty.
Variables ¶
var ( // DatabasePrefixes allowed to be used for creating a temporary database. // It mitigates the risk of running migration and tests on the wrong database. DatabasePrefixes = []string{"test", "benchmark", "fuzz"} // SchemaVersionTable where tern saves the version of the current migration in PostgreSQL. SchemaVersionTable = "schema_version" // Empty is used to create a temporary test database without running migrations. Empty fs.FS = emptyFS{} )
Functions ¶
func Quick ¶ added in v0.3.0
Quick connects to a PostgreSQL database using environment variables, runs migrations, and returns a pgx connection pool.
If you want a connection to the data pool without migrations, use sqltest.Empty as the files parameter.
If a database already exists, it will be dropped and recreated. To do this as safe as possible by default the databases managed by sqltest use a "test" prefix.
func SQLTestName ¶
SQLTestName takes a test name, normalizes it, and outputs a database name for usage. The name is lowercase, stripped of invalid runes, and has '/' replaced with '__'. Long test names are truncated and suffixed with a hash to fit PostgreSQL's identifier limit.
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 (*Migration) MigrateTo ¶
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 ¶
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
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.
//
// The prefix must start with a prefix allowed in DatabasePrefixes.
TemporaryDatabasePrefix string
// Files to use in the migration.
// Implement embed.FS or use os.DirFS to load the migration files.
// e.g., os.DirFS("migrations/")
Files fs.FS
// Logs enables printing status of the migration step-by-step.
Logs bool
}
Options for the migration.
Source Files
Directories