# SQLite binding (core slice)

This is a small, hand-written V3 binding for the core SQLite API:
scalar values, BLOBs, prepared statements and connection control.  It
is not a replacement for the full `m2SQLITE` definition.

## Current surface

```modula2
(* connection *)
sqlite3_open
sqlite3_open_v2
sqlite3_exec
sqlite3_close
sqlite3_close_v2

(* prepared statements *)
sqlite3_prepare_v2
sqlite3_bind_int
sqlite3_bind_int64
sqlite3_bind_double
sqlite3_bind_null
sqlite3_bind_blob
sqlite3_bind_zeroblob
sqlite3_bind_text
sqlite3_step
sqlite3_reset
sqlite3_clear_bindings
sqlite3_finalize

(* row change metadata *)
sqlite3_changes
sqlite3_total_changes
sqlite3_last_insert_rowid

(* column metadata and scalar results *)
sqlite3_column_count
sqlite3_data_count
sqlite3_column_type
sqlite3_column_bytes
sqlite3_column_int
sqlite3_column_int64
sqlite3_column_double
sqlite3_column_blob
sqlite3_column_text
sqlite3_column_name
sqlite3_column_decltype

(* errors and ownership *)
sqlite3_errmsg
sqlite3_errstr
sqlite3_errcode
sqlite3_extended_errcode
sqlite3_extended_result_codes
sqlite3_free

(* incremental BLOB I/O *)
sqlite3_blob_open
sqlite3_blob_close
sqlite3_blob_read
sqlite3_blob_write
sqlite3_blob_bytes
sqlite3_blob_reopen

(* binding helper *)
SQLiteTransient
```

The matching constants include the primary result codes
(`SQLiteOk`, `SQLiteConstraint`, ...), `SQLiteRow`, `SQLiteDone`,
storage classes (`SQLiteInteger`, `SQLiteFloat`, `SQLiteText`,
`SQLiteBlob`, `SQLiteNull`), a few extended constraints and the
`SQLiteOpen*` flags used by `sqlite3_open_v2` and `sqlite3_blob_open`.

## Tests and showcase

`run.sh` builds and runs:

- `SQLiteSmoke.mod` - open / exec / close
- `SQLitePrepared.mod` - prepared insert and select
- `SQLiteScalar.mod` - int, int64, double, text, NULL and column metadata
- `SQLiteErrors.mod` - error codes, errmsg/errstr and `sqlite3_free`
- `SQLiteBlob.mod` - bind_blob, bind_zeroblob, column_blob and incremental BLOB I/O
- `SQLiteConnection.mod` - open_v2, close_v2, changes/rowid and deferred close
- `showcase/SQLiteShowcase.mod` - prepared-statement walkthrough

The showcase prints:

```text
1: Ada
2: Grace
```

## Build/run

```sh
./run.sh
```

The script uses `pkg-config --libs sqlite3` when available; otherwise it
links the versioned runtime library directly:

```text
/usr/lib/x86_64-linux-gnu/libsqlite3.so.0
```

That fallback matters on systems with the SQLite runtime installed but
without `libsqlite3-dev`.

## Ownership notes

- `sqlite3_exec` now takes `VAR errmsg : ADDRESS`.  A non-NIL message is
  allocated by SQLite and must be released with `sqlite3_free`.
- `sqlite3_errmsg` and `sqlite3_errstr` return borrowed C strings.  Copy
  them with `CStr.Copy` if they need to outlive the next SQLite call.
- `sqlite3_column_text` and `sqlite3_column_blob` return pointers valid
  only until the next `step`, `reset` or `finalize`; copy or consume them
  immediately.
- For a raw C data pointer to a V3 array, use `ADR(a[0])`, not `ADR(a)`:
  `ADR(a)` points at the V3 array descriptor.
- `SQLiteTransient()` supplies the `SQLITE_TRANSIENT` sentinel so SQLite
  copies bound text or BLOB data.  Passing `NIL` means `SQLITE_STATIC`;
  the caller's buffer must then stay alive until the statement is reset
  or finalized.
- `sqlite3_blob_open` needs an explicit `SQLiteOpenReadOnly` or
  `SQLiteOpenReadWrite` flag.  A BLOB handle holds a read/write lock on
  its row until `sqlite3_blob_close`.
- When extended result codes are enabled, `sqlite3_exec` and
  `sqlite3_errcode` can report an extended code such as
  `SQLiteConstraintPrimaryKey` (1555) rather than only
  `SQLiteConstraint` (19).

## Still to add

Callbacks, backup, extension loading, WAL/checkpoint helpers, connection
configuration and statement parameter introspection.