testutil

Documentation

Overview

Package testutil provides shared helpers for integration tests that require a live MySQL connection. All helpers are designed for use in test functions and call t.Fatal/t.Skip on errors as appropriate.

Index

• Constants
• func BaseDSN() string
• func CreateTestDB(t *testing.T) (*sql.DB, string)
• func CreateTestMariaDB(t *testing.T) (*sql.DB, string)
• func InitIndexTables(t *testing.T, db *sql.DB)
• func InsertEvent(t *testing.T, db *sql.DB, binlogFile string, startPos, endPos uint64, ...)
• func InsertSnapshot(t *testing.T, db *sql.DB, snapshotID int, ...)
• func IntegrationDSN(dbName string) string
• func MariaDBBaseDSN() string
• func MariaDBRequired() bool
• func MustExec(t *testing.T, db *sql.DB, query string, args ...any)
• func MySQLRequired() bool
• func PostgresDSN() string
• func PostgresRequired() bool
• func RequiredPGExtensions() map[string]bool
• func SetupPartitionedTable(t *testing.T, db *sql.DB, dbName string, hours []time.Time)
• func SkipIfNoMariaDB(t *testing.T)
• func SkipIfNoMySQL(t *testing.T)
• func SkipIfNoPostgres(t *testing.T) string
• func SkipOrFailMariaDB(t *testing.T, format string, args ...any)
• func SnapshotDSN(dbName string) string

Constants

const DefaultDSN = "root:testroot@tcp(127.0.0.1:13306)"

DefaultDSN is the base DSN used when BINTRAIL_TEST_DSN is not set. It assumes a local Docker container on port 13306 with root:testroot.

const MariaDBDefaultDSN = "root:testroot@tcp(127.0.0.1:13307)"

MariaDBDefaultDSN is the base DSN used when BINTRAIL_TEST_MARIADB_DSN is not set. It assumes a local Docker MariaDB container on port 13307 with root:testroot (distinct from the MySQL index container on 13306).

Functions

func BaseDSN

func BaseDSN() string

BaseDSN returns the base DSN (without database name) from the environment or the default. It always includes parseTime=true.

func CreateTestDB

func CreateTestDB(t *testing.T) (*sql.DB, string)

CreateTestDB creates a unique database for the calling test, returning a connected *sql.DB, the database name, and a cleanup function that drops the database. The cleanup function is also registered via t.Cleanup.

func CreateTestMariaDB

func CreateTestMariaDB(t *testing.T) (*sql.DB, string)

CreateTestMariaDB creates a unique database on the MariaDB SOURCE server, returning a connected *sql.DB, the database name, and registering cleanup. It mirrors CreateTestDB but targets the MariaDB container (13307).

func InitIndexTables

func InitIndexTables(t *testing.T, db *sql.DB)

InitIndexTables creates all index tables in the given database. This mirrors `bintrail init` without requiring the CLI binary.

func InsertEvent

func InsertEvent(t *testing.T, db *sql.DB,
	binlogFile string, startPos, endPos uint64,
	ts string, gtid *string,
	schema, table string, eventType uint8,
	pkValues string,
	changedCols, rowBefore, rowAfter []byte,
)

InsertEvent inserts a single event into binlog_events using raw SQL. Useful for setting up test data without going through the indexer.

func InsertSnapshot

func InsertSnapshot(t *testing.T, db *sql.DB,
	snapshotID int, snapshotTime, schema, table, column string,
	ordinal int, columnKey, dataType, isNullable string,
)

InsertSnapshot inserts a single snapshot row into schema_snapshots.

func IntegrationDSN

func IntegrationDSN(dbName string) string

IntegrationDSN returns a full DSN with the given database name appended.

func MariaDBBaseDSN

func MariaDBBaseDSN() string

MariaDBBaseDSN returns the base MariaDB source DSN (without database name) from the environment or the default. It always includes parseTime=true.

func MariaDBRequired

func MariaDBRequired() bool

MariaDBRequired reports whether MariaDB integration tests must RUN (and fail rather than skip when MariaDB is unavailable or a setup step no-ops). The dedicated CI job sets BINTRAIL_REQUIRE_MARIADB=1, where a MariaDB source is guaranteed present — so a silent skip there would be a false green that hides a real regression in the headline capture path. Unset on developer machines and the MySQL-only matrix job, where graceful skipping is the right behavior.

func MustExec

func MustExec(t *testing.T, db *sql.DB, query string, args ...any)

MustExec executes a query or calls t.Fatal on error.

func MySQLRequired

func MySQLRequired() bool

MySQLRequired reports whether MySQL integration tests must RUN (and fail rather than skip) when the server is unreachable. The dedicated 8.0/8.4 integration matrix jobs set BINTRAIL_REQUIRE_MYSQL=1, where a MySQL server is guaranteed present — so a silent skip there would be a false green that hides a real regression in the flagship capture->index->query->recover pipeline. Unset on developer machines, where graceful skipping is right. Mirrors MariaDBRequired / PostgresRequired.

func PostgresDSN

func PostgresDSN() string

PostgresDSN returns the test PostgreSQL DSN from BINTRAIL_TEST_PG_DSN, or "". A suitable target is a local PostgreSQL with wal_level=logical and a role that has REPLICATION (e.g. the spike's container: postgres://postgres:testpg@localhost:15533/pgtest).

func PostgresRequired

func PostgresRequired() bool

PostgresRequired reports whether PostgreSQL integration tests must RUN (and fail rather than skip) when no DSN is configured. The dedicated CI job (integration-postgres-source) sets BINTRAIL_REQUIRE_POSTGRES=1, where a live PostgreSQL source is guaranteed — so a missing DSN there is a misconfiguration to surface loudly, not a green-via-skip. The MySQL integration matrix leaves it unset, so PG tests skip cleanly there. Mirrors MariaDBRequired.

func RequiredPGExtensions

func RequiredPGExtensions() map[string]bool

RequiredPGExtensions returns the set of PostgreSQL extensions the extension-type integration tests must exercise, from the comma-separated BINTRAIL_REQUIRE_PGEXT (e.g. "postgis" or "vector"). When an extension named here cannot be created in the test database, the extension-type round-trip test FAILS instead of skipping its cases: the dedicated CI cells run images that guarantee the extension (postgis/postgis, pgvector/pgvector), so an unavailable extension there is a misconfiguration to surface loudly, not a green-via-skip. Cells without the env var (the plain postgres matrix) skip the extension cases cleanly. Mirrors PostgresRequired / MariaDBRequired.

func SetupPartitionedTable

func SetupPartitionedTable(t *testing.T, db *sql.DB, dbName string, hours []time.Time)

SetupPartitionedTable reorganizes binlog_events' p_future into hourly partitions covering the given hours (plus a fresh p_future catch-all), so a test can insert data into specific hours and then rotate them away.

Kept dependency-free on purpose — it inlines the "p_2006010215" partition name format rather than calling indexer.PartitionName — so testutil stays a leaf. internal/rotation's own tests import testutil; a testutil→rotation edge (or testutil→indexer, whose tests import testutil) would create an import cycle. Shared by the rotation, archive, and reconstruct integration tests.

func SkipIfNoMariaDB

func SkipIfNoMariaDB(t *testing.T)

SkipIfNoMariaDB pings the MariaDB source server and skips (or fails, when MariaDBRequired()) if unreachable, so MariaDB tests degrade gracefully when only the MySQL container is running but cannot false-green in the CI job that guarantees a MariaDB source.

func SkipIfNoMySQL

func SkipIfNoMySQL(t *testing.T)

SkipIfNoMySQL pings the MySQL server and calls t.Skip if unreachable, or t.Fatal when MySQLRequired() — so a dial/ping failure never silently passes as green in the CI job that guarantees a live MySQL server. This provides graceful degradation when no Docker container is running.

func SkipIfNoPostgres

func SkipIfNoPostgres(t *testing.T) string

SkipIfNoPostgres skips the test unless BINTRAIL_TEST_PG_DSN is set, and returns the DSN. It is presence-only (no driver dependency) on purpose: the MySQL-based CI integration jobs run `go test -tags integration ./...` WITHOUT setting it, so PostgreSQL integration tests must skip cleanly there rather than fail or hang — the live Postgres CI cell is integration-postgres-source (#534's matrix), which sets BINTRAIL_REQUIRE_POSTGRES=1 so a missing DSN there fails loud instead of passing as green-via-skip. Mirrors SkipIfNoMySQL / SkipOrFailMariaDB.

func SkipOrFailMariaDB

func SkipOrFailMariaDB(t *testing.T, format string, args ...any)

SkipOrFailMariaDB skips the test, or fails it when MariaDBRequired() — so a MariaDB step that can't run never silently passes as green in CI.

func SnapshotDSN

func SnapshotDSN(dbName string) string

SnapshotDSN returns a DSN string for the given database name, suitable for passing to commands that accept --index-dsn.