Documentation
¶
Overview ¶
Package dbtest provides the database container test harness and targets used across integration tests in mockagen.
Targets include the three containerized databases (PostgreSQL, MySQL, SQL Server) and a fourth local target (SQLite) whose container step is a no-op, allowing uniform four-dialect test tables.
Containers are started lazily upon first need and terminated via Teardown, typically called from TestMain.
Index ¶
- Constants
- Variables
- func IsASCIIOnly(s string) bool
- func Teardown()
- func UTF8Hex(s string) string
- func UTF16LEHex(s string) string
- type ServerImage
- type Target
- func (tg Target) BundleDir() string
- func (tg Target) Compare(t testing.TB, want []string, got map[int]string)
- func (tg Target) Container(t testing.TB) testcontainers.Container
- func (tg Target) CopyIn(t testing.TB, localPath string)
- func (tg Target) DSN(t testing.TB) string
- func (tg Target) ExecIn(t testing.TB, workdir string, argv ...string) string
- func (tg Target) Host(t testing.TB) string
- func (tg Target) Loaded(t testing.TB) map[int]string
- func (tg Target) MappedPort(t testing.TB) int
- func (tg Target) Query(t testing.TB, sql string) string
- func (tg Target) RunFile(t testing.TB, name string)
- func (tg Target) Setup(t testing.TB)
Constants ¶
const ContainerBundleDir = "/tmp/mockagen-bundle"
ContainerBundleDir is where a generated bundle is copied inside the container (or the local filesystem for sqlite). The bulk scripts reference their CSV by bare name, so the client is run with this as its working directory - matching what a user does after unpacking the bundle.
const MSSQLPassword = "Mockagen1!"
MSSQLPassword satisfies SQL Server's password complexity rules (length, uppercase, lowercase, numbers, and symbols), and is used both to start the container and to connect to it.
const StartupTimeout = 3 * time.Minute
StartupTimeout bounds how long a database server gets to become usable. SQL Server needs the most of the three and is comfortably inside this on a cold start.
Variables ¶
var HostBundleDir = filepath.Join(hostWorkDir, "bundle")
HostBundleDir is the sqlite target's bundle directory, the host-side counterpart of ContainerBundleDir.
var SQLiteDBPath = filepath.Join(hostWorkDir, "mockagen.db")
SQLiteDBPath is the sqlite target's database file. It sits beside HostBundleDir rather than inside it, so that wiping the bundle between loads does not drop the active database.
Functions ¶
func IsASCIIOnly ¶
IsASCIIOnly detects whether a string contains non-ASCII runes, used to filter test suites for targets with known codepage restrictions.
func Teardown ¶
func Teardown()
Teardown stops and removes every container started during the test run. It is designed for TestMain invocation after m.Run(), avoiding orphan containers across test failures.
func UTF8Hex ¶
UTF8Hex encodes a string into lowercase hexadecimal UTF-8 bytes to verify against hex queries on UTF-8 database engines.
func UTF16LEHex ¶
UTF16LEHex encodes a string as lowercase hexadecimal UTF-16LE, matching SQL Server's nvarchar storage format including surrogate pairs.
Types ¶
type ServerImage ¶
type ServerImage struct {
// contains filtered or unexported fields
}
ServerImage describes how one database server is started: the image ref, environment variables, command overrides, and a readiness probe strategy. The readiness checks run each server's own CLI client inside the container rather than probing ports, because listening sockets accept connections before the database engine finishes initialization.
type Target ¶
type Target struct {
// Dialect is the mockagen dialect identifier (e.g. "postgres", "mysql",
// "mssql", "sqlite").
Dialect string
// Port is the internal TCP port for containerized databases (5432, 3306,
// 1433). For SQLite, Port is 0.
Port int
// Client is the argv prefix that runs the database CLI client against
// the test database.
Client []string
// Env is set for every command execution. MySQL requires MYSQL_PWD here
// to prevent interactive password warnings on stderr.
Env []string
// InitSQL runs before anything else, creating the database where the
// container image does not create one automatically (e.g. MSSQL).
InitSQL []string
// DDL creates the test table the integration tests load into.
DDL string
// FileFlag is how the CLI client is instructed to execute a file (empty
// means pipe file content via stdin).
FileFlag string
// QueryFlag is how the CLI client is given a single statement to execute.
QueryFlag string
// SelectHex returns "<id>:<hex of value>" per row, ordered by id.
SelectHex string
// Encode renders an expected Go string as hex matching the database's
// internal storage format.
Encode func(string) string
// BulkASCIIOnly restricts the bulk round-trip to ASCII values. Only
// SQL Server for Linux requires this due to CODEPAGE limitations.
BulkASCIIOnly bool
// contains filtered or unexported fields
}
Target describes one database under test and encapsulates how to start, initialize, query, and bulk-load data into it across both containerized services and local SQLite.
func Lookup ¶
Lookup finds a target by its mockagen dialect name (accepting both sqlite and sqlite3), returning false if the dialect is not supported.
func ServerTargets ¶
func ServerTargets() []Target
ServerTargets returns the three container-backed database targets, for tests that specifically exercise remote database server processes.
func Targets ¶
func Targets() []Target
Targets returns all four supported database targets, including SQLite, so multi-dialect test matrices stay uniform at four rows.
func (Target) BundleDir ¶
BundleDir is where this target's bundle lives: a path inside the container for a containerized target, and the per-process host directory for sqlite. One constant could not serve both - it was being MkdirAll'd on the host and used as a container working directory at the same time.
func (Target) Compare ¶
Compare checks that every loaded row value matches the expected hex byte-for-byte.
func (Target) Container ¶
func (tg Target) Container(t testing.TB) testcontainers.Container
Container starts this target's server if not already running, and returns the shared container instance. SQLite returns nil because it runs locally without Docker overhead.
func (Target) CopyIn ¶
CopyIn places a file into the target's bundle dir. Files are copied with 0o644 permissions so server processes running under non-root container users (such as mssql) can open them directly for bulk ingestion.
func (Target) DSN ¶
DSN constructs a connection string suitable for database drivers pointing at this target. For SQLite, this returns the filesystem path to the file.
func (Target) ExecIn ¶
ExecIn runs argv inside the service (or locally for SQLite), optionally with a working directory, returning its combined output. Container runs use Multiplexed de-framing so Docker stream headers do not corrupt output.
func (Target) Host ¶
Host returns the reachable host address for the container port, resolving bridge or port-forwarding addresses. SQLite returns "" since it is local.
func (Target) Loaded ¶
Loaded retrieves stored rows as hex strings keyed by row ID, allowing exact byte-level verification without client string escaping interference.
func (Target) MappedPort ¶
MappedPort returns the host TCP port mapped to the container's database port, allowing host-bound Go SQL drivers to connect. SQLite returns 0 because it has no network port.
func (Target) Query ¶
Query executes a single SQL statement using the database's CLI client and returns stdout, ensuring statements execute exactly as a user client would.