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. The server is sized to the host's CPU and memory limits (commonsdb.ScaledTestingParameters); a reused server started with lower settings logs a warning naming the command that stops it. Where it lives is configurable:
COMMONS_DB_DATA_DIR "tmpfs" puts the cluster in RAM: /dev/shm on
Linux, a RAM disk volume /Volumes/commons-db on
macOS; any other value is a literal path
COMMONS_DB_TMPFS_SIZE RAM the tmpfs cluster requires (default 2GB)
COMMONS_DB_BIN_DIR PostgreSQL binaries (default
$TMPDIR/commons-db/bin); never put on tmpfs
An empty pool never makes a caller wait for more than one CREATE DATABASE: checkout creates its own database outside the pool lock and a background refill tops the pool up to max(5, GOMAXPROCS) free databases.
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.
Every created database is named commons_db_test_<unix>_<unique>_<name> and leased: an advisory lock on its name is held from before it exists until it is dropped. Each resolution starts a background sweep that drops test databases whose lock is no longer held, so databases leaked by a killed or timed-out test process are reclaimed by the next run. ForT and ForGinkgo drop their database in the background and only log teardown failures.
Index ¶
Constants ¶
const ( // EnvDataDir moves the embedded cluster: "tmpfs" puts it on a RAM-backed // filesystem (/dev/shm on Linux, a RAM disk volume on macOS); any other // value is a literal path. EnvDataDir = "COMMONS_DB_DATA_DIR" // EnvBinDir overrides where the PostgreSQL binaries are extracted. They are // never put on tmpfs, so they survive a reboot. EnvBinDir = "COMMONS_DB_BIN_DIR" // EnvTmpfsSize is the RAM-backed filesystem size COMMONS_DB_DATA_DIR=tmpfs // requires, e.g. "4GB". Defaults to 2GB. EnvTmpfsSize = "COMMONS_DB_TMPFS_SIZE" )
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 a non-blocking, non-fatal teardown 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 a non-blocking, non-fatal teardown 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, and takes precedence over
// COMMONS_DB_DATA_DIR. 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