|
|
@@ -0,0 +1,178 @@
|
|
|
+# SQLite binding — test inventory
|
|
|
+
|
|
|
+Date: 2026-10-26
|
|
|
+
|
|
|
+This note records which existing tests are useful for hardening the V3
|
|
|
+SQLite binding under `bindings/sqlite3`, and which APIs they would drive.
|
|
|
+
|
|
|
+## Sources scanned
|
|
|
+
|
|
|
+| Source | Count | Notes |
|
|
|
+|---|---:|---|
|
|
|
+| `bindings/sqlite3/tests` | 8 | Current V3 tests: smoke, prepared, scalar, errors, BLOB, connection, callback, hooks |
|
|
|
+| sibling `m2SQLITE/tests` | 7 | Original GNU Modula-2 binding tests; closest existing coverage |
|
|
|
+| sibling `m2SQLITE/sqlite-master/test` | 1,195 `.test` files | Upstream SQLite TCL regression suite; useful as a specification |
|
|
|
+| `compiler/tests` | 806 files | Compiler/ABI tests; not SQLite-specific, but several guard binding prerequisites |
|
|
|
+
|
|
|
+The upstream SQLite tests are TCL-based and cannot run directly against
|
|
|
+the V3 binding. Port individual `do_test` scenarios, not the test
|
|
|
+harness.
|
|
|
+
|
|
|
+## Current V3 binding tests
|
|
|
+
|
|
|
+- `SQLiteSmoke.mod`
|
|
|
+- `SQLitePrepared.mod`
|
|
|
+- `SQLiteScalar.mod`
|
|
|
+- `SQLiteErrors.mod`
|
|
|
+- `SQLiteBlob.mod`
|
|
|
+- `SQLiteConnection.mod`
|
|
|
+- `SQLiteCallback.mod`
|
|
|
+- `SQLiteHooks.mod`
|
|
|
+
|
|
|
+## Original m2SQLITE tests
|
|
|
+
|
|
|
+| Test | Useful coverage | Status in V3 binding |
|
|
|
+|---|---|---|
|
|
|
+| `test_prepare.mod` | `bind_parameter_count/index`, named parameters, 64-bit bind, scalar round trip | **High priority.** Missing parameter-introspection APIs |
|
|
|
+| `test_func.mod` | scalar/aggregate UDFs, auxdata, numeric type, `result_value`, 64-bit text/blob, zeroblob, error paths | Missing several callback/result APIs |
|
|
|
+| `test_blob.mod` | read-only BLOB write error, reopen, backup API, backup to file | BLOB happy path covered; read-only/error and backup not covered |
|
|
|
+| `test_codes.mod` | extended constraint codes (unique/not-null/PK/FK), `get_table` | Only PK/unique constants; missing not-null/FK constants and `get_table` |
|
|
|
+| `test_exec.mod` | exec, change counters, rowid, error capture | Already covered by current V3 tests |
|
|
|
+| `test_open.mod` | `open` / `open_v2` / close and `errcode` | Already covered by current V3 tests |
|
|
|
+| `test_version.mod` | `sqlite3_libversion*` | Missing version APIs |
|
|
|
+
|
|
|
+## Upstream SQLite tests worth mining
|
|
|
+
|
|
|
+### Highest priority
|
|
|
+
|
|
|
+| File | Interesting cases | What it drives |
|
|
|
+|---|---|---|
|
|
|
+| `bind.test` | `bind-1.*` named params/unbound NULL/reset; `bind-9.*` high parameter numbers; `bind-10.*` parameter index/name; 32/64/double/NULL/text/UTF-16/clear sections | `sqlite3_bind_parameter_count/name/index`; reset/reuse; long 64-bit values |
|
|
|
+| `incrblob.test` | sections `incrblob-3.*` read-only write, `4.*` bad row/table/column/type opens, `7.*` handle invalidation | BLOB error paths and boundary behavior |
|
|
|
+| `types.test`, `types2.test`, `types3.test` | storage classes, affinity, integer/real/text conversions | `column_type`, numeric columns, bound values |
|
|
|
+| `null.test`, `nulls1.test`, `nulls2.test` | NULL in expressions, comparisons, result types | `bind_null`, `column_type`, `value_type` |
|
|
|
+| `auth.test` | deny at prepare, `SQLITE_IGNORE` for reads, action arguments, authorizer replacement | authorizer arguments and return semantics |
|
|
|
+| `busy.test`, `busy2.test` | lock contention, busy handler invocation, timeout | actual busy-handler behavior (current test only registers one) |
|
|
|
+| `progress.test` | callback count, nonzero return aborts query, nested query from callback | progress callback return handling |
|
|
|
+| `trace.test`, `trace2.test`, `trace3.test` | statement/profile/row/close masks and callback arguments | trace masks beyond `SQLiteTraceStmt` |
|
|
|
+
|
|
|
+### Medium priority
|
|
|
+
|
|
|
+| File | Interesting cases | What it drives |
|
|
|
+|---|---|---|
|
|
|
+| `func.test` … `func9.test` | function arg counts, NULLs, destructors, auxdata, aggregates, result types | aggregate/auxdata APIs, more result writers |
|
|
|
+| `errors`/`errmsg.test` | error text and error offsets | `sqlite3_error_offset`, error-message behavior |
|
|
|
+| `fkey1.test` … `fkey9.test` | foreign-key and not-null constraint codes | missing extended-code constants |
|
|
|
+| `openv2.test`, `uri.test`, `uri2.test` | open flags, URI filenames, read-only opens | `open_v2` flags and URI behavior |
|
|
|
+| `limit.test`, `limit2.test` | `sqlite3_limit` | connection limits |
|
|
|
+| `trans.test`, `trans2.test`, `trans3.test`, `rollback.test` | transaction boundaries and hooks | commit/rollback hook ordering |
|
|
|
+| `backup.test`, `backup2.test`, `backup4.test`, `backup5.test` | online backup and incremental backup | backup API |
|
|
|
+| `attach.test`, `attach2.test` | multiple attached databases | BLOB `zDb` values, future helpers |
|
|
|
+
|
|
|
+### Later / not useful yet
|
|
|
+
|
|
|
+- `malloc*`, `*fault*`, `*ioerr*`: SQLite fault-injection harness.
|
|
|
+- `wal*`, `shared*`, `lock*`: pager/WAL/concurrency internals.
|
|
|
+- `window*`, `collat*`: APIs not exposed by the V3 binding yet.
|
|
|
+- `select*`, `expr*`, `alter*`, `vacuum*`: SQL engine behavior, not binding behavior.
|
|
|
+- `session`, `rbu`, `rtree`, `fts`: extension APIs.
|
|
|
+
|
|
|
+## Compiler tests that matter as binding prerequisites
|
|
|
+
|
|
|
+These are not SQLite tests, but they exercise compiler/ABI features the
|
|
|
+binding relies on and should remain in the main gate:
|
|
|
+
|
|
|
+- `compiler/tests/t_callback.mod` — top-level C callbacks
|
|
|
+- `compiler/tests/cabi_scalars_prog.mod` — scalar C ABI
|
|
|
+- `compiler/tests/cstr_prog.mod` — C strings
|
|
|
+- `compiler/tests/cstruct_layout_prog.mod` — C record layout
|
|
|
+- `compiler/tests/t_open_row_adr.mod` — `ADR` behavior
|
|
|
+- `compiler/tests/t_libc2.mod` — raw C buffers
|
|
|
+- `compiler/tests/t_byte.mod`, `t_real.mod`, `t_long.mod` — byte/REAL/LONGINT widths
|
|
|
+
|
|
|
+## Recommended next test additions
|
|
|
+
|
|
|
+### 1. `SQLiteParams.mod` — best next test
|
|
|
+
|
|
|
+Port from `m2SQLITE/tests/test_prepare.mod` and `bind.test`.
|
|
|
+
|
|
|
+Add APIs:
|
|
|
+
|
|
|
+- `sqlite3_bind_parameter_count`
|
|
|
+- `sqlite3_bind_parameter_name`
|
|
|
+- `sqlite3_bind_parameter_index`
|
|
|
+
|
|
|
+Cases:
|
|
|
+
|
|
|
+- anonymous `?` parameters
|
|
|
+- named `:name`, `@name`, `$name` parameters
|
|
|
+- repeated named parameters
|
|
|
+- unbound parameters read back as NULL
|
|
|
+- `reset` and rebind reuse
|
|
|
+- `clear_bindings`
|
|
|
+- `LONGINT` value such as `9000000001`
|
|
|
+
|
|
|
+### 2. Extend `SQLiteBlob.mod`
|
|
|
+
|
|
|
+Port from `incrblob-3.*`, `incrblob-4.*` and `test_blob.mod`.
|
|
|
+
|
|
|
+Cases:
|
|
|
+
|
|
|
+- write to a read-only handle returns `SQLiteReadOnly`
|
|
|
+- close after a read-only write error
|
|
|
+- open nonexistent row/table/column
|
|
|
+- open integer/real/NULL column as BLOB
|
|
|
+- read/write outside bounds
|
|
|
+- reopen behavior
|
|
|
+- handle invalidation after a write to the same table
|
|
|
+
|
|
|
+### 3. Extend `SQLiteHooks.mod`
|
|
|
+
|
|
|
+Port from `progress.test` and `auth.test`.
|
|
|
+
|
|
|
+Cases:
|
|
|
+
|
|
|
+- progress callback returns nonzero and aborts the query
|
|
|
+- progress callback with `nOps = 0` disabled
|
|
|
+- authorizer `SQLiteAuthIgnore` on `SQLITE_READ` returns NULL
|
|
|
+- authorizer action arguments
|
|
|
+- busy handler actually invoked by a second connection
|
|
|
+
|
|
|
+### 4. Extended-code tests
|
|
|
+
|
|
|
+Port from `m2SQLITE/tests/test_codes.mod`.
|
|
|
+
|
|
|
+Add constants and tests for:
|
|
|
+
|
|
|
+- `SQLiteConstraintNotNull` = 1299
|
|
|
+- `SQLiteConstraintForeignKey` = 787
|
|
|
+- `SQLiteConstraintCheck` = 275
|
|
|
+- optionally trigger, rowid and datatype constraints
|
|
|
+
|
|
|
+### 5. Later slices
|
|
|
+
|
|
|
+- aggregate functions + auxdata (`test_func.mod`, `func*.test`)
|
|
|
+- backup API (`test_blob.mod`, `backup*.test`)
|
|
|
+- version/sourceid/threadsafe (`test_version.mod`)
|
|
|
+- `sqlite3_get_table` / `free_table`
|
|
|
+- statement metadata (`sqlite3_sql`, `expanded_sql`, `stmt_readonly`, `stmt_busy`)
|
|
|
+- limits, autocommit and error offsets
|
|
|
+
|
|
|
+## Related session note
|
|
|
+
|
|
|
+See `docs/session-2026-10-26-sqlite-binding.md` for the binding work
|
|
|
+completed in this session and the current verification state.
|
|
|
+
|
|
|
+## Porting caveats
|
|
|
+
|
|
|
+- Replace m2SQLITE's `libc.printf`/`HALT` style with the V3 test convention:
|
|
|
+ set `ExitCode := 42` on success.
|
|
|
+- m2SQLITE's `SQLiteUtils` helpers do not exist in the V3 binding; call
|
|
|
+ the raw `SQLite` procedures directly.
|
|
|
+- For a raw C pointer to a V3 array, use `ADR(a[0])`, not `ADR(a)`.
|
|
|
+- V3 string literals in the current compiler can be truncated for long
|
|
|
+ SQL text. Keep individual literals short, or build the SQL through a
|
|
|
+ character buffer/concatenation. Adjacent string literal concatenation
|
|
|
+ is not supported.
|
|
|
+- The upstream tests are specifications, not a runnable harness for this
|
|
|
+ binding.
|
