# SQLite binding (scalar slice)

This is a small, hand-written V3 binding for the scalar SQLite API.  It
is not a replacement for the full `m2SQLITE` definition.

## Current surface

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

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

(* 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_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

(* binding helper *)
SQLiteTransient
```

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

## 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`
- `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` is valid only until the next `step`, `reset` or
  `finalize`; copy it immediately.
- `SQLiteTransient()` supplies the `SQLITE_TRANSIENT` sentinel so SQLite
  copies bound text.  Passing `NIL` means `SQLITE_STATIC`; the caller's
  buffer must then stay alive until the statement is reset or finalized.
- 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

BLOB binding/column access, `open_v2` flags, `close_v2`, changes/rowid
helpers, callbacks, BLOB I/O, backup and extension loading.