Documentation
¶
Overview ¶
Package dbtest resolves the PostgreSQL database that integration tests run against.
Tests do not choose between an embedded and an external server themselves; they call ForT / ForGinkgo (or Open, for a framework-agnostic handle) and get whichever the environment provides:
COMMONS_DB_URL connect to this server instead of embedding one
COMMONS_DB_CREATE "false" uses COMMONS_DB_URL as-is; anything else
(including unset) carves out a fresh database
When COMMONS_DB_URL is unset, dbtest starts or reuses the persistent embedded PostgreSQL server under $TMPDIR/commons-db and checks out an isolated database from its cross-process pool.
Supplying Options.Provisioner replaces the empty-database pool with a content-addressed PostgreSQL template. The first matching request prepares and seals the template; every request clones it, runs instance preparation, and drops only the clone during cleanup. Templates are retained for reuse and superseded templates older than 24 hours are removed when they are unlocked. Provisioners require database creation and are rejected when COMMONS_DB_CREATE=false.
Index ¶
Constants ¶
const ( EnvURL = "COMMONS_DB_URL" EnvCreate = "COMMONS_DB_CREATE" )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB is a resolved test database. The handle accessors are lazy and memoised, so a test that only needs a DSN never opens a pool. They do not return errors: a database that cannot be reached is a dead test, so they abort through the failure handler the constructing adapter installed.
func ForGinkgo ¶
ForGinkgo resolves a database for a Ginkgo spec and registers cleanup with DeferCleanup.
Call it from BeforeAll or BeforeEach — DeferCleanup binds the teardown to whichever node is running, so a BeforeAll resolution is torn down after the containing Ordered container rather than after each spec.
func ForT ¶
ForT resolves a database for a standard library / testify test and registers cleanup on t.
func Open ¶
Open resolves a database according to the environment. The returned cleanup closes every handle the DB produced and drops the database if Open created one; callers own it.
Handle accessors on the returned DB panic on failure. ForT and ForGinkgo install their framework's failure handler instead.
type Options ¶
type Options struct {
// Name seeds the database name. Required.
Name string
// DataDir overrides where an embedded server keeps its cluster. Ignored
// when COMMONS_DB_URL is set. Defaults to $TMPDIR/commons-db.
DataDir string
// LogName labels the gorm SQL logger. Defaults to Name.
LogName string
// Provisioner prepares a reusable schema template and reconciles each
// isolated database cloned from it. It cannot be used when
// COMMONS_DB_CREATE=false.
Provisioner Provisioner
}
Options configures how a test database is resolved.
type Provisioner ¶ added in v0.1.26
type Provisioner interface {
Fingerprint(context.Context) (string, error)
PrepareTemplate(ctx context.Context, connection string) error
PrepareInstance(ctx context.Context, connection string) error
}
Provisioner describes the database content required by a test. Fingerprint identifies reusable template content, PrepareTemplate builds a missing template, and PrepareInstance reconciles every isolated clone.
Source Files