M2compiler-V3/bindings/sqlite3/README.md

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

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

1: Ada
2: Grace

Build/run

./run.sh

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

/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.