v0.7.1 (build 925)
Koya home

Module/sqlite

SQLite3 bindings exposed to QuickJS via a native plugin.

Async SQLite3 wrapper with Promise-based API. Provides open/close, exec (DDL/DML), and query (SELECT). Work is performed on a dedicated worker thread; results resolve on the engine's update loop.

Import #

import * as Sqlite from 'Module/sqlite';

Types #

DatabaseHandle
Opaque handle returned by open() and openInMemory().
  • id number - Internal database identifier.

Functions #

open
Opens (and creates if missing) a database file.
open(path: string): DatabaseHandle
openInMemory
Opens an in-memory database.
openInMemory(): DatabaseHandle
close
Closes the database handle.
close(db: DatabaseHandle): void
exec
Executes statements that do not return rows (CREATE/INSERT/UPDATE/DELETE/etc.).
  • Rejects with an error object { message, code } on failure.
exec(db: DatabaseHandle, sql: string): Promise<void>
query
Runs a SELECT and resolves to an array of row objects.
  • Column names map to object keys; values are strings or null for now; coerce in JS as needed.
query(db: DatabaseHandle, sql: string): Promise<Array<Record<string, any>>>

Example #

Open a persistent database, create a table, insert a row, query it back, and close the handle. This covers the full lifecycle of a typical key-value storage pattern.

import * as Sqlite from 'Module/sqlite';
import * as Log from 'Helix/Log';

const db = Sqlite.open('/home/user/.koya/app.db');
await Sqlite.exec(db, 'CREATE TABLE IF NOT EXISTS kv (k TEXT PRIMARY KEY, v TEXT)');
await Sqlite.exec(db, "INSERT OR REPLACE INTO kv(k,v) VALUES('hello','world')");

const rows = await Sqlite.query(db, 'SELECT k, v FROM kv');
for (const r of rows) {
  Log.info(r.k + '=' + r.v);
}

Sqlite.close(db);

Notes #

  • exec/query return Promises that reject with { message, code } on failure. Use try/catch with await.
  • For large blobs, consider base64 encoding at the JS layer for now.
<- Module/httpModule/dbus ->