dbtest

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 14, 2026 License: MIT Imports: 16 Imported by: 0

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

View Source
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.

View Source
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.

View Source
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

View Source
var HostBundleDir = filepath.Join(hostWorkDir, "bundle")

HostBundleDir is the sqlite target's bundle directory, the host-side counterpart of ContainerBundleDir.

View Source
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

func IsASCIIOnly(s string) bool

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

func UTF8Hex(s string) string

UTF8Hex encodes a string into lowercase hexadecimal UTF-8 bytes to verify against hex queries on UTF-8 database engines.

func UTF16LEHex

func UTF16LEHex(s string) string

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

func Lookup(dialect string) (Target, bool)

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

func (tg Target) BundleDir() string

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

func (tg Target) Compare(t testing.TB, want []string, got map[int]string)

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

func (tg Target) CopyIn(t testing.TB, localPath string)

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

func (tg Target) DSN(t testing.TB) string

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

func (tg Target) ExecIn(t testing.TB, workdir string, argv ...string) string

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

func (tg Target) Host(t testing.TB) string

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

func (tg Target) Loaded(t testing.TB) map[int]string

Loaded retrieves stored rows as hex strings keyed by row ID, allowing exact byte-level verification without client string escaping interference.

func (Target) MappedPort

func (tg Target) MappedPort(t testing.TB) int

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

func (tg Target) Query(t testing.TB, sql string) string

Query executes a single SQL statement using the database's CLI client and returns stdout, ensuring statements execute exactly as a user client would.

func (Target) RunFile

func (tg Target) RunFile(t testing.TB, name string)

RunFile executes a script file already placed in the target's bundle dir. Clients without file flags (like MySQL and SQLite) feed the file via stdin redirection, matching generated bulk script instructions.

func (Target) Setup

func (tg Target) Setup(t testing.TB)

Setup initializes the database, creates the target table, and prepares an empty bundle directory so subsequent test loads start from a known state.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL