Documentation
¶
Overview ¶
Package postgrestest provides real PostgreSQL containers for integration tests. It requires a compatible container runtime for Open and never substitutes a fake for PostgreSQL semantics. Release test fixtures with Shutdown. RunIsolated rolls back only work performed on its supplied transaction.
Index ¶
Constants ¶
const ( // DefaultIsolationCleanupTimeout bounds the rollback that restores test // isolation after cancellation, panic, or goroutine termination. DefaultIsolationCleanupTimeout = 5 * time.Second )
Variables ¶
var ( // ErrNilIsolationCallback reports a missing isolated test body. ErrNilIsolationCallback = errors.New("postgrestest: isolation callback is nil") )
Functions ¶
func RunIsolated ¶
func RunIsolated( ctx context.Context, beginner IsolationBeginner, fn func(context.Context, pgx.Tx) error, ) (err error)
RunIsolated executes fn once in a transaction that is always rolled back. It is suitable only when the code under test does not commit, open other connections, execute non-transactional DDL, or depend on external side effects. Callback and rollback errors remain inspectable through errors.Is and errors.As. A panic triggers bounded rollback before the original value is re-panicked, and goroutine termination cannot skip rollback. A cleanup panic cannot replace a returned callback error or either terminal callback path. With no earlier callback cause, a rollback panic propagates rather than reporting successful isolation. A non-nil ctx and usable beginner are required; the callback must not retain or finalize tx. Cleanup detaches caller cancellation and deadlines but retains context values. The callback itself is not forcibly bounded and this helper performs no retries.
Types ¶
type Config ¶
type Config struct {
// Image selects the container image; empty selects postgres:18-alpine.
Image string
// Database selects the initial database; empty selects postgres_test.
Database string
// Username selects the test login; empty selects postgres_test.
Username string
// Password selects test credentials; empty selects postgres_test. Never
// log the DSN.
Password string
// HostPort optionally binds PostgreSQL to a stable loopback port. It is
// useful for stop/start tests whose client endpoint must not move.
HostPort string
// CleanupTimeout bounds container termination even when the setup context
// has already been canceled. Nonpositive values select 30s.
CleanupTimeout time.Duration
// Setup runs once after startup. An error, panic, or goroutine termination
// triggers bounded container cleanup without replacing the original cause.
Setup func(context.Context, string) error
}
Config controls an isolated PostgreSQL container. Setup runs exactly once after PostgreSQL is accepting connections and receives its complete DSN. Setup errors, panics, or goroutine termination trigger bounded container cleanup. The original setup panic is preserved even if termination also panics.
type Database ¶
type Database struct {
// contains filtered or unexported fields
}
Database owns a PostgreSQL test container and its connection string. Acquire it with Open; its zero value is not usable and it must not be copied after use. Concurrent Shutdown calls share one termination; native Container operations require separate application coordination.
func Open ¶
Open creates a PostgreSQL container, waits for readiness, obtains a DSN, and invokes the optional setup hook synchronously. Nil or already-canceled ctx is refused before startup. A successful result transfers fixture ownership to the caller, who must Shutdown it. Returned connection-string/setup errors may join cleanup errors and can contain native or application credentials. Setup must cooperate with ctx; cleanup bounds cannot preempt blocking code.
func (*Database) Container ¶
func (d *Database) Container() *testcontainerspostgres.PostgresContainer
Container borrows the native testcontainers PostgreSQL container without transferring ownership. Direct stop/start or termination bypasses this helper lifecycle; coordinate it explicitly and retain responsibility for Shutdown.
func (*Database) DSN ¶
DSN returns the complete pgx-compatible connection string. Treat it as a secret because it contains the configured test credentials.
func (*Database) Shutdown ¶
Shutdown starts one caller-independent, bounded container termination and lets each caller wait with its own context. Repeated calls return the shared terminal termination result. The first caller supplies context values, but its cancellation/deadline is detached from termination and replaced with the configured cleanup timeout. A caller that stops waiting has not proved cleanup completed. Native termination must cooperate with its context; it is not forcibly interrupted. Nil ctx is refused without starting termination.
type IsolationBeginner ¶
type IsolationBeginner interface {
// Begin returns a transaction to be borrowed by the isolation callback and
// then rolled back.
Begin(context.Context) (pgx.Tx, error)
}
IsolationBeginner is implemented by pgx.Conn, pgxpool.Pool, pgxpool.Conn, and pgx.Tx values that can begin a transaction.
Source Files