Documentation
¶
Overview ¶
Package provision defines the Provisioner abstraction for spinning up ephemeral database instances during verify runs, and provides:
- Provisioner — the interface every provisioner must satisfy.
- FakeProvisioner — a deterministic in-memory fake used by unit tests.
- NewTestcontainers — a real provisioner backed by testcontainers-go (see containers.go); it requires Docker and is integration-only.
Design ¶
The provisioner is OPT-IN. The verify command's default behaviour (reading DB_CATALYST_VERIFY_DSN from the environment) is unchanged. Callers that want auto-provisioning call Provision, use the returned DSN, then call cleanup.
Graceful degradation ¶
If Docker is unavailable, NewTestcontainers returns a provisioner whose Provisioner.Provision call returns ErrDockerUnavailable. Callers should treat that error as a signal to skip the verify run (or fall back to the manual DSN path).
Intended cmd wiring ¶
When `db-catalyst verify --database postgres --provision` is invoked, the command should:
- Call provision.NewTestcontainers() to obtain a Provisioner.
- Call p.Provision(ctx, "postgres") to spin up a container and get a DSN.
- If the error is ErrDockerUnavailable (or wraps it), log a message and skip verification (same behaviour as missing DB_CATALYST_VERIFY_DSN).
- Construct a postgres.New(dsn) verifier and run it as today.
- Defer cleanup() to terminate and remove the container.
The --provision flag is additive; the existing --dsn / env-var path is unchanged and remains the default.
Index ¶
Constants ¶
This section is empty.
Variables ¶
ErrDockerUnavailable is returned by a testcontainers-backed Provisioner when no Docker daemon can be reached. Callers that receive this error (or an error wrapping it) should skip verification rather than failing hard.
Functions ¶
This section is empty.
Types ¶
type FakeProvisioner ¶
type FakeProvisioner struct {
// DSN is the value returned by Provision when Err is nil.
DSN string
// Err, if non-nil, is returned as the error from Provision (DSN="" and
// cleanup=nil in that case).
Err error
// LastDialect is set to the dialect argument of the most recent Provision
// call. Tests can assert it was invoked with the expected dialect.
LastDialect string
// CleanupCalled is set to true when the cleanup func returned by Provision
// is invoked. Tests can assert cleanup was called after the flow completes.
CleanupCalled bool
}
FakeProvisioner is a deterministic in-process Provisioner for use in unit tests. It never contacts Docker or any real infrastructure.
Configure the behaviour via exported fields before calling Provision.
func (*FakeProvisioner) Provision ¶
Provision implements Provisioner. It records the dialect, and either returns the configured error or returns FakeProvisioner.DSN plus a cleanup func that marks CleanupCalled.
type Provisioner ¶
type Provisioner interface {
// Provision starts an ephemeral instance for the given dialect
// ("postgres" or "mysql") and returns its DSN and a cleanup function.
//
// If Docker is unavailable, Provision returns [ErrDockerUnavailable] (or
// an error wrapping it) with an empty DSN and nil cleanup.
//
// On any other error, DSN is empty and cleanup is nil.
Provision(ctx context.Context, dialect string) (dsn string, cleanup func(), err error)
}
Provisioner spins up an ephemeral database instance and returns a DSN that can be passed to a [verify.Verifier].
Implementations must be safe to call from a single goroutine. The returned cleanup func terminates and removes the container (or equivalent resource); it must be called exactly once and must not panic.
func NewTestcontainers ¶
func NewTestcontainers() Provisioner
NewTestcontainers returns a Provisioner that uses testcontainers-go to spin up ephemeral database containers. It supports "postgres" and "mysql".
If Docker is unavailable at Provision time, Provision returns ErrDockerUnavailable and the caller should skip the verify run.
This provisioner is intended for integration and CI environments where Docker is available. It is explicitly NOT the default code path: callers must opt in by constructing this provisioner and passing it to their verify flow.
Source Files