sqltest

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package sqltest is the SQL harness that runs a module's store suite on each dialect: RunModule hands the suite fresh databases, on SQLite in memory and in a file and, when asked, on PostgreSQL, each migrated with the module's streams alone. It also starts the one PostgreSQL server that a test process shares, holds the statements and checks that the SQL fault tests share, and describes a database's schema for the golden files.

Role

platform layer, test support (platform/sql): the SQL harness that runs a module's store suite on each dialect, so a module adds one test file to get its SQLite runs, and its PostgreSQL run when it asks for one. Test files in any module may import it (dependency rule 1); production code never does. It imports the dialect layer, the SQLite and PostgreSQL drivers, platform/crypt, testcontainers' PostgreSQL module, pkg/containertest and go-cmp.

Inputs

  • For RunModule: the modules whose streams make a store's schema, in the canonical module order; open, which builds the module's store over a dialect.Store; the suite; and the options WithPostgres and WithKeyring.
  • For OpenSQLite: the modules. For Reset: a database, its dialect and the modules whose tables to empty. For Schema: a database and its dialect's name; for SchemaGolden, also the golden file.
  • ARTIFACTWEAVE_TEST_POSTGRES_DSN, a PostgreSQL server to use in place of a container.
  • Driving: the module store suites from STO-12 to STO-18, and their fault tests; the composite store's suites in app, which call PostgresDSN, Schema and SchemaGolden, and reach Reset through app/storetest's Reset over the composite's module list.

Outputs

  • RunModule, with Option, WithPostgres and WithKeyring: the subtests memory, file and, when asked for, postgres, in each of which the suite gets a newStore that opens a fresh store.
  • OpenSQLite: one fresh in-memory store.
  • PostgresDSN, the DSN of the shared server, and ScratchDSN, a DSN whose connections start in an empty schema of their own.
  • Reset: the tables of the given modules emptied.
  • Exec, Fails, Err, Err3, FailTrigger and DropTable: the fault-test helpers.
  • Schema, a description of every table, index, constraint and sequence and the row count of every table that holds rows, with ErrUnknownDialect; SchemaGolden, which compares it with a golden file, rewrites the file when asked, and proves that an added table changes the description.

Invariants

  • A test process starts at most one PostgreSQL container: PostgresDSN starts it on its first call, and every PostgreSQL run of the process shares it. The image is pinned to postgres:17-alpine so that a PostgreSQL release cannot change behaviour under the suites; a bump is deliberate.
  • Unless ARTIFACTWEAVE_TEST_POSTGRES_DSN names a server, PostgresDSN skips the calling test in a -short run and where no Docker engine that runs Linux containers answers, so the suites run everywhere and their PostgreSQL half runs in the Linux CI jobs (decision 0015).
  • Every store that RunModule or OpenSQLite hands out has a database of its own, holding only the history and the tables of its modules' streams: a new SQLite database in memory or in a file of the test's temporary directory, or, on PostgreSQL, a scratch schema of its own on the shared server. A row written through one store never reaches another; the composite tables that other tests of the process keep in the server's public schema are left alone; and test processes that share a server through ARTIFACTWEAVE_TEST_POSTGRES_DSN do not meet in it.
  • A store opens as the composite store opens: a ping, every stream migrated, the pool wrapped with the keyring, then each module's AfterMigrate in module order. The keyring is the one the composite store's runs seal with, unless WithKeyring replaces it.
  • A store is closed, and its scratch schema dropped, when the test that asked for it ends. A database that cannot be opened, migrated or dropped, or a hook that fails, fails that test.
  • The fault statements are SQLite's: a PostgreSQL trigger runs a separate trigger function, so the fault tests that use FailTrigger run on SQLite.
  • Schema leaves out schema_migrations, whose shape the module streams change, and everything that differs between runs or hosts (object ids, SQLite root pages, the database's default collation), so two databases built by the same streams describe as the same string.

References

  • Decision 0015: docs/research/decisions/0015-testing-and-acceptance.md (one contract suite for every backend; PostgreSQL through testcontainers, skipped where Docker cannot run Linux containers).
  • Decision 0044: docs/research/decisions/0044-modular-monolith-migration.md ("Persistence": module suites run through RunModule, and the PostgreSQL composite runs stay in the composite's packages in app; "Names the migration introduces"; "Dependency rules").
  • Target layout: docs/research/architecture-options/5-modular-monolith.md, line 586 (platform/sql/sqltest: RunModule on each dialect), lines 631 to 633 (RunModule runs any module's store suite against every dialect, so a module adds one test file) and line 1044 (the mapping row).
  • Plan: docs/implementation/plan.md#p2-stores and #p9d-modular-monolith-migration, epic STO (https://github.com/weaveplatform/artifactweave/issues/939).
  • https://github.com/weaveplatform/artifactweave/issues/996

Status

Implemented P2: the PostgreSQL server that the contract runs share, and Reset (pull request 3). Moved here in P9d: RunModule, OpenSQLite, ScratchDSN, Reset over any modules and the fault-test helpers (issue 996), and Schema and SchemaGolden (issues 960 and 1098).

Testing

  • TestAccRunModule, TestAccRunModuleWithoutPostgres, TestAccRunModuleKeyrings and TestAccRunModuleRunsAfterMigrate run RunModule over modules of one table each, and TestAccOpenSQLite and TestAccReset the other two entry points.
  • TestAccHarnessFailsTheTest provokes each failure in a child run of the test binary and checks that it fails the test with its message.
  • TestAccPostgresDSN and TestAccScratchDSN run on the shared server and skip with it.
  • TestUnitFaultStatements, TestUnitErrKeepsTheError and TestAccFaultHelpers cover the fault-test helpers.
  • The composite store's PostgreSQL runs, TestAccContract and TestAccKeyRotation among them, use PostgresDSN and Reset.
  • Schema and SchemaGolden are exercised by the composite store's TestAccSchemaGolden on SQLite and PostgreSQL, TestAccMigrationsUpDownUp and TestAccStreamsMigrateAlone, against the schema goldens beside the composite's dialect packages.

Index

Constants

This section is empty.

Variables

View Source
var ErrUnknownDialect = errors.New("sqltest: unknown dialect")

ErrUnknownDialect reports a dialect name that Schema cannot describe.

Functions

func DropTable

func DropTable(table string) string

DropTable returns the statement that drops table, so the statements that touch it fail.

func Err

func Err[V any](_ V, err error) error

Err returns the error of a call that returns a value and an error, so the call can stand as an entry of the map that Fails takes.

func Err3

func Err3[V any](_ V, _ string, err error) error

Err3 returns the error of a call that returns a value, a string and an error, the shape of a paged list (the page, the next cursor, the error), so the call can stand as an entry of the map that Fails takes.

func Exec

func Exec(t *testing.T, db *sql.DB, stmts ...string)

Exec runs each statement on db, outside any transaction, and fails t at the first that fails, naming the statement. Fault tests use it to change a database behind its store's back: a trigger that makes a write fail, a dropped table, a value the column type forbids.

func FailTrigger

func FailTrigger(event, table string) string

FailTrigger returns the statement that creates a trigger making every row-level event (INSERT, UPDATE or DELETE) on table abort with "injected", so a test reaches the statement after a successful one. It is SQLite's trigger syntax: PostgreSQL has no trigger body in the statement, only a trigger function, so fault tests that use it run on SQLite.

func Fails

func Fails(t *testing.T, calls map[string]error)

Fails marks t failed, and goes on, for each entry of calls whose error is nil, reporting it by its key as "<key> succeeded". A fault test names every call that the injected fault must make fail and checks them in one go.

func OpenSQLite

func OpenSQLite(t *testing.T, mods ...dialect.Module) *dialect.Store

OpenSQLite returns a fresh in-memory SQLite store migrated with mods and sealed with the test keyring, with each module's AfterMigrate run as RunModule runs it; t.Cleanup closes it. A database that cannot be migrated, or a hook that fails, fails t.

func PostgresDSN

func PostgresDSN(t *testing.T) string

PostgresDSN returns the DSN of the PostgreSQL server that every test of the process shares: ARTIFACTWEAVE_TEST_POSTGRES_DSN when it is set, or else that of a postgres:17-alpine container, database artifactweave with user and password aw, which the first call starts and later calls reuse. Without the variable it skips t in a -short run and where Docker cannot run Linux containers, and it fails t when the container does not start; a failed start is not retried, so every later call fails too. Tables a test creates in the server's public schema are seen by every other test of the process; ScratchDSN gives a test a schema of its own.

func Reset

func Reset(t *testing.T, db *sql.DB, d dialect.Dialect, mods []dialect.Module)

Reset rolls every stream of mods back to zero and migrates them again, leaving their tables empty; tables of other streams are untouched. Running it before each test also exercises every down migration of mods.

func RunModule

func RunModule[S any](
	t *testing.T,
	mods []dialect.Module,
	open func(*dialect.Store) S,
	suite func(t *testing.T, newStore func(*testing.T) S),
	opts ...Option,
)

RunModule runs suite in the subtests "memory" and "file", SQLite in memory and in a file of the test's temporary directory, and, with WithPostgres, "postgres". In each, newStore returns open applied to a fresh database that holds only the tables of mods: every call opens a database of its own, migrates every stream of mods, wraps it in a store sealed with the test keyring or WithKeyring's, and runs each module's AfterMigrate in the order of mods, as the composite store's open does. mods are in the canonical module order, as dialect.Migrate takes them.

On PostgreSQL every store gets a scratch schema of its own (ScratchDSN) on the server PostgresDSN returns, so no store sees another's rows or the tables that other tests keep in the server's public schema, even when test processes share one server; the subtest skips where PostgresDSN skips. A store is closed, and its schema dropped, when the test that called newStore ends. A database that cannot be opened or migrated, or a hook that fails, fails that test.

func Schema

func Schema(ctx context.Context, db *sql.DB, dialect string) (string, error)

Schema returns a normalised, deterministic description of every table, index, constraint and sequence in db, plus the row count of every table that holds rows. It leaves out every catalog object of schema_migrations, whose shape the per-module migration streams change.

dialect is the Name of a dialect.Dialect, "sqlite" or "postgres"; any other name returns ErrUnknownDialect. The description holds nothing that differs between runs or hosts, such as object ids, SQLite root pages or the database's default collation, so two databases built by the same schema compare equal as strings, line by line.

func SchemaGolden

func SchemaGolden(t *testing.T, db *sql.DB, dialect, path string, update bool)

SchemaGolden compares Schema(db, dialect) with the golden file at path and reports a mismatch as a line diff; update rewrites the file from db first. The golden pins the schema that the module streams together build on a fresh database, so a change to any stream shows as a diff of the golden that review has to accept.

A planned subtest then proves the comparison can fail: it adds a scratch table and requires the description to differ from the golden. The table is dropped when the subtest ends, because one PostgreSQL server serves every test of the binary.

func ScratchDSN

func ScratchDSN(t *testing.T, dsn string) string

ScratchDSN creates an empty schema of its own on the server that dsn names and returns dsn with that schema as its search_path. pgx passes an unknown DSN parameter such as search_path to the server as a run-time parameter, so every connection of a pool opened with the result starts in the schema: unqualified tables are created and read there, and current_schema(), which the migrator's legacy-history check reads, names it. dsn is a postgres:// or postgresql:// URL or key=value pairs. The schema is dropped when t ends, after the cleanups registered later, such as closing a pool opened with the result, because one server serves every test of the process and may serve other processes too.

Types

type Option

type Option func(*options)

Option changes how RunModule runs a suite; WithPostgres and WithKeyring return one.

func WithKeyring

func WithKeyring(k *crypt.Keyring) Option

WithKeyring makes RunModule seal its stores with k in place of the test keyring. A nil k opens them without a keyring: Seal then stores values as given, and Unseal fails on a sealed value with dialect.ErrNoKeyring.

func WithPostgres

func WithPostgres() Option

WithPostgres adds the "postgres" subtest to RunModule. PostgreSQL is asked for rather than run by default because module suites run on SQLite and the PostgreSQL runs stay with the composite store (decision 0044, "Persistence").

Jump to

Keyboard shortcuts

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