@gjsify/sqlite-native 0.0.0-stage → 0.64.12-next.281

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# @gjsify/sqlite-native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Optional native Vala bridge over the system **libsqlite3** for GJS: a connection handle
+(`GjsifySqlite.Database`), prepared statements with 1-based parameter binding
+(`GjsifySqlite.Statement`), and a typed column cursor. Errors carry sqlite's **extended** result
+code, so a caller can tell `SQLITE_CONSTRAINT_UNIQUE` (2067) from bare `SQLITE_CONSTRAINT` (19).
+
+Part of the [gjsify](https://github.com/gjsify/gjsify) project — Node.js and Web APIs for GJS
+(GNOME JavaScript).
+
+## What is and is not here
+
+The bridge is deliberately thin. It exposes only what needs a C pointer — a live `sqlite3_stmt`
+with its bindings and cursor — and nothing it can avoid. Everything `node:sqlite` promises on top
+of that (the `DatabaseSync`/`StatementSync` surface, statement caching, JS value coercion,
+`readBigInts`, the error class hierarchy) belongs to [`@gjsify/sqlite`](../sqlite) and is written
+in TypeScript.
+
+Text is UTF-8 in both directions, straight through: sqlite's native encoding is GJS's.
+
+## Installation
+
+This package is loaded automatically by `@gjsify/sqlite` when present.
+
+```bash
+gjsify install @gjsify/sqlite-native
+
+# npm or yarn also work:
+npm install @gjsify/sqlite-native
+yarn add @gjsify/sqlite-native
+```
+
+## Usage
+
+```typescript
+import { hasNativeSqlite, loadNativeSqlite } from '@gjsify/sqlite-native';
+
+if (hasNativeSqlite()) {
+    const { Database, OpenMode, StepResult } = loadNativeSqlite()!;
+
+    const db = Database.open(':memory:', OpenMode.READWRITE_CREATE, false);
+    db.exec('CREATE TABLE t (a INTEGER PRIMARY KEY, b TEXT)');
+
+    const insert = db.prepare('INSERT INTO t (b) VALUES (?)');
+    insert.bind_text(1, 'hello');
+    insert.step();
+    insert.close();
+    console.log(db.last_insert_rowid, db.changes);
+
+    const select = db.prepare('SELECT b FROM t');
+    while (select.step() === StepResult.ROW) {
+        console.log(select.column_text(0));
+    }
+    db.close();
+}
+```
+
+`Database.close()` finalizes every statement still open on the connection first, so closing in
+either order is safe — and so is leaving both to the garbage collector, since each `Statement`
+holds a strong reference to its database.
+
+## Lifetime and naming notes
+
+- **`Statement.close()`, not `finalize()`.** The sqlite call behind it is `sqlite3_finalize`, but
+  a Vala method named `finalize` on a `GLib.Object` subclass collides with the generated
+  `GObjectClass.finalize` slot, so the method carries the name every other resource type in this
+  workspace uses.
+- **`Database.close()` drains before it drops.** The Vala binding exposes plain `sqlite3_close`,
+  which refuses a connection with outstanding statements and leaks the handle with only a
+  warning. Finalizing the live statements first is what lets this bridge do without
+  `sqlite3_close_v2`.
+
+## Requirements
+
+**libsqlite3 ≥ 3.37** — `sqlite3_changes64` is checked for at meson configure time and a older
+library fails the build loudly rather than truncating a bulk `UPDATE`'s row count in silence.
+
+`sqlite3_column_origin_name` is deliberately **not** exposed: it needs
+`SQLITE_ENABLE_COLUMN_METADATA`, which macOS's system libsqlite3 is not built with, so a darwin
+prebuild would link against a symbol that is not there. `column_decltype()` is available
+everywhere and is what the JS layer uses.
+
+## Platform coverage
+
+| Platform | Prebuild | Built by |
+|---|---|---|
+| `linux-x64`, `linux-arm64` | ✅ `.so` + `.gir` + `.typelib` | native runner |
+| `linux-ppc64`, `linux-s390x`, `linux-riscv64` | ✅ | QEMU emulation |
+| `darwin-arm64`, `darwin-x64` (macOS) | ✅ `.dylib` + `.gir` + `.typelib` | `macos-latest` / `macos-13` runner |
+| Windows | ❌ | — no Vala toolchain leg |
+
+Linux builds link the distribution's `sqlite-devel`; macOS links the libsqlite3 that ships in the
+SDK, so no Homebrew formula is involved. All prebuilds are produced by
+[`.github/workflows/prebuilds.yml`](../../../.github/workflows/prebuilds.yml) and committed back
+to the repository.
+
+## License
+
+MIT

package/lib/esm/_virtual/_rolldown/runtime.js

@@ -0,0 +1 @@
+var e=Object.defineProperty,__name=(t,n)=>e(t,`name`,{value:n,configurable:!0});export{__name};

package/lib/esm/index.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{loadOptionalNativeModule as e}from"@gjsify/utils/core";let t=null,n=!1,r=null;function loadNativeSqlite(){if(n)return t;n=!0;let{module:i,error:a}=e(`GjsifySqlite`,[`Database`,`Statement`]);return t=i,r=a,t}function hasNativeSqlite(){return loadNativeSqlite()!==null}function getLoadError(){return r}export{getLoadError,hasNativeSqlite,loadNativeSqlite};

package/lib/types/index.d.ts

@@ -0,0 +1,28 @@
+import type { GjsifySqlite as GjsifySqliteNS } from 'gi://GjsifySqlite?version=1.0';
+type DatabaseInstance = GjsifySqliteNS.Database;
+type DatabaseStatic = typeof GjsifySqliteNS.Database;
+type StatementInstance = GjsifySqliteNS.Statement;
+type StatementStatic = typeof GjsifySqliteNS.Statement;
+export interface NativeSqliteModule {
+    Database: DatabaseStatic;
+    Statement: StatementStatic;
+    OpenMode: typeof GjsifySqliteNS.OpenMode;
+    StepResult: typeof GjsifySqliteNS.StepResult;
+    ColumnType: typeof GjsifySqliteNS.ColumnType;
+}
+export type { DatabaseInstance as Database };
+export type { StatementInstance as Statement };
+/**
+ * Lazily load the GjsifySqlite typelib. Idempotent — subsequent calls
+ * return the cached module (or `null` if the first call failed).
+ */
+export declare function loadNativeSqlite(): NativeSqliteModule | null;
+/**
+ * Returns `true` if the GjsifySqlite typelib is loadable (prebuild present).
+ */
+export declare function hasNativeSqlite(): boolean;
+/**
+ * Returns the load error from the first `loadNativeSqlite()` call, or `null`
+ * if loading succeeded or hasn't been attempted yet.
+ */
+export declare function getLoadError(): Error | null;

package/lib/types/sqlite.gjs.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/meson.build

@@ -0,0 +1,106 @@
+# `buildtype=plain` = NO `-g`. ld64 emits a DEBUG MAP into any image whose objects
+# carry DWARF — one `N_OSO` stab per object, holding its MTIME — so with `-g` every
+# rebuild of this commit differed in bytes (plus the `LC_UUID` and the ad-hoc signature
+# computed over them) and `commit-prebuilds` re-committed all 16 darwin dylibs. That map
+# names intermediate `.o` files no consumer can have. Why: docs/prebuilds.md.
+project('GjsifySqlite', ['c', 'vala'], version: '1.0',
+        default_options: ['buildtype=plain'])
+
+root_dir = meson.current_source_dir()
+
+# Required system packages (Fedora 43+):
+#   dnf install vala meson ninja-build sqlite-devel
+#
+# Bindings: Vala SHIPS a `sqlite3.vapi`, so unlike the nghttp2 bridge this one
+# needs no C shim — `--pkg=sqlite3` gives Vala the whole API it uses. The four
+# entry points that vapi predates are declared in src/vala/sqlite-compat.vapi,
+# which is why `--vapidir` points back into this package.
+#
+# We use cc.find_library instead of `dependency()` for sqlite3 — `dependency()`
+# makes meson pass `--pkg sqlite3` to valac AS A PKG-CONFIG NAME and then also
+# hand it the pkg-config vapi lookup, which collides with the bundled vapi we
+# want. find_library only affects the C compile + link stages, not Vala.
+# macOS needs no formula for it: libsqlite3 and sqlite3.h are both in the SDK.
+cc = meson.get_compiler('c')
+
+sqlite3_lib = cc.find_library('sqlite3', has_headers: ['sqlite3.h'])
+
+# `sqlite3_changes64` arrived in sqlite 3.37 (2021-11). Asserting it here turns a
+# too-old libsqlite3 into a configure error naming the version, instead of an
+# undefined symbol at link time or — on a host that links lazily — at dlopen,
+# which docs/prebuilds.md records as the failure nobody reads correctly.
+assert(cc.has_function('sqlite3_changes64',
+                       prefix: '#include <sqlite3.h>',
+                       dependencies: sqlite3_lib),
+       'libsqlite3 is older than 3.37: sqlite3_changes64 is missing')
+
+host_system = host_machine.system()
+
+# On darwin every GNOME library is resolved against the HOST PROCESS rather than
+# recorded as an `@rpath/` dependency: a second GLib beside the one the host
+# already loaded gives the process two GType registries, then SIGSEGV.
+# docs/prebuilds.md § One GLib. libsqlite3 is NOT host-provided — it reaches no
+# GLib, so it stays an ordinary link dependency.
+host_provided = ['glib-2.0', 'gobject-2.0']
+
+vala_deps = []
+foreach pkg : host_provided
+    dep = dependency(pkg)
+    vala_deps += host_system == 'darwin' \
+        ? dep.partial_dependency(compile_args: true, includes: true) \
+        : dep
+endforeach
+
+host_provided_link_args = host_system == 'darwin' ? ['-Wl,-undefined,dynamic_lookup'] : []
+
+sources = files(
+    'src/vala/database.vala',
+    'src/vala/statement.vala',
+)
+
+libGjsifySqlite = library('gjsifysqlite', sources,
+    dependencies: vala_deps + [sqlite3_lib],
+    vala_args: [
+        '--pkg=sqlite3',
+        '--vapidir=' + root_dir / 'src/vala',
+        '--pkg=sqlite-compat',
+    ],
+    link_args: host_provided_link_args,
+    vala_gir: meson.project_name() + '-1.0.gir',
+    install: true,
+    install_dir: [true, true, true, true],
+)
+
+# ----------------------------------------------------------------------------
+# Host-dependent shared-library leaf name.
+#
+# The typelib records the exact filename gjs' g_module_open() resolves at load
+# time, and meson names the shared library per host convention: lib<name>.so on
+# ELF hosts, lib<name>.dylib on macOS. Recording the wrong leaf yields a typelib
+# that IS found via GI_TYPELIB_PATH but whose library never loads — a silent,
+# confusing failure. Mirrors the branch in packages/napi/napi/meson.build.
+#
+# Windows is deliberately absent: this bridge has had no Windows portability
+# work, so `else` (ELF naming) is the honest fallback rather than a .dll branch
+# that would imply support which does not exist.
+# ----------------------------------------------------------------------------
+if host_system == 'darwin'
+    shared_lib_name = 'libgjsifysqlite.dylib'
+else
+    shared_lib_name = 'libgjsifysqlite.so'
+endif
+
+g_ir_compiler = find_program('g-ir-compiler')
+
+custom_target(meson.project_name() + '-1.0.typelib',
+    command: [
+        g_ir_compiler,
+        '--shared-library', shared_lib_name,
+        '--output', '@OUTPUT@',
+        meson.current_build_dir() / meson.project_name() + '-1.0.gir',
+    ],
+    output: meson.project_name() + '-1.0.typelib',
+    depends: libGjsifySqlite,
+    install: true,
+    install_dir: get_option('libdir') / 'girepository-1.0',
+)

package/package.json

@@ -1,6 +1,96 @@
 {
-  "name": "@gjsify/sqlite-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@gjsify/sqlite-native",
+    "version": "0.64.12-next.281",
+    "description": "Optional Vala/GObject bridge over the system libsqlite3, exposing the parts of the C API that cannot be expressed in JavaScript: a connection handle, prepared statements with 1-based parameter binding, and a typed column cursor. Errors carry sqlite's extended result code. Used by @gjsify/sqlite to implement node:sqlite directly on sqlite3 instead of through libgda.",
+    "type": "module",
+    "main": "lib/esm/index.js",
+    "module": "lib/esm/index.js",
+    "types": "lib/types/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./lib/types/index.d.ts",
+            "default": "./lib/esm/index.js"
+        }
+    },
+    "files": [
+        "lib",
+        "meson.build",
+        "src/vala"
+    ],
+    "gjsify": {
+        "platforms": [
+            "linux-x64",
+            "linux-arm64",
+            "linux-ppc64",
+            "linux-s390x",
+            "linux-riscv64",
+            "darwin-arm64",
+            "darwin-x64"
+        ],
+        "runtimes": {
+            "gjs": "polyfill",
+            "node": "none",
+            "browser": "none",
+            "nativescript": "none"
+        },
+        "tier": 1
+    },
+    "scripts": {
+        "clear": "gjsify clear lib build tsconfig.tsbuildinfo tsconfig.types.tsbuildinfo test.gjs.mjs",
+        "check": "gjsify tsc --noEmit",
+        "init:meson": "meson setup build .",
+        "init:meson:wipe": "gjsify run init:meson --wipe",
+        "build": "gjsify run build:gjsify && gjsify run build:types",
+        "build:gjsify": "gjsify build --library 'src/ts/**/*.{ts,js}' --exclude 'src/ts/**/*.spec.{mts,ts}' 'src/ts/test.{mts,ts}'",
+        "build:meson": "gjsify run init:meson && meson compile -C build",
+        "build:types": "gjsify tsc",
+        "build:prebuilds": "gjsify run build:meson && node ../../../scripts/stage-prebuild.mjs .",
+        "build:gir-types": "ts-for-gir generate --externalDeps --allowMissingDeps --girDirectories=../sqlite-native-linux-x64/prebuilds/linux-x64 --girDirectories=/usr/share/gir-1.0 --modules=GjsifySqlite-1.0 --outdir=src/ts --npmScope=@girs --package=false --ignoreVersionConflicts=true",
+        "build:test": "gjsify run build:test:gjs",
+        "build:test:gjs": "gjsify build src/ts/test.mts --app gjs --outfile test.gjs.mjs",
+        "test": "gjsify run build:gjsify && gjsify run build:test && gjsify run test:gjs",
+        "test:gjs": "gjsify run test.gjs.mjs"
+    },
+    "keywords": [
+        "gjs",
+        "sqlite",
+        "sqlite3",
+        "database",
+        "prepared-statement",
+        "vala",
+        "native"
+    ],
+    "dependencies": {
+        "@girs/gjs": "5.4.0",
+        "@girs/glib-2.0": "5.4.0",
+        "@girs/gobject-2.0": "5.4.0",
+        "@gjsify/utils": "0.64.12-next.281"
+    },
+    "devDependencies": {
+        "@gjsify/cli": "0.64.12-next.281",
+        "@gjsify/unit": "0.64.12-next.281",
+        "@ts-for-gir/cli": "^4.1.0",
+        "@types/node": "^25.9.2",
+        "typescript": "^6.0.3"
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gjsify/gjsify.git",
+        "directory": "packages/node/sqlite-native"
+    },
+    "bugs": {
+        "url": "https://github.com/gjsify/gjsify/issues"
+    },
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/node/sqlite-native#readme",
+    "optionalDependencies": {
+        "@gjsify/sqlite-native-darwin-arm64": "0.64.12-next.281",
+        "@gjsify/sqlite-native-darwin-x64": "0.64.12-next.281",
+        "@gjsify/sqlite-native-linux-arm64": "0.64.12-next.281",
+        "@gjsify/sqlite-native-linux-ppc64": "0.64.12-next.281",
+        "@gjsify/sqlite-native-linux-riscv64": "0.64.12-next.281",
+        "@gjsify/sqlite-native-linux-s390x": "0.64.12-next.281",
+        "@gjsify/sqlite-native-linux-x64": "0.64.12-next.281"
+    },
+    "gitHead": "c4d2e266c0d9849860b9828c14ebfe37b6d493b8"
+}

package/src/vala/database.vala

@@ -0,0 +1,316 @@
+/*
+ * GjsifySqlite.Database — a libsqlite3 connection, introspectable.
+ *
+ * This bridge is DELIBERATELY THIN. Everything `node:sqlite` promises on top of
+ * sqlite — statement caching, the `DatabaseSync`/`StatementSync` surface, the
+ * JS value coercions, `readBigInts`, the error class hierarchy — belongs to
+ * `@gjsify/sqlite` and lives in TypeScript. What cannot live there is the part
+ * that needs a C pointer: a prepared `sqlite3_stmt` with bindings and a column
+ * cursor. So this file exposes exactly that and nothing it can avoid.
+ *
+ * Errors travel as a GLib.Error in the {@link GjsifySqlite.SqliteError} domain
+ * whose `code` is sqlite's EXTENDED result code (2067, not 19) — GJS surfaces
+ * that unchanged on the thrown exception, which is the only reason the JS layer
+ * can rebuild Node's `err.errcode` without a second round trip.
+ */
+
+namespace GjsifySqlite {
+
+    /**
+     * The error domain every failure here is reported in.
+     *
+     * The enumerated member is a formality: the `code` carried by a thrown
+     * error is never FAILED but sqlite's own extended result code, so that the
+     * JS layer sees what `sqlite3_extended_errcode()` saw. Only the DOMAIN is
+     * load-bearing — see {@link sqlite_error}.
+     */
+    public errordomain SqliteError {
+        FAILED
+    }
+
+    /**
+     * Mint an error in the {@link SqliteError} domain carrying @code.
+     *
+     * Vala offers no way to name an errordomain's quark, and its `throw new
+     * SqliteError.FAILED (…)` form can only produce the enumerated code — which
+     * is the one value that tells the JS layer nothing. Constructing the error
+     * and then overwriting its public `code` field is how both halves are had
+     * at once: the domain Vala generated, and sqlite's own result code.
+     */
+    internal SqliteError sqlite_error (int code, string message) {
+        var error = new SqliteError.FAILED ("%s", message);
+        error.code = code;
+        return error;
+    }
+
+    /** How {@link Database.open} should treat a missing or read-only file. */
+    public enum OpenMode {
+        /** Open an existing database for reading; fail if it does not exist. */
+        READONLY,
+        /** Open an existing database for writing; fail if it does not exist. */
+        READWRITE,
+        /** Open for writing, creating the database when it does not exist. */
+        READWRITE_CREATE
+    }
+
+    /** What {@link Statement.step} found. Anything else is thrown. */
+    public enum StepResult {
+        /** A row is available; the column accessors may be read. */
+        ROW,
+        /** The statement ran to completion and has no (more) rows. */
+        DONE
+    }
+
+    /** The storage class of a value in the current row. */
+    public enum ColumnType {
+        INTEGER,
+        FLOAT,
+        TEXT,
+        BLOB,
+        NULL
+    }
+
+    /**
+     * A connection to a SQLite database.
+     *
+     * Obtained from {@link Database.open}; there is no public constructor,
+     * because an instance without a handle has no useful state.
+     */
+    public class Database : GLib.Object {
+
+        private Sqlite.Database? handle = null;
+
+        /**
+         * Every statement prepared from this connection and not yet closed.
+         *
+         * Entries are UNOWNED: the reference runs the other way, each
+         * {@link Statement} holding a strong ref on its database. That
+         * direction is what makes the teardown order safe — a connection
+         * cannot be finalized while a statement can still reach its handle —
+         * and this list exists only so {@link close} can reach the statements
+         * it must finalize first.
+         */
+        private GLib.List<unowned Statement> live = new GLib.List<unowned Statement> ();
+
+        /** Whether the connection is still usable. */
+        public bool is_open {
+            get { return this.handle != null; }
+        }
+
+        /**
+         * ROWID of the most recent successful INSERT, or 0 when there was none
+         * — and 0 on a closed connection, since a property cannot throw.
+         */
+        public int64 last_insert_rowid {
+            get {
+                if (this.handle == null) {
+                    return 0;
+                }
+                return this.handle.last_insert_rowid ();
+            }
+        }
+
+        /**
+         * Rows changed by the most recent INSERT/UPDATE/DELETE.
+         *
+         * `sqlite3_changes64`, not `sqlite3_changes`: the 32-bit one truncates
+         * a bulk UPDATE's count silently, and a wrong number is worse here than
+         * no number.
+         */
+        public int64 changes {
+            get {
+                if (this.handle == null) {
+                    return 0;
+                }
+                return GjsifySqliteCompat.changes64 (this.handle);
+            }
+        }
+
+        /**
+         * Whether an explicit transaction is open.
+         *
+         * `sqlite3_get_autocommit()` answers the inverse — autocommit is ON
+         * exactly when no transaction is pending — so the sense is flipped here
+         * rather than in every caller.
+         */
+        public bool in_transaction {
+            get {
+                if (this.handle == null) {
+                    return false;
+                }
+                return this.handle.get_autocommit () == 0;
+            }
+        }
+
+        /**
+         * Open a database file.
+         *
+         * @param path     filesystem path, `:memory:`, or a URI when @uri
+         * @param mode     which of the three useful `SQLITE_OPEN_*` combinations
+         * @param uri      interpret @path as a `file:` URI with query parameters
+         */
+        public static Database open (string path,
+                                     OpenMode mode = OpenMode.READWRITE_CREATE,
+                                     bool uri = false) throws SqliteError {
+            int flags;
+            switch (mode) {
+                case OpenMode.READONLY:
+                    flags = Sqlite.OPEN_READONLY;
+                    break;
+                case OpenMode.READWRITE:
+                    flags = Sqlite.OPEN_READWRITE;
+                    break;
+                default:
+                    flags = Sqlite.OPEN_READWRITE | Sqlite.OPEN_CREATE;
+                    break;
+            }
+            if (uri) {
+                flags |= Sqlite.OPEN_URI;
+            }
+
+            Sqlite.Database opened;
+            int rc = Sqlite.Database.open_v2 (path, out opened, flags, null);
+
+            if (rc != Sqlite.OK) {
+                // sqlite hands back a handle even for most failures, and it is
+                // the only thing that knows WHY. Reading the message off it
+                // before it goes out of scope (where the vapi's free function
+                // closes it) is the difference between "unable to open database
+                // file" and bare "error 14".
+                string message;
+                int code;
+                if (opened != null) {
+                    message = opened.errmsg ();
+                    code = GjsifySqliteCompat.extended_errcode (opened);
+                } else {
+                    message = GjsifySqliteCompat.errstr (rc);
+                    code = rc;
+                }
+                throw sqlite_error ((code & 0xff) == rc ? code : rc, message);
+            }
+
+            // Without this, errcode() and extended_errcode() answer the same
+            // primary code and the JS layer can never tell SQLITE_CONSTRAINT
+            // from SQLITE_CONSTRAINT_UNIQUE.
+            opened.extended_result_codes (1);
+
+            var db = new Database ();
+            db.handle = (owned) opened;
+            return db;
+        }
+
+        /**
+         * Run one or more statements, discarding any rows.
+         *
+         * This is `sqlite3_exec`, so it accepts a whole script — the JS layer
+         * uses it for `DatabaseSync.exec()`.
+         */
+        public void exec (string sql) throws SqliteError {
+            unowned Sqlite.Database h = this.require_handle ();
+            string? message = null;
+            int rc = h.exec (sql, null, out message);
+            if (rc != Sqlite.OK) {
+                throw this.make_error (rc, message);
+            }
+        }
+
+        /**
+         * Compile the FIRST statement in @sql.
+         *
+         * Text after that statement is ignored, exactly as `sqlite3_prepare_v2`
+         * ignores it; callers wanting a script want {@link exec}.
+         */
+        public Statement prepare (string sql) throws SqliteError {
+            unowned Sqlite.Database h = this.require_handle ();
+
+            Sqlite.Statement compiled;
+            int rc = h.prepare_v2 (sql, -1, out compiled);
+            if (rc != Sqlite.OK) {
+                throw this.make_error (rc);
+            }
+            if (compiled == null) {
+                // SQLITE_OK with a null statement is how sqlite reports input
+                // that held only whitespace or a comment. Node raises here, so
+                // the bridge does too rather than hand back a statement whose
+                // every method would misuse-fail.
+                throw sqlite_error (Sqlite.ERROR,
+                                    "the SQL text contains no statement");
+            }
+
+            return new Statement (this, (owned) compiled);
+        }
+
+        /**
+         * Close the connection. Idempotent.
+         *
+         * Every statement still open is finalized FIRST: the vapi binds the
+         * plain `sqlite3_close`, which refuses a connection with outstanding
+         * statements and would leave the handle leaked with only a warning.
+         * Draining the list here is what lets this bridge do without
+         * `sqlite3_close_v2`.
+         */
+        public void close () {
+            if (this.handle == null) {
+                return;
+            }
+
+            // Emptied before the loop so that each statement's unregister()
+            // becomes a no-op and cannot mutate a list being walked.
+            GLib.List<unowned Statement> pending = (owned) this.live;
+            this.live = new GLib.List<unowned Statement> ();
+
+            foreach (unowned Statement stmt in pending) {
+                stmt.close ();
+            }
+
+            this.handle = null;
+        }
+
+        internal void register (Statement stmt) {
+            this.live.prepend (stmt);
+        }
+
+        internal void unregister (Statement stmt) {
+            this.live.remove (stmt);
+        }
+
+        /**
+         * Build — not throw — the error for a failed call on this connection.
+         *
+         * Returning it keeps Vala's flow analysis satisfied at the call sites,
+         * which all spell `throw this.make_error (rc)` and so still read as the
+         * exits they are.
+         */
+        internal SqliteError make_error (int rc, string? message = null) {
+            int code = rc;
+            string text;
+
+            if (this.handle != null) {
+                // The extended code belongs to the CONNECTION, not to the call,
+                // so it only describes this failure when its low byte is the
+                // primary code the call just returned.
+                int extended = GjsifySqliteCompat.extended_errcode (this.handle);
+                if ((extended & 0xff) == rc) {
+                    code = extended;
+                }
+            }
+
+            if (message != null) {
+                text = message;
+            } else if (this.handle != null) {
+                text = this.handle.errmsg ();
+            } else {
+                text = GjsifySqliteCompat.errstr (rc);
+            }
+
+            return sqlite_error (code, text);
+        }
+
+        private unowned Sqlite.Database require_handle () throws SqliteError {
+            if (this.handle == null) {
+                throw sqlite_error (Sqlite.MISUSE, "database is not open");
+            }
+            return this.handle;
+        }
+    }
+}

package/src/vala/sqlite-compat.vapi

@@ -0,0 +1,77 @@
+/*
+ * sqlite-compat.vapi — the libsqlite3 entry points Vala 0.56's bundled
+ * `sqlite3.vapi` does not declare.
+ *
+ * WHY THIS FILE EXISTS
+ * ────────────────────
+ * `sqlite3.vapi` ships with Vala and covers most of the C API, but it was
+ * written against sqlite 3.4 and has not tracked every addition since. Four
+ * symbols this bridge needs are missing from it, and each has a reason it
+ * cannot be worked around:
+ *
+ *   • sqlite3_changes64        — the vapi only has `changes()`, which returns
+ *                                `int`. `node:sqlite` reports `changes` as a
+ *                                BigInt-capable count, so truncating at 2^31
+ *                                would be a silent wrong answer on a bulk
+ *                                UPDATE. Added in sqlite 3.37 (2021-11).
+ *   • sqlite3_extended_errcode — `errcode()` answers the PRIMARY result code
+ *                                (19 = SQLITE_CONSTRAINT) regardless of
+ *                                `extended_result_codes()`. Node reports the
+ *                                extended one (2067 = …_CONSTRAINT_UNIQUE) on
+ *                                `err.errcode`, and the JS layer can only
+ *                                build that if it travels out of here intact.
+ *   • sqlite3_errstr           — the only way to describe a result code when
+ *                                there is no connection to ask (an open that
+ *                                failed before a handle existed).
+ *   • sqlite3_column_decltype  — declared column type, needed so the JS layer
+ *                                can apply sqlite's type affinity rules.
+ *
+ * NOT declared here, deliberately: `sqlite3_column_origin_name`. It exists
+ * only in a libsqlite3 built with SQLITE_ENABLE_COLUMN_METADATA, which the
+ * macOS system library is not. Referencing it would link on Fedora and leave
+ * the darwin prebuild with an undefined symbol — found by GI, refused by the
+ * loader, which docs/prebuilds.md calls out as the silent failure mode.
+ *
+ * `sqlite3_close_v2` is likewise absent: {@link GjsifySqlite.Database.close}
+ * finalizes every live statement before it drops the handle, so the plain
+ * `sqlite3_close` the vapi already binds as the compact class's free function
+ * never meets an outstanding statement.
+ */
+
+[CCode (cheader_filename = "sqlite3.h")]
+namespace GjsifySqliteCompat {
+
+    /**
+     * Rows modified by the most recent statement, as int64.
+     *
+     * sqlite >= 3.37. The build asserts its presence at configure time rather
+     * than letting the link fail (see meson.build).
+     */
+    [CCode (cname = "sqlite3_changes64")]
+    public int64 changes64 (Sqlite.Database db);
+
+    /**
+     * The EXTENDED result code of the most recent failed call on @db — the
+     * value `node:sqlite` surfaces as `err.errcode`.
+     */
+    [CCode (cname = "sqlite3_extended_errcode")]
+    public int extended_errcode (Sqlite.Database db);
+
+    /**
+     * English text for a result code, with no connection involved.
+     *
+     * The string is owned by libsqlite3 and is valid for the process lifetime.
+     */
+    [CCode (cname = "sqlite3_errstr")]
+    public unowned string errstr (int result_code);
+
+    /**
+     * Declared type of a result column as written in the CREATE TABLE
+     * statement, or %null for an expression column.
+     *
+     * The string is owned by the statement and is invalidated by
+     * `sqlite3_finalize`; callers copy before returning it.
+     */
+    [CCode (cname = "sqlite3_column_decltype")]
+    public unowned string? column_decltype (Sqlite.Statement stmt, int column);
+}

package/src/vala/statement.vala

@@ -0,0 +1,285 @@
+/*
+ * GjsifySqlite.Statement — one compiled `sqlite3_stmt`, introspectable.
+ *
+ * Parameters are addressed by their 1-BASED sqlite index throughout, never by
+ * name: resolving `:foo` to an index is `bind_parameter_index()`, which is
+ * exposed so the JS layer can do that mapping once per statement instead of
+ * once per bind.
+ */
+
+namespace GjsifySqlite {
+
+    /**
+     * A prepared statement, obtained from {@link Database.prepare}.
+     *
+     * The instance holds a STRONG reference to its database. That is what makes
+     * the object graph safe in a garbage-collected host: GJS finalizes in no
+     * order anyone can predict, and without the ref a collected `Database`
+     * would close the connection under a statement that is still reachable from
+     * JS. With it, the connection outlives every statement by construction.
+     */
+    public class Statement : GLib.Object {
+
+        private Database? owner;
+        private Sqlite.Statement? stmt;
+
+        internal Statement (Database owner, owned Sqlite.Statement stmt) {
+            this.owner = owner;
+            this.stmt = (owned) stmt;
+            owner.register (this);
+        }
+
+        ~Statement () {
+            this.release ();
+        }
+
+        /** Whether the statement is still compiled and usable. */
+        public bool is_valid {
+            get { return this.stmt != null; }
+        }
+
+        /** Number of result columns; 0 for a statement that returns no rows. */
+        public int column_count {
+            get {
+                if (this.stmt == null) {
+                    return 0;
+                }
+                return this.stmt.column_count ();
+            }
+        }
+
+        /** Highest 1-based parameter index used by the statement. */
+        public int bind_parameter_count {
+            get {
+                if (this.stmt == null) {
+                    return 0;
+                }
+                return this.stmt.bind_parameter_count ();
+            }
+        }
+
+        /** The SQL text this statement was compiled from. */
+        public string? sql {
+            owned get {
+                if (this.stmt == null) {
+                    return null;
+                }
+                return this.stmt.sql ();
+            }
+        }
+
+        /** The SQL text with current bindings substituted in, for diagnostics. */
+        public string? expanded_sql {
+            owned get {
+                if (this.stmt == null) {
+                    return null;
+                }
+                return this.stmt.expanded_sql ();
+            }
+        }
+
+        /**
+         * Finalize the statement. Idempotent, and safe after the database was
+         * closed — {@link Database.close} calls exactly this on every statement
+         * it still knows about.
+         */
+        public void close () {
+            this.release ();
+        }
+
+        public void bind_null (int index) throws SqliteError {
+            this.check (this.require_stmt ().bind_null (index));
+        }
+
+        public void bind_int64 (int index, int64 value) throws SqliteError {
+            this.check (this.require_stmt ().bind_int64 (index, value));
+        }
+
+        public void bind_double (int index, double value) throws SqliteError {
+            this.check (this.require_stmt ().bind_double (index, value));
+        }
+
+        public void bind_text (int index, string value) throws SqliteError {
+            // The vapi's `bind_text` overload takes an OWNED string and hands
+            // sqlite `g_free` as the destructor, so the copy outlives this
+            // frame. The raw binding's default is SQLITE_STATIC, which would
+            // leave sqlite pointing at a freed buffer.
+            this.check (this.require_stmt ().bind_text (index, value));
+        }
+
+        /**
+         * Bind a BLOB.
+         *
+         * The bytes are COPIED. SQLITE_TRANSIENT — the sentinel that asks
+         * sqlite to copy for us — is a cast of -1 to a function pointer that
+         * Vala has no way to spell, and the alternative the binding defaults to
+         * (SQLITE_STATIC) would have sqlite read @value's buffer long after
+         * this frame and possibly the GLib.Bytes are gone.
+         */
+        public void bind_blob (int index, GLib.Bytes value) throws SqliteError {
+            unowned Sqlite.Statement s = this.require_stmt ();
+            size_t size = value.get_size ();
+
+            if (size == 0) {
+                // sqlite3_bind_blob with a null pointer binds NULL, not an
+                // empty blob, and a zero-length GLib.Bytes has no data pointer.
+                // bind_zeroblob(0) is how sqlite spells "a BLOB of no bytes".
+                this.check (s.bind_zeroblob (index, 0));
+                return;
+            }
+
+            if (size > int.MAX) {
+                throw sqlite_error (Sqlite.TOOBIG,
+                                    "blob exceeds the maximum size sqlite can bind");
+            }
+
+            void* copy = GLib.malloc (size);
+            GLib.Memory.copy (copy, value.get_data (), size);
+            // sqlite invokes the destructor even when the bind itself fails, so
+            // the failing path below leaks nothing.
+            this.check (s.bind_blob (index, copy, (int) size, GLib.g_free));
+        }
+
+        /** 1-based index of a named parameter, or 0 when there is no such name. */
+        public int bind_parameter_index (string name) throws SqliteError {
+            return this.require_stmt ().bind_parameter_index (name);
+        }
+
+        /** Name of a 1-based parameter, or %null for a positional `?`. */
+        public string? bind_parameter_name (int index) throws SqliteError {
+            unowned string? name = this.require_stmt ().bind_parameter_name (index);
+            return name;
+        }
+
+        /** Reset every binding to NULL without recompiling the statement. */
+        public void clear_bindings () throws SqliteError {
+            this.check (this.require_stmt ().clear_bindings ());
+        }
+
+        /**
+         * Advance the cursor.
+         *
+         * @return ROW when column values are available, DONE at the end
+         */
+        public StepResult step () throws SqliteError {
+            int rc = this.require_stmt ().step ();
+            if (rc == Sqlite.ROW) {
+                return StepResult.ROW;
+            }
+            if (rc == Sqlite.DONE) {
+                return StepResult.DONE;
+            }
+            throw this.owner.make_error (rc);
+        }
+
+        /**
+         * Rewind the statement so it can run again. Bindings are KEPT, matching
+         * `sqlite3_reset`; {@link clear_bindings} drops them.
+         */
+        public void reset () throws SqliteError {
+            // sqlite3_reset answers the error code of the statement's LAST run,
+            // which the caller has already been told about. Re-raising it here
+            // would report the same failure twice, so only the reset itself is
+            // checked — and it cannot fail on its own.
+            this.require_stmt ().reset ();
+        }
+
+        /** Name of a 0-based result column, as the SELECT labelled it. */
+        public string? column_name (int index) throws SqliteError {
+            unowned string? name = this.require_stmt ().column_name (index);
+            return name;
+        }
+
+        /**
+         * The column's declared type from CREATE TABLE, or %null for an
+         * expression column. The JS layer needs it to apply type affinity.
+         */
+        public string? column_decltype (int index) throws SqliteError {
+            unowned string? decl = GjsifySqliteCompat.column_decltype (this.require_stmt (), index);
+            return decl;
+        }
+
+        /** Storage class of the value in the current row. */
+        public ColumnType column_type (int index) throws SqliteError {
+            int type = this.require_stmt ().column_type (index);
+
+            // if/else rather than a switch: these are C macros reaching Vala as
+            // vapi constants, not case labels it will fold.
+            if (type == Sqlite.INTEGER) {
+                return ColumnType.INTEGER;
+            }
+            if (type == Sqlite.FLOAT) {
+                return ColumnType.FLOAT;
+            }
+            if (type == Sqlite.TEXT) {
+                return ColumnType.TEXT;
+            }
+            if (type == Sqlite.BLOB) {
+                return ColumnType.BLOB;
+            }
+            return ColumnType.NULL;
+        }
+
+        public int64 column_int64 (int index) throws SqliteError {
+            return this.require_stmt ().column_int64 (index);
+        }
+
+        public double column_double (int index) throws SqliteError {
+            return this.require_stmt ().column_double (index);
+        }
+
+        public string? column_text (int index) throws SqliteError {
+            unowned string? text = this.require_stmt ().column_text (index);
+            return text;
+        }
+
+        /**
+         * The column's bytes, copied into a fresh GLib.Bytes.
+         *
+         * A copy is not optional: sqlite's pointer is invalidated by the next
+         * step/reset/finalize, and GJS hands a GLib.Bytes to JS that may well
+         * outlive all three.
+         */
+        public GLib.Bytes column_blob (int index) throws SqliteError {
+            unowned Sqlite.Statement s = this.require_stmt ();
+
+            // Order matters: sqlite3_column_blob may convert the value, and
+            // sqlite3_column_bytes only reports the post-conversion length once
+            // it has. Asking for the length first can answer for the old type.
+            void* data = s.column_blob (index);
+            int size = s.column_bytes (index);
+
+            if (data == null || size <= 0) {
+                return new GLib.Bytes (new uint8[0]);
+            }
+
+            uint8[] copy = new uint8[size];
+            GLib.Memory.copy (copy, data, (size_t) size);
+            return new GLib.Bytes.take ((owned) copy);
+        }
+
+        private void release () {
+            // Dropping the field runs the vapi's free function, sqlite3_finalize.
+            this.stmt = null;
+
+            if (this.owner != null) {
+                this.owner.unregister (this);
+                this.owner = null;
+            }
+        }
+
+        private unowned Sqlite.Statement require_stmt () throws SqliteError {
+            if (this.stmt == null) {
+                throw sqlite_error (Sqlite.MISUSE, "statement is finalized");
+            }
+            return this.stmt;
+        }
+
+        private void check (int rc) throws SqliteError {
+            if (rc == Sqlite.OK) {
+                return;
+            }
+            throw this.owner.make_error (rc);
+        }
+    }
+}