Last updated

Two layers: std/db/driver is the raw executor (sqlite3 system lib, libpq lazily loaded); std/db is the JS ORM on top (query builder, models, relations, transactions, migrations). Placeholders only (? for sqlite, $1..$n for postgres) — values bind separately, never interpolated. Every terminal comes in async (Promise) + Sync twins; Sync twins block and return directly (for boot scripts).

const db = require("std/db");const s = await db.connect("sqlite::memory:");const User = s.defineModel("User", {table: "users", columns: {  id: {type: "integer", primaryKey: true, autoIncrement: true},  name: {type: "text", notNull: true}}});await User.createTable();await User.create({name: "ada"});console.log((await User.first()).name); // "ada"await s.close();

🔗db.connect

db.connect(spec) -> Promise<Database> / db.connectSync(spec) -> Database

"sqlite::memory:", "sqlite:/path/app.db", "sqlite:relative.db", "postgres://user:pass@host:5432/dbname", or {dialect: "sqlite", path} / {dialect: "postgres", host?, port?, user?, password?, database, connectTimeout?} (host defaults to 127.0.0.1, port to 5432). Same shapes on std/db/driver (driver.connect/connectSync return the raw handle).

const db = require("std/db");const s = await db.connect("sqlite::memory:");

🔗handle.query / exec

query(text[, params]) -> {rows, rowCount, changes, lastInsertRowId?} (same for exec)

params is an array of string|number|boolean|null (undefined throws — pass null for NULL). rows is [{col: val}]; BLOBs arrive as Uint8Array. Available raw (s.raw, driver handles) and on Database, each with a Sync twin. Invalid SQL throws before executing.

await s.exec("CREATE TABLE t(a TEXT)");await s.query("SELECT * FROM t WHERE a > ?", ["x"]);

🔗s.table

s.table(name) -> QueryBuilder

Fluent builder: where({col: val|{eq,ne,gt,gte,lt,lte,like,ilike,in,notIn}}), where("raw fragment", [params]) (AND-ed in order), select(cols?), orderBy(col[, dir]), limit(n), offset(n), join(kind, table, on), insert(row|[rows]), update(patch), delete() (refuses without WHERE). Terminals: all(), first(), run() (+ Sync twins); toSQL(dialect) previews.

await s.table("users").insert([{name: "ada", age: 36}]).run();const rows = await s.table("users").where({age: {gte: 18}})  .orderBy("age", "desc").select(["name"]).all();

🔗s.transaction

s.transaction(async (tx) => ...) -> fn return

BEGIN/COMMIT, rollback on throw; nested calls use savepoints.

await s.transaction(async (tx) => {  await tx.table("t").insert({a: 1}).run();  throw new Error("rolls back");});

🔗s.migrate

s.migrate(migrations) -> [appliedVersions] (+ migrateSync)

[{version: int>=1, up: "SQL"|[SQL...]}], sorted by version, tracked in _carne_migrations; applied-once.

await s.migrate([{version: 1, up: "CREATE TABLE t(a TEXT)"}]);

🔗s.defineModel

s.defineModel(name, {table?, columns}) -> Model

Column types: integer|real|text|blob|boolean|datetime, with primaryKey, autoIncrement, notNull, unique, default (exactly one primary key required).

const User = s.defineModel("User", {table: "users", columns: {  id: {type: "integer", primaryKey: true, autoIncrement: true}}});

🔗Model

createTable(), create(data), find(id), all(), first(), where(cond[, params]) -> {first, all}, get() (raw builder), hasMany(Other[, {foreignKey?}]) (adds inst.get<Plural>()), belongsTo(Other[, {foreignKey?}]) (adds inst.get<Model>()). Instances carry save() (UPDATE by pk) and remove().

User.hasMany(Post);const ana = await User.where({name: "ada"}).first();await ana.getPosts();ana.age = 37; await ana.save();

🔗handle.close

close() -> true

Idempotent; use-after-close throws.