fastc-core-sqlite

SQLite bindings for fastC — FFI to system libsqlite3.

Part of the fastc-core launch set. The implementation currently ships inside the fastC compiler's built-in prelude — every fastC v1.0 program already gets use sqlite::* for free. This repository is the public home for the module's API and will become installable via fastc add github.com/Skelf-Research/fastc-core-sqlite once stage 1.7's vendor-consumption flow completes the loop.

Requires

System libsqlite3 at link time.

• macOS: brew install sqlite3
• Debian / Ubuntu: apt install libsqlite3-dev
• Alpine: apk add sqlite-dev

The fastC build driver passes -lsqlite3 to the linker when any module in the program imports sqlite::*.

Surface

use sqlite::Db;            // opaque — open database handle
use sqlite::Cursor;        // opaque — active query cursor
use sqlite::Row;           // opaque — one row from a result set
use sqlite::SqliteError;   // CannotOpen | SyntaxError | BindFailed
                           //           | BusyOrLocked | Other(i32)

use sqlite::open;
// (path: Str, cap: ref(CapFsWrite)) -> res(Db, SqliteError)

use sqlite::exec;
// (db: ref(Db), sql: Str) -> res(i32, SqliteError)
//   returns the number of rows affected

use sqlite::query;
// (db: ref(Db), sql: Str) -> res(Cursor, SqliteError)
//   starts a SELECT; advance with `next`

use sqlite::next;
// (cursor: mref(Cursor)) -> opt(Row)
//   None when the result set is exhausted

use sqlite::get_int;
// (row: ref(Row), col: i32) -> i64

use sqlite::get_text;
// (row: ref(Row), col: i32) -> Str

use sqlite::close;
// (db: Db) -> void
//   explicit cleanup; required before program exit

Parameter binding uses ? placeholders inline in the SQL string. A future slice adds typed bind APIs (bind_int, bind_text, …) for prepared statements that are reused across calls.

Example

use sqlite::open;
use sqlite::exec;
use sqlite::query;
use sqlite::next;
use sqlite::get_int;
use sqlite::get_text;
use sqlite::close;
use caps::init;
use io::println;

fn main() -> i32 {
    let bundle: Caps = init();
    let db: Db = open(":memory:", addr(bundle.fs_write))?;

    exec(addr(db), "CREATE TABLE users (id INTEGER, name TEXT)")?;
    exec(addr(db), "INSERT INTO users VALUES (1, 'ada')")?;

    let mut cur: Cursor = query(addr(db), "SELECT id, name FROM users")?;
    loop {
        match next(mref(cur)) {
            Some(row) => {
                println(get_text(addr(row), 1));
            }
            None => break,
        }
    }

    close(db);
    return 0;
}

Capability policy

open requires ref(CapFsWrite) — never CapFsRead. SQLite writes to a rollback journal (or WAL) file even for read-only queries the moment a transaction needs durability or another connection touches the database. A handle that can only read the filesystem cannot honour the engine's invariants, so the cap gate trips at open, not at exec. The :memory: path takes the same cap for surface uniformity — a future refinement may admit a no-cap in-memory open once the threat model is settled.

SQL injection safety

Never concatenate user input into the SQL string. Use ? placeholders and bind values via the (forthcoming) typed bind APIs, or — until those land — validate and quote inputs at the boundary with text::escape_sql_literal. String-built SQL is the single largest class of CVEs against database-backed services; the fastC review rubric treats inline interpolation of unvalidated input into exec/query as a hard failure.

Status

v0.1.0 — preview. API is final; the FFI bindings and the small runtime/sqlite_shim.h opaque-pointer wrapper land in the post-cutover sprint. Until then, the same API is available in every fastC v1.0 program via the built-in prelude.

License

MIT