IF Commons GitHub

AnyFS SQL: the port

0003Active

0003-sql-port · owner if · domain commons

Requirements

FR-001checkpassing

The port MUST give query (the rows a statement returns), exec, transaction (all or none, the function's throw undoing it) and close, with a value of exactly null, a wide integer, a number, a text or bytes, and a row by the name of its column.

Enforced (check): .github: cd commons/anyfs-sql && bun run verify — suite/port.test.ts

Proved by: anyfs-sql/suite/port.test.ts

Written in: anyfs-sql/src/governance/values.ts

Tests: passed: suite/port.test.ts the port has query, exec, transaction and close, and a transaction that throws leaves noth

FR-002checkpassing

The builder MUST write a name as the dialect's identifier writes it (a keyword quoted), a parameter as the dialect's placeholder writes it in the order the parameters were added, and MUST give the bytes of an object to DuckDB as hex (unhex, and hex on the way back), so that a value is never part of the text.

Enforced (check): .github: cd commons/anyfs-sql && bun run verify — suite/port.test.ts

Proved by: anyfs-sql/suite/port.test.ts

Written in: anyfs-sql/src/physical/sql.ts

Tests: passed: suite/port.test.ts the builder writes names as the dialect writes them and parameters in the order they were

FR-003checkpassing

A gate MUST run what goes through it one at a time in the order it came, and two connections to one file in one process MUST share one.

Enforced (check): .github: cd commons/anyfs-sql && bun run verify — suite/port.test.ts

Proved by: anyfs-sql/suite/port.test.ts

Written in: anyfs-sql/src/physical/adapters/common.ts

Tests: passed: suite/port.test.ts a gate runs what goes through it one at a time in the order it came

FR-004checkpassing

A value a driver gives MUST be read into a value of the port: a buffer, an array buffer or an array of bytes into bytes (copied), a boolean into 1 or 0, a date into its ISO text, and an object with no prototype into a row.

Enforced (check): .github: cd commons/anyfs-sql && bun run verify — suite/port.test.ts

Proved by: anyfs-sql/suite/port.test.ts

Written in: anyfs-sql/src/physical/adapters/common.ts

Tests: passed: suite/port.test.ts a driver's values are read as the port's: buffers, array buffers and arrays of bytes into

FR-005checkpassing

The port of SQLite MUST open a write as BEGIN IMMEDIATE with a busy timeout, open a file in write-ahead mode, and be had from a file opened by the module of the runtime that is running (bun:sqlite or node:sqlite), typed by the shape both have.

Enforced (check): .github: cd commons/anyfs-sql && bun run verify — suite/port.test.ts

Proved by: anyfs-sql/suite/port.test.ts

Written in: anyfs-sql/src/physical/adapters/sqlite.ts

Tests: passed: suite/port.test.ts the port of SQLite runs a write as BEGIN IMMEDIATE, so a second connection waits for the f

FR-006checkpassing

The port of a libSQL client (Turso, a libSQL file, a server of sqld) MUST run a transaction through the client's transaction('write'), commit it or roll it back, and give blobs that arrive as array buffers as bytes, typed by the client's shape.

Enforced (check): .github: cd commons/anyfs-sql && bun run verify — suite/port.test.ts

Proved by: anyfs-sql/suite/port.test.ts

Written in: anyfs-sql/src/physical/adapters/libsql.ts

Tests: passed: suite/port.test.ts the port of a libSQL client (a FAKE of the client's shape over a real SQLite) runs stateme

FR-007checkpassing

The port of PGlite MUST run a transaction through PGlite's own, so that a statement outside it waits for it.

Enforced (check): .github: cd commons/anyfs-sql && bun run verify — suite/port.test.ts

Proved by: anyfs-sql/suite/port.test.ts

Written in: anyfs-sql/src/physical/adapters/pglite.ts

Tests: passed: suite/port.test.ts the port of PGlite (PostgreSQL itself) runs a transaction through PGlite's own and undoes

FR-008checkpassing

The port of pg MUST take a connection of a pool for each transaction and give it back, or run one transaction at a time on a client, read a BIGINT that arrives as text and a buffer as bytes, and never take credentials from a place.

Enforced (check): .github: cd commons/anyfs-sql && bun run verify — suite/port.test.ts

Proved by: anyfs-sql/suite/port.test.ts

Written in: anyfs-sql/src/physical/adapters/pg.ts

Tests: passed: suite/port.test.ts the port of a `pg` pool (a FAKE of the pool's shape over PostgreSQL in PGlite) takes a con

FR-009checkpassing

The port of DuckDB MUST run a transaction as BEGIN TRANSACTION and COMMIT, undone with ROLLBACK, one at a time on a connection.

Enforced (check): .github: cd commons/anyfs-sql && bun run verify — suite/port.test.ts

Proved by: anyfs-sql/suite/port.test.ts

Written in: anyfs-sql/src/physical/adapters/duckdb.ts

Tests: passed: suite/port.test.ts the port of DuckDB runs a transaction as BEGIN and COMMIT, undoes a throw with ROLLBACK an

FR-010checkno test run

Each port of a driver (pg, PGlite, DuckDB) MUST say which package to install where it is handed no connection of that driver: the driver is an optional peer of the package that holds the library and no source of commons imports it (commons 0036-distribution FR-023, FR-033), so a port that is given nothing, or something that has not the methods it uses, MUST throw a TypeError that names the driver, the range of versions and that the caller installs it and hands the connection over.

Enforced (check): .github: cd commons/anyfs-sql && bun run verify — suite/port.test.ts

Proved by: anyfs-sql/suite/port.test.ts

Acceptance scenarios

  1. Given a statement whose parameter holds a quote, a percent sign and a backslash, When it is built, Then the text holds only a placeholder, per FR-002.
  2. Given two transactions on one port, When they run at once, Then one ends before the other starts, per FR-003.
  3. Given a transaction that throws, When it ends, Then none of its changes is there, per FR-001.

Out of scope

  • A pool of connections for SQLite or DuckDB.

Edge cases

  • A driver that gives a number as text is read by the store (FR-004 of 0005).

Assumptions

Open questions

  • None.

Key entities

  • Port, Dialect, Layout, Revision.

Success criteria

SC-001success criterion

Every behaviour is tested on the real engines in memory or in temporary folders, with no network and no real time.

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

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