IF Commons GitHub

sql assertions

0049Active

0049-sql-assertions · owner if · domain data

Requirements

FR-001checkpassing

Structural assertions MUST be made from the state a schema has, for every dialect, and run by a driver.

Enforced (check): .github: cd commons/data && bun run verify — suite/assertions.test.ts: the structure a schema's state says is held on each dialect, by a driver and by one query that returns TAP lines, and what a database lacks or has otherwise is a failing line that names it

Proved by: data/suite/assertions.test.ts

Written in: data/sql/extensions/assertions/assert.ts, data/sql/extensions/assertions/mod.ts

Tests: passed: suite/assertions.test.ts the structure a schema's state says is held on each dialect, by a driver and by one query

FR-002checkpassing

A difference between a database and the state MUST be a failing line that names what is wrong.

Enforced (check): .github: cd commons/data && bun run verify — suite/assertions.test.ts: the structure a schema's state says is held on each dialect, by a driver and by one query that returns TAP lines, and what a database lacks or has otherwise is a failing line that names it

Proved by: data/suite/assertions.test.ts

Written in: data/sql/extensions/assertions/assert.ts

Tests: passed: suite/assertions.test.ts the structure a schema's state says is held on each dialect, by a driver and by one query

FR-003checkpassing

Assertions MUST be written as pgTAP scripts and run by the pgTAP extension.

Enforced (check): .github: cd commons/data && bun run verify — suite/assertions.test.ts: rows are held in any order and compared as sets, a statement that must fail passes only where it is refused and changes nothing where it is not, and the query that gives TAP says a statement that must fail was skipped

Proved by: data/suite/assertions.test.ts

Written in: data/sql/extensions/assertions/assert.ts

Tests: passed: suite/assertions.test.ts rows are held in any order and compared as sets, a statement that must fail passes only wh

FR-004checkpassing

TAP version 14 MUST be values, text and readable back.

Enforced (check): .github: cd commons/data && bun run verify — suite/assertions.test.ts: TAP is values that are written as TAP version 14 and read back, with a skipped test counted apart from a failure

Proved by: data/suite/assertions.test.ts

Written in: data/sql/extensions/assertions/tap.ts

Tests: passed: suite/assertions.test.ts TAP is values that are written as TAP version 14 and read back, with a skipped test counte

Cited by: Data, sql/extensions/assertions/tap

FR-005checkpassing

rows and fails assertions of one's own MUST run in every dialect.

Enforced (check): .github: cd commons/data && bun run verify — suite/assertions.test.ts: the assertions are a pgTAP script that the pgTAP extension runs in PostgreSQL, giving the same results as the query and the driver

Proved by: data/suite/assertions.test.ts

Written in: data/sql/extensions/assertions/assert.ts

Tests: passed: suite/assertions.test.ts the assertions are a pgTAP script that the pgTAP extension runs in PostgreSQL, giving the

Out of scope

  • A pgTAP server beyond PGlite's.

Edge cases

  • A dialect without the feature, an empty list, or a name that needs quoting: each is an error value or is quoted, never a silent omission, per FR-001.

Assumptions

  • The engines of the tests are SQLite, DuckDB and PGlite (PostgreSQL), in process.

Open questions

  • None.

Key entities

  • Assertion - one thing held to be true of a database, run as pgTAP, as a TAP query or by a driver.

Success criteria

SC-001success criterion

Each requirement above is proved by a test that runs on real engines, and bun run verify is green.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

Data, sql/extensions/assertions/assert, sql/extensions/assertions/tap

Titles, headings, exports, tables, columns and requirements. Esc closes.