quiverdb 0.10.1 → 0.10.3

package/README.md

@@ -64,6 +64,7 @@ bun run example.ts
 
 - `Database.fromSchema(dbPath, schemaPath)` -- Create database from SQL schema file
 - `Database.fromMigrations(dbPath, migrationsPath)` -- Create database from migrations directory
+- `Database.validateMigrations(migrationsPath)` -- Validate a migrations directory (every `up.sql`, then every `down.sql`, ending with no table left behind) in-memory; throws on failure
 - `close()` -- Close the database connection
 
 ### Create / Delete
@@ -71,28 +72,36 @@ bun run example.ts
 - `createElement(collection, data)` -- Create element, returns numeric ID
 - `updateElement(collection, id, data)` -- Update element by ID
 - `deleteElement(collection, id)` -- Delete element by ID
+- `updateElementByLabel(collection, label, data)` -- Update element by label
+- `deleteElementByLabel(collection, label)` -- Delete element by label
 
 ### Read (bulk)
 
 - `readScalarIntegers(collection, attribute)` -- Read all integer scalars
+- `readScalarBooleans(collection, attribute)` -- Read INTEGER-backed boolean scalars
 - `readScalarFloats(collection, attribute)` -- Read all float scalars
 - `readScalarStrings(collection, attribute)` -- Read all string scalars
 - `readVectorIntegers(collection, attribute)` -- Read all integer vectors
+- `readVectorBooleans(collection, attribute)` -- Read INTEGER-backed boolean vectors
 - `readVectorFloats(collection, attribute)` -- Read all float vectors
 - `readVectorStrings(collection, attribute)` -- Read all string vectors
 - `readSetIntegers(collection, attribute)` -- Read all integer sets
+- `readSetBooleans(collection, attribute)` -- Read INTEGER-backed boolean sets
 - `readSetFloats(collection, attribute)` -- Read all float sets
 - `readSetStrings(collection, attribute)` -- Read all string sets
 
 ### Read (by ID)
 
 - `readScalarIntegerById(collection, attribute, id)` -- Read integer or null
+- `readScalarBooleanById(collection, attribute, id)` -- Read INTEGER-backed boolean or null
 - `readScalarFloatById(collection, attribute, id)` -- Read float or null
 - `readScalarStringById(collection, attribute, id)` -- Read string or null
 - `readVectorIntegersById(collection, attribute, id)` -- Read integer vector
+- `readVectorBooleansById(collection, attribute, id)` -- Read INTEGER-backed boolean vector
 - `readVectorFloatsById(collection, attribute, id)` -- Read float vector
 - `readVectorStringsById(collection, attribute, id)` -- Read string vector
 - `readSetIntegersById(collection, attribute, id)` -- Read integer set
+- `readSetBooleansById(collection, attribute, id)` -- Read INTEGER-backed boolean set
 - `readSetFloatsById(collection, attribute, id)` -- Read float set
 - `readSetStringsById(collection, attribute, id)` -- Read string set
 
@@ -121,9 +130,11 @@ bun run example.ts
 
 - `queryString(sql, parameters?)` -- Query returning string or null
 - `queryInteger(sql, parameters?)` -- Query returning integer or null
+- `queryBoolean(sql, parameters?)` -- Query returning an INTEGER-backed boolean or null
 - `queryFloat(sql, parameters?)` -- Query returning float or null
 
-Parameters are passed as an array of `number | string | null`.
+Parameters are passed as an array of `number | boolean | string | null` (a `boolean` binds as the
+INTEGER 1 or 0).
 
 ### Transaction
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quiverdb",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/boolean.ts

@@ -0,0 +1,20 @@
+export function integerToBoolean(value: number, collection?: string, attribute?: string): boolean;
+export function integerToBoolean(value: null, collection?: string, attribute?: string): null;
+export function integerToBoolean(
+  value: number | null,
+  collection?: string,
+  attribute?: string,
+): boolean | null;
+export function integerToBoolean(
+  value: number | null,
+  collection?: string,
+  attribute?: string,
+): boolean | null {
+  if (value === null) return null;
+  if (value === 0) return false;
+  if (value === 1) return true;
+  const source = collection ? ` in '${collection}.${attribute}'` : "";
+  // A RangeError, not a QuiverError: the message is crafted here, not read from
+  // quiver_get_last_error — these readers are a binding-only convenience.
+  throw new RangeError(`Cannot convert integer ${value} to boolean${source}: expected 0 or 1`);
+}

package/src/create.ts

@@ -35,6 +35,12 @@ function setElementArray(
     return;
   }
 
+  if (typeof first === "boolean") {
+    const arr = allocNativeInt64((values as boolean[]).map((v) => (v ? 1 : 0)));
+    check(lib.quiver_element_set_array_integer(elemPtr, nameBuf.buf, arr.buf, values.length, null));
+    return;
+  }
+
   if (typeof first === "number") {
     const allIntegers = (values as number[]).every((v) => Number.isInteger(v));
     if (allIntegers) {
@@ -73,6 +79,11 @@ function setElementField(lib: Symbols, elemPtr: NativePointer, name: string, val
     return;
   }
 
+  if (typeof value === "boolean") {
+    check(lib.quiver_element_set_integer(elemPtr, nameBuf.buf, value ? 1n : 0n));
+    return;
+  }
+
   if (typeof value === "number") {
     if (Number.isInteger(value)) {
       check(lib.quiver_element_set_integer(elemPtr, nameBuf.buf, BigInt(value)));
@@ -148,12 +159,98 @@ Database.prototype.updateElement = function (
   }
 };
 
+/** Label-addressed counterpart of updateElement. */
+Database.prototype.updateElementByLabel = function (
+  this: Database,
+  collection: string,
+  label: string,
+  data: ElementData,
+): void {
+  const lib = getSymbols();
+  const handle = this._handle;
+
+  const outElem = allocPtrOut();
+  check(lib.quiver_element_create(outElem.buf));
+  const elemPtr = readPtrOut(outElem);
+
+  try {
+    for (const [key, value] of Object.entries(data)) {
+      if (value === undefined) continue;
+      setElementField(lib, elemPtr, key, value);
+    }
+    const collBuf = toCString(collection);
+    const labelBuf = toCString(label);
+    check(lib.quiver_database_update_element_by_label(handle, collBuf.buf, labelBuf.buf, elemPtr));
+  } finally {
+    lib.quiver_element_destroy(elemPtr);
+  }
+};
+
+/**
+ * Points one scalar foreign-key relation at the element labeled `targetLabel`; `null` clears it.
+ * The column is derived as `collectionTo.toLowerCase() + "_" + relationType`.
+ */
+Database.prototype.updateRelation = function (
+  this: Database,
+  collectionFrom: string,
+  collectionTo: string,
+  relationType: string,
+  id: number,
+  targetLabel: string | null,
+): void {
+  const lib = getSymbols();
+  check(
+    lib.quiver_database_update_relation(
+      this._handle,
+      toCString(collectionFrom).buf,
+      toCString(collectionTo).buf,
+      toCString(relationType).buf,
+      BigInt(id),
+      targetLabel === null ? null : toCString(targetLabel).buf,
+    ),
+  );
+};
+
+/** Label-addressed counterpart of updateRelation. */
+Database.prototype.updateRelationByLabel = function (
+  this: Database,
+  collectionFrom: string,
+  collectionTo: string,
+  relationType: string,
+  label: string,
+  targetLabel: string | null,
+): void {
+  const lib = getSymbols();
+  check(
+    lib.quiver_database_update_relation_by_label(
+      this._handle,
+      toCString(collectionFrom).buf,
+      toCString(collectionTo).buf,
+      toCString(relationType).buf,
+      toCString(label).buf,
+      targetLabel === null ? null : toCString(targetLabel).buf,
+    ),
+  );
+};
+
 Database.prototype.deleteElement = function (this: Database, collection: string, id: number): void {
   const lib = getSymbols();
   const collBuf = toCString(collection);
   check(lib.quiver_database_delete_element(this._handle, collBuf.buf, BigInt(id)));
 };
 
+/** Label-addressed counterpart of deleteElement. */
+Database.prototype.deleteElementByLabel = function (
+  this: Database,
+  collection: string,
+  label: string,
+): void {
+  const lib = getSymbols();
+  const collBuf = toCString(collection);
+  const labelBuf = toCString(label);
+  check(lib.quiver_database_delete_element_by_label(this._handle, collBuf.buf, labelBuf.buf));
+};
+
 /**
  * Replace all of an element's rows in one *named* vector group, from column arrays keyed by name.
  *
@@ -180,6 +277,25 @@ Database.prototype.updateVectorGroup = function (
   );
 };
 
+/** Label-addressed counterpart of updateVectorGroup. */
+Database.prototype.updateVectorGroupByLabel = function (
+  this: Database,
+  collection: string,
+  group: string,
+  label: string,
+  data: GroupColumns,
+): void {
+  updateGroupColumns(
+    this._handle,
+    "updateVectorGroupByLabel",
+    getSymbols().quiver_database_update_vector_group_by_label,
+    collection,
+    group,
+    label,
+    data,
+  );
+};
+
 /** Set-group counterpart of updateVectorGroup. */
 Database.prototype.updateSetGroup = function (
   this: Database,
@@ -198,3 +314,22 @@ Database.prototype.updateSetGroup = function (
     data,
   );
 };
+
+/** Label-addressed counterpart of updateSetGroup. */
+Database.prototype.updateSetGroupByLabel = function (
+  this: Database,
+  collection: string,
+  group: string,
+  label: string,
+  data: GroupColumns,
+): void {
+  updateGroupColumns(
+    this._handle,
+    "updateSetGroupByLabel",
+    getSymbols().quiver_database_update_set_group_by_label,
+    collection,
+    group,
+    label,
+    data,
+  );
+};

package/src/database.ts

@@ -64,6 +64,17 @@ export class Database {
     return new Database(readPtrOut(outDb));
   }
 
+  /**
+   * Applies every migration's up.sql in order, then every down.sql in reverse.
+   * Throws on failure, including a round trip that leaves any table behind.
+   */
+  static validateMigrations(migrationsPath: string): void {
+    const lib = getSymbols();
+    const migrPathBuf = toCString(migrationsPath);
+
+    check(lib.quiver_database_validate_migrations(migrPathBuf.buf));
+  }
+
   close(): void {
     if (this._closed) return;
     const lib = getSymbols();
@@ -86,10 +97,27 @@ export class Database {
   // --- Element CRUD (implemented in create.ts) ---
   declare createElement: (collection: string, data: ElementData) => number;
   declare updateElement: (collection: string, id: number, data: ElementData) => void;
+  declare updateElementByLabel: (collection: string, label: string, data: ElementData) => void;
   declare deleteElement: (collection: string, id: number) => void;
+  declare deleteElementByLabel: (collection: string, label: string) => void;
+  declare updateRelation: (
+    collectionFrom: string,
+    collectionTo: string,
+    relationType: string,
+    id: number,
+    targetLabel: string | null,
+  ) => void;
+  declare updateRelationByLabel: (
+    collectionFrom: string,
+    collectionTo: string,
+    relationType: string,
+    label: string,
+    targetLabel: string | null,
+  ) => void;
 
   // --- Reads (implemented in read.ts) ---
   declare readScalarIntegers: (collection: string, attribute: string) => (number | null)[];
+  declare readScalarBooleans: (collection: string, attribute: string) => (boolean | null)[];
   declare readScalarFloats: (collection: string, attribute: string) => (number | null)[];
   declare readScalarStrings: (collection: string, attribute: string) => (string | null)[];
   declare readScalarIntegerById: (
@@ -97,6 +125,11 @@ export class Database {
     attribute: string,
     id: number,
   ) => number | null;
+  declare readScalarBooleanById: (
+    collection: string,
+    attribute: string,
+    id: number,
+  ) => boolean | null;
   declare readScalarFloatById: (collection: string, attribute: string, id: number) => number | null;
   declare readScalarStringById: (
     collection: string,
@@ -106,21 +139,26 @@ export class Database {
   declare readElementIds: (collection: string) => number[];
   declare numberOfElements: (collection: string) => number;
   declare readVectorIntegers: (collection: string, attribute: string) => number[][];
+  declare readVectorBooleans: (collection: string, attribute: string) => boolean[][];
   declare readVectorFloats: (collection: string, attribute: string) => number[][];
   declare readVectorStrings: (collection: string, attribute: string) => string[][];
   declare readVectorIntegersById: (collection: string, attribute: string, id: number) => number[];
+  declare readVectorBooleansById: (collection: string, attribute: string, id: number) => boolean[];
   declare readVectorFloatsById: (collection: string, attribute: string, id: number) => number[];
   declare readVectorStringsById: (collection: string, attribute: string, id: number) => string[];
   declare readSetIntegers: (collection: string, attribute: string) => number[][];
+  declare readSetBooleans: (collection: string, attribute: string) => boolean[][];
   declare readSetFloats: (collection: string, attribute: string) => number[][];
   declare readSetStrings: (collection: string, attribute: string) => string[][];
   declare readSetIntegersById: (collection: string, attribute: string, id: number) => number[];
+  declare readSetBooleansById: (collection: string, attribute: string, id: number) => boolean[];
   declare readSetFloatsById: (collection: string, attribute: string, id: number) => number[];
   declare readSetStringsById: (collection: string, attribute: string, id: number) => string[];
 
   // --- Queries (implemented in query.ts) ---
   declare queryString: (sql: string, parameters?: QueryParam[]) => string | null;
   declare queryInteger: (sql: string, parameters?: QueryParam[]) => number | null;
+  declare queryBoolean: (sql: string, parameters?: QueryParam[]) => boolean | null;
   declare queryFloat: (sql: string, parameters?: QueryParam[]) => number | null;
 
   // --- Transactions (implemented in transaction.ts) ---
@@ -156,24 +194,48 @@ export class Database {
     id: number,
     data: TimeSeriesData,
   ) => void;
+  declare updateTimeSeriesGroupByLabel: (
+    collection: string,
+    group: string,
+    label: string,
+    data: TimeSeriesData,
+  ) => void;
   declare updateVectorGroup: (
     collection: string,
     group: string,
     id: number,
     data: GroupColumns,
   ) => void;
+  declare updateVectorGroupByLabel: (
+    collection: string,
+    group: string,
+    label: string,
+    data: GroupColumns,
+  ) => void;
   declare updateSetGroup: (
     collection: string,
     group: string,
     id: number,
     data: GroupColumns,
   ) => void;
+  declare updateSetGroupByLabel: (
+    collection: string,
+    group: string,
+    label: string,
+    data: GroupColumns,
+  ) => void;
   declare upsertTimeSeriesRow: (
     collection: string,
     group: string,
     id: number,
     row: Record<string, number | bigint | string>,
   ) => void;
+  declare upsertTimeSeriesRowByLabel: (
+    collection: string,
+    group: string,
+    label: string,
+    row: Record<string, number | bigint | string>,
+  ) => void;
   declare hasTimeSeriesFiles: (collection: string) => boolean;
   declare listTimeSeriesFilesColumns: (collection: string) => string[];
   declare readTimeSeriesFiles: (collection: string) => Record<string, string | null>;

package/src/group-columns.ts

@@ -15,13 +15,14 @@ export type GroupColumns = Record<string, (number | string | null)[]>;
 
 /**
  * The parallel-array signature every columnar group update C function shares
- * (quiver_database_update_{time_series,vector,set}_group).
+ * (quiver_database_update_{time_series,vector,set}_group and their _by_label forms). The 4th
+ * argument addresses the element: an id for the by-id forms, a NUL-terminated label otherwise.
  */
 type ColumnUpdateFn = (
   db: NativePointer,
   collection: Uint8Array,
   group: Uint8Array,
-  id: bigint,
+  key: bigint | Uint8Array,
   names: Uint8Array | null,
   types: Uint8Array | null,
   data: Uint8Array | null,
@@ -32,8 +33,8 @@ type ColumnUpdateFn = (
 
 /**
  * Marshal a column-oriented payload and forward it to one of the columnar group update C
- * functions. Shared by updateTimeSeriesGroup / updateVectorGroup / updateSetGroup: the three
- * differ only in which C entry point they call.
+ * functions. Shared by updateTimeSeriesGroup / updateVectorGroup / updateSetGroup and their
+ * _by_label counterparts: they differ only in which C entry point they call.
  *
  * Pass `{}` (no columns) to clear the group.
  */
@@ -43,15 +44,16 @@ export function updateGroupColumns(
   update: ColumnUpdateFn,
   collection: string,
   group: string,
-  id: number,
+  key: number | string,
   data: GroupColumns,
 ): void {
   const collBuf = toCString(collection);
   const grpBuf = toCString(group);
+  const keyArg = typeof key === "string" ? toCString(key).buf : BigInt(key);
   const entries = Object.entries(data);
 
   if (entries.length === 0) {
-    check(update(handle, collBuf.buf, grpBuf.buf, BigInt(id), null, null, null, null, 0n, 0n));
+    check(update(handle, collBuf.buf, grpBuf.buf, keyArg, null, null, null, null, 0n, 0n));
     return;
   }
 
@@ -149,7 +151,7 @@ export function updateGroupColumns(
       handle,
       collBuf.buf,
       grpBuf.buf,
-      BigInt(id),
+      keyArg,
       namesTable.buf,
       typesAlloc.buf,
       dataTable.buf,

package/src/loader.ts

@@ -35,6 +35,7 @@ const lifecycleSymbols = {
   // struct in JS.
   quiver_database_from_schema: { args: [BUF, BUF, BUF, P], returns: I32 },
   quiver_database_from_migrations: { args: [BUF, BUF, BUF, P], returns: I32 },
+  quiver_database_validate_migrations: { args: [BUF], returns: I32 },
   quiver_database_open: { args: [BUF, BUF, P], returns: I32 },
   quiver_database_close: { args: [P], returns: I32 },
   quiver_database_is_healthy: { args: [P, P], returns: I32 },
@@ -58,7 +59,11 @@ const elementSymbols = {
 const crudSymbols = {
   quiver_database_create_element: { args: [P, BUF, P, P], returns: I32 },
   quiver_database_update_element: { args: [P, BUF, I64, P], returns: I32 },
+  quiver_database_update_element_by_label: { args: [P, BUF, BUF, P], returns: I32 },
   quiver_database_delete_element: { args: [P, BUF, I64], returns: I32 },
+  quiver_database_delete_element_by_label: { args: [P, BUF, BUF], returns: I32 },
+  quiver_database_update_relation: { args: [P, BUF, BUF, BUF, I64, BUF], returns: I32 },
+  quiver_database_update_relation_by_label: { args: [P, BUF, BUF, BUF, BUF, BUF], returns: I32 },
 } as const;
 
 const readSymbols = {
@@ -131,18 +136,34 @@ const timeSeriesSymbols = {
     args: [P, BUF, BUF, I64, P, P, P, USIZE],
     returns: I32,
   },
+  quiver_database_upsert_time_series_row_by_label: {
+    args: [P, BUF, BUF, BUF, P, P, P, USIZE],
+    returns: I32,
+  },
   quiver_database_update_time_series_group: {
     args: [P, BUF, BUF, I64, P, P, P, P, USIZE, USIZE],
     returns: I32,
   },
+  quiver_database_update_time_series_group_by_label: {
+    args: [P, BUF, BUF, BUF, P, P, P, P, USIZE, USIZE],
+    returns: I32,
+  },
   quiver_database_update_vector_group: {
     args: [P, BUF, BUF, I64, P, P, P, P, USIZE, USIZE],
     returns: I32,
   },
+  quiver_database_update_vector_group_by_label: {
+    args: [P, BUF, BUF, BUF, P, P, P, P, USIZE, USIZE],
+    returns: I32,
+  },
   quiver_database_update_set_group: {
     args: [P, BUF, BUF, I64, P, P, P, P, USIZE, USIZE],
     returns: I32,
   },
+  quiver_database_update_set_group_by_label: {
+    args: [P, BUF, BUF, BUF, P, P, P, P, USIZE, USIZE],
+    returns: I32,
+  },
   quiver_database_free_time_series_data: { args: [P, P, P, P, USIZE, USIZE], returns: I32 },
   quiver_database_has_time_series_files: { args: [P, BUF, P], returns: I32 },
   quiver_database_list_time_series_files_columns: { args: [P, BUF, P, P], returns: I32 },

package/src/lua-api.ts

@@ -10,8 +10,9 @@
 // and whether the prose is semantically true.
 //
 // NOTE: the binary/expression subsystems are bound in the native binding and documented below.
-// File-touching operations (db:open_file, db:bin_to_csv, db:csv_to_bin, expr:save) are sandboxed
-// to the database file's directory; the pure-metadata builders stay under the quiver.* global.
+// File-touching operations (db:open_file, db:bin_to_csv, db:csv_to_bin, db:validate_migrations,
+// expr:save) are sandboxed to the database file's directory; the pure-metadata builders stay under
+// the quiver.* global.
 //
 // FORMAT CONVENTION: every db: method appears at least once as the literal token
 // `db:<snake_case_name>`, and every quiver.* function as `quiver.<name>`, so coverage is greppable
@@ -50,7 +51,7 @@ Lua values map to Quiver column values as follows:
 | integer            | INTEGER      | Also accepted for REAL columns (coerced to real). |
 | number (float)     | REAL         | A float is rejected for an INTEGER column.     |
 | string             | TEXT         | Also used for \`date_time\` columns (ISO 8601).  |
-| \`nil\`              | NULL         | In query params, file paths, and ts rows.      |
+| \`nil\`              | NULL         | In query params, file paths, ts rows, relations.|
 | table (1-indexed)  | array        | Used for vectors/sets and column-oriented data.|
 
 **Unsupported types throw.** Passing a boolean, a function, or a nested table where a scalar is
@@ -59,15 +60,21 @@ attributes, time-series rows, and query parameters. A skipped positional query p
 shift every later parameter and bind NULL to the trailing placeholder, so this is rejected loudly.
 
 Dates are plain strings in ISO 8601 format: \`YYYY-MM-DDTHH:MM:SS\`. (Lua keeps a string-based
-datetime surface — there are no DateTime wrapper helpers, unlike Julia/Dart/Python.)
+datetime surface — there are no DateTime wrapper helpers, unlike Julia/Dart/Python.) The time part
+is optional, so \`"2024-01-15"\` is also valid, and a space may replace the \`T\`. Every field is
+fixed-width and zero-padded. Anything shorter or malformed — \`"2005"\`, \`"2005-01"\`,
+\`"2024-02-31"\`, \`"2024-1-5"\`, \`"2024-01-15T10:30"\` — is **rejected when you write it**, not
+silently stored. The value is stored exactly as written; a date-only value is not padded to
+midnight.
 
 ---
 
 ## Critical rules
 
 - **Type coercion.** An integer is accepted for a REAL column (coerced to real on insert); a float
-  is rejected for an INTEGER column. Other type mismatches raise a validation error and roll the
-  whole script back.
+  is rejected for an INTEGER column. A string bound to a \`date_*\` column must parse as ISO 8601
+  (\`YYYY-MM-DD\`, optionally \`THH:MM:SS\` or \` HH:MM:SS\`). Other type mismatches raise a
+  validation error and roll the whole script back.
 - **Errors abort the script.** Any error thrown by a \`db:\` call stops the script and surfaces as
   \`Failed to run Lua script: <message>\`. Validation failures roll back whatever the current
   transaction covered.
@@ -76,16 +83,16 @@ datetime surface — there are no DateTime wrapper helpers, unlike Julia/Dart/Py
   and \`dofile\`/\`loadfile\` are removed (string-form \`load\` stays available). Integer division is
   the Lua 5.4 \`//\` operator — a language operator, unrelated to \`math\`.
 - **Filesystem sandbox.** Every file-touching operation (\`db:export_csv\`, \`db:import_csv\`,
-  \`db:open_file\`, \`db:bin_to_csv\`, \`db:csv_to_bin\`, \`expr:save\`) resolves relative paths against
-  the directory containing the database file and rejects anything outside it (subdirectories are
-  fine; \`..\` escapes and outside absolute paths throw \`Cannot <op>: path '...' escapes the
+  \`db:open_file\`, \`db:bin_to_csv\`, \`db:csv_to_bin\`, \`db:validate_migrations\`, \`expr:save\`) resolves
+  relative paths against the directory containing the database file and rejects anything outside it
+  (subdirectories are fine; \`..\` escapes and outside absolute paths throw \`Cannot <op>: path '...' escapes the
   database directory ...\`). On an in-memory database these operations throw
   \`Cannot <op>: database is in-memory, file operations are unavailable\`.
 - **Output.** A script can \`return\` one value and the host receives it as JSON — prefer this over
   \`print()\` when you need structured data back (\`print()\` still works and is captured). Only the
   **first** returned value is encoded. Arrays are 1-indexed (iterate with \`ipairs\`); reading a NULL
   yields \`nil\`, writing \`nil\` stores NULL where NULL is accepted (query params, ts rows, file
-  columns — but NOT element scalar attributes; see CRUD).
+  columns, relation targets — but NOT element scalar attributes; see CRUD).
 
   \`\`\`lua
   return { ids = db:read_element_ids("Collection"), total = 3 }
@@ -134,10 +141,15 @@ db:describe()                      -- string: whole-DB text report (returns it,
 db:describe_collection(collection) -- string: one collection's structure (text report)
 db:summarize_collection(collection)-- string: per-scalar null/non-null counts, low-cardinality
                                    --         integer value distributions, per-group sizes
+db:validate_migrations(path)       -- validate a migrations dir (up then down) in-memory; no return
 \`\`\`
 
 All three \`describe*\`/\`summarize*\` methods **return** a string — \`print()\` it to see it.
 
+\`db:validate_migrations(path)\` applies every \`up.sql\` in version order, then every \`down.sql\` in
+reverse, against a throwaway in-memory database — nothing in \`db\` itself is touched. The round trip
+must end with an empty database; leftover tables are named in the error.
+
 ---
 
 ## Transactions
@@ -212,7 +224,12 @@ Rules worth knowing:
 \`\`\`lua
 local id = db:create_element(collection, element_table)   -- returns new integer id
 db:update_element(collection, id, element_table)
+db:update_element_by_label(collection, label, element_table)  -- same update, addressed by label
 db:delete_element(collection, id)
+db:delete_element_by_label(collection, label)             -- same delete, addressed by label
+
+db:update_relation(collection_from, collection_to, relation_type, id, target_label)
+db:update_relation_by_label(collection_from, collection_to, relation_type, label, target_label)
 \`\`\`
 
 The element table holds scalar attributes as \`key = value\`, and vector/set attributes as
@@ -238,6 +255,13 @@ Notes:
 - **\`update_element\` / \`delete_element\` require an existing id.** Targeting an id that does not
   exist throws \`Element not found: <id> in collection '<collection>'\` (no silent no-op). Use
   \`read_element_ids\` to get valid ids.
+- **\`update_element_by_label\` / \`delete_element_by_label\` require an existing label**, unique
+  *per collection*, not per database — one naming an element of another collection does not
+  resolve. A miss throws \`Element not found: label '<label>' in collection '<collection>'\` and
+  changes nothing. Passing \`label = "New name"\` in the element table renames the element, after
+  which only the new label resolves. Because the label form delegates to the id form, failures
+  that validate the *element* (an empty table, a type mismatch) report
+  \`Cannot update_element: ...\`.
 - **Empty arrays are skipped.** An attribute whose value is \`{}\` writes no vector/set (the element
   type can't be inferred from an empty array), so it is silently dropped.
 - **No \`nil\` scalar attributes.** In Lua a key set to \`nil\` is dropped from the table, so
@@ -245,7 +269,18 @@ Notes:
   **throws** (\`...must have at least one scalar attribute\` on create, \`...at least one attribute
   to update\` on update). To leave a column unchanged, omit the key — you cannot set a scalar to
   NULL via the element table. (\`nil\` → NULL is only accepted by
-  \`upsert_time_series_row\` and \`update_time_series_files\`.)
+  \`upsert_time_series_row\`, \`update_time_series_files\` and \`update_relation\`.)
+- **\`update_relation\` points one scalar foreign-key relation at another element**, named by the
+  target's label. The column is derived from the naming convention —
+  \`lowercase(collection_to) .. "_" .. relation_type\`, so
+  \`db:update_relation("Child", "Parent", "id", id, "Parent A")\` writes \`Child.parent_id\`. A
+  \`nil\` or omitted \`target_label\` clears the relation; anything that is not a string throws
+  (\`target_label has unsupported Lua type\`). The derived column must exist and be a
+  foreign key to \`collection_to\`, otherwise \`Cannot update_relation: ...\`. The write delegates
+  to \`update_element\`, so a missing id reports that method's error;
+  \`update_relation_by_label\` takes a label in place of the id, with
+  \`update_element_by_label\`'s resolution and miss semantics. A relation living in a vector, set
+  or time-series group is a list of targets — use that group's writer instead.
 
 ---
 
@@ -295,6 +330,9 @@ db:update_vector_group("Child", "refs", id, { parent_ref = { 1, 2, 3 } })
 db:update_set_group("Child", "parents", id, { parent_ref = { 1, 2 } })
 
 db:update_vector_group("Child", "refs", id, {})   -- clears the group
+
+db:update_vector_group_by_label("Child", "refs", "Child 1", { parent_ref = { 1, 2 } })
+db:update_set_group_by_label("Child", "parents", "Child 1", { parent_ref = { 1, 2 } })
 \`\`\`
 
 Use these instead of routing a group's columns through \`update_element\` whenever a column name is
@@ -311,7 +349,8 @@ Rules:
   are rejected if passed.
 - **Foreign-key columns accept a label string** and resolve it to the referenced id, exactly as in
   \`create_element\` / \`update_element\`.
-- The element id must exist, same as \`update_element\` / \`delete_element\`.
+- The element id must exist, same as \`update_element\` / \`delete_element\`; the \`_by_label\` form
+  takes a label in its place, with \`update_element_by_label\`'s resolution and miss semantics.
 
 ---
 
@@ -372,6 +411,8 @@ db:update_time_series_group("Items", "data", id, {
 })
 
 db:update_time_series_group("Items", "data", id, {})   -- clears the group
+
+db:update_time_series_group_by_label("Items", "data", "Item 1", { date_time = { "2024-01-01T00:00:00" }, value = { 10.5 } })
 \`\`\`
 
 A read-modify-write looks like this:
@@ -401,6 +442,8 @@ column names). Each value of the top-level table must be an **array**, not a sca
   table {} to clear the group\`) — only a bare \`{}\` clears.
 - Integer values are accepted for REAL columns (converted on insert). Booleans, functions, and
   other unsupported Lua types throw \`column '...' has unsupported Lua type\`.
+- The element id must exist; the \`_by_label\` form takes a label in its place, with
+  \`update_element_by_label\`'s resolution and miss semantics. Every rule above applies to both.
 
 ### Append/upsert a single row (\`upsert_time_series_row\` — ROW-oriented, the one exception)
 
@@ -412,8 +455,16 @@ db:upsert_time_series_row("Items", "data", id, {
     date_time = "2024-01-04T00:00:00",
     value     = 40.0,
 })
+
+db:upsert_time_series_row_by_label("Items", "data", "Item 1", {
+    date_time = "2024-01-04T00:00:00",
+    value     = 40.0,
+})
 \`\`\`
 
+The element id must exist; the \`_by_label\` form takes a label in its place, with
+\`update_element_by_label\`'s resolution and miss semantics.
+
 ---
 
 ## Time series files

package/src/query.ts

@@ -1,4 +1,5 @@
 import { ptr } from "bun:ffi";
+import { integerToBoolean } from "./boolean.ts";
 import { Database } from "./database.ts";
 import { check, QuiverError } from "./errors.ts";
 import {
@@ -38,6 +39,11 @@ function marshalParams(parameters: QueryParam[]): {
     if (p === null) {
       typesDv.setInt32(i * 4, DATA_TYPE_NULL, true);
       valuesDv.setBigInt64(i * 8, 0n, true);
+    } else if (typeof p === "boolean") {
+      typesDv.setInt32(i * 4, DATA_TYPE_INTEGER, true);
+      const native = allocNativeInt64([p ? 1 : 0]);
+      keepalive.push(native);
+      valuesDv.setBigInt64(i * 8, nativeAddress(native.ptr), true);
     } else if (typeof p === "number") {
       if (Number.isInteger(p)) {
         typesDv.setInt32(i * 4, DATA_TYPE_INTEGER, true);
@@ -130,6 +136,14 @@ Database.prototype.queryInteger = function (
   return Number(new DataView(outValue.buffer).getBigInt64(0, true));
 };
 
+Database.prototype.queryBoolean = function (
+  this: Database,
+  sql: string,
+  parameters?: QueryParam[],
+): boolean | null {
+  return integerToBoolean(this.queryInteger(sql, parameters));
+};
+
 Database.prototype.queryFloat = function (
   this: Database,
   sql: string,

package/src/read.ts

@@ -1,4 +1,5 @@
 import { CString, type Pointer, toArrayBuffer } from "bun:ffi";
+import { integerToBoolean } from "./boolean.ts";
 import { Database } from "./database.ts";
 import { check } from "./errors.ts";
 import {
@@ -52,6 +53,16 @@ Database.prototype.readScalarIntegers = function (
   return result;
 };
 
+Database.prototype.readScalarBooleans = function (
+  this: Database,
+  collection: string,
+  attribute: string,
+): (boolean | null)[] {
+  return this.readScalarIntegers(collection, attribute).map((value) =>
+    integerToBoolean(value, collection, attribute),
+  );
+};
+
 Database.prototype.readScalarFloats = function (
   this: Database,
   collection: string,
@@ -143,6 +154,19 @@ Database.prototype.readScalarIntegerById = function (
   return Number(new DataView(outValBuf.buffer).getBigInt64(0, true));
 };
 
+Database.prototype.readScalarBooleanById = function (
+  this: Database,
+  collection: string,
+  attribute: string,
+  id: number,
+): boolean | null {
+  return integerToBoolean(
+    this.readScalarIntegerById(collection, attribute, id),
+    collection,
+    attribute,
+  );
+};
+
 Database.prototype.readScalarFloatById = function (
   this: Database,
   collection: string,
@@ -342,6 +366,19 @@ Database.prototype.readVectorIntegers = function (
     attribute,
   );
 };
+/**
+ * NULL cells are dropped and only elements that own rows are returned, so the result is not
+ * positionally aligned with `readElementIds` (unlike `readScalarBooleans`).
+ */
+Database.prototype.readVectorBooleans = function (
+  this: Database,
+  collection: string,
+  attribute: string,
+): boolean[][] {
+  return this.readVectorIntegers(collection, attribute).map((values) =>
+    values.map((value) => integerToBoolean(value, collection, attribute)),
+  );
+};
 Database.prototype.readVectorFloats = function (
   this: Database,
   collection: string,
@@ -381,6 +418,16 @@ Database.prototype.readSetIntegers = function (
     attribute,
   );
 };
+/** Same alignment caveat as `readVectorBooleans`: NULL cells dropped, only ids that own rows. */
+Database.prototype.readSetBooleans = function (
+  this: Database,
+  collection: string,
+  attribute: string,
+): boolean[][] {
+  return this.readSetIntegers(collection, attribute).map((values) =>
+    values.map((value) => integerToBoolean(value, collection, attribute)),
+  );
+};
 Database.prototype.readSetFloats = function (
   this: Database,
   collection: string,
@@ -515,6 +562,16 @@ Database.prototype.readVectorIntegersById = function (
     id,
   );
 };
+Database.prototype.readVectorBooleansById = function (
+  this: Database,
+  collection: string,
+  attribute: string,
+  id: number,
+): boolean[] {
+  return this.readVectorIntegersById(collection, attribute, id).map((value) =>
+    integerToBoolean(value, collection, attribute),
+  );
+};
 Database.prototype.readVectorFloatsById = function (
   this: Database,
   collection: string,
@@ -560,6 +617,16 @@ Database.prototype.readSetIntegersById = function (
     id,
   );
 };
+Database.prototype.readSetBooleansById = function (
+  this: Database,
+  collection: string,
+  attribute: string,
+  id: number,
+): boolean[] {
+  return this.readSetIntegersById(collection, attribute, id).map((value) =>
+    integerToBoolean(value, collection, attribute),
+  );
+};
 Database.prototype.readSetFloatsById = function (
   this: Database,
   collection: string,

package/src/time-series.ts

@@ -18,7 +18,7 @@ import {
   toCString,
 } from "./ffi-helpers.ts";
 import { updateGroupColumns } from "./group-columns.ts";
-import { getSymbols } from "./loader.ts";
+import { getSymbols, type NativePointer } from "./loader.ts";
 import {
   type Allocation,
   DATA_TYPE_DATE_TIME,
@@ -200,16 +200,57 @@ Database.prototype.updateTimeSeriesGroup = function (
   );
 };
 
-Database.prototype.upsertTimeSeriesRow = function (
+/** Label-addressed counterpart of updateTimeSeriesGroup. */
+Database.prototype.updateTimeSeriesGroupByLabel = function (
   this: Database,
   collection: string,
   group: string,
-  id: number,
+  label: string,
+  data: TimeSeriesData,
+): void {
+  updateGroupColumns(
+    this._handle,
+    "updateTimeSeriesGroupByLabel",
+    getSymbols().quiver_database_update_time_series_group_by_label,
+    collection,
+    group,
+    label,
+    data,
+  );
+};
+
+/**
+ * The parallel-array signature both row-oriented time-series upsert C functions share
+ * (quiver_database_upsert_time_series_row and its _by_label form). `key` is an id for the by-id
+ * form, a NUL-terminated label otherwise.
+ */
+type UpsertRowFn = (
+  db: NativePointer,
+  collection: Uint8Array,
+  group: Uint8Array,
+  key: bigint | Uint8Array,
+  names: Uint8Array | null,
+  types: Uint8Array | null,
+  data: Uint8Array | null,
+  columnCount: bigint,
+) => number;
+
+/**
+ * Marshal a single row of scalars and forward it to one of the row-oriented time-series upsert
+ * C functions. Shared by upsertTimeSeriesRow / upsertTimeSeriesRowByLabel: they differ only in
+ * which C entry point they call and whether `key` is an id or a label.
+ */
+function upsertRowColumns(
+  handle: NativePointer,
+  upsert: UpsertRowFn,
+  collection: string,
+  group: string,
+  key: number | string,
   row: Record<string, number | bigint | string>,
 ): void {
-  const lib = getSymbols();
   const collBuf = toCString(collection);
   const grpBuf = toCString(group);
+  const keyArg = typeof key === "string" ? toCString(key).buf : BigInt(key);
   const entries = Object.entries(row);
   const columnCount = entries.length;
   const keepalive: Allocation[] = [];
@@ -248,17 +289,52 @@ Database.prototype.upsertTimeSeriesRow = function (
   keepalive.push(dataTable);
 
   check(
-    lib.quiver_database_upsert_time_series_row(
-      this._handle,
+    upsert(
+      handle,
       collBuf.buf,
       grpBuf.buf,
-      BigInt(id),
+      keyArg,
       namesTable.buf,
       typesAlloc.buf,
       dataTable.buf,
       BigInt(columnCount),
     ),
   );
+}
+
+Database.prototype.upsertTimeSeriesRow = function (
+  this: Database,
+  collection: string,
+  group: string,
+  id: number,
+  row: Record<string, number | bigint | string>,
+): void {
+  upsertRowColumns(
+    this._handle,
+    getSymbols().quiver_database_upsert_time_series_row,
+    collection,
+    group,
+    id,
+    row,
+  );
+};
+
+/** Label-addressed counterpart of upsertTimeSeriesRow. */
+Database.prototype.upsertTimeSeriesRowByLabel = function (
+  this: Database,
+  collection: string,
+  group: string,
+  label: string,
+  row: Record<string, number | bigint | string>,
+): void {
+  upsertRowColumns(
+    this._handle,
+    getSymbols().quiver_database_upsert_time_series_row_by_label,
+    collection,
+    group,
+    label,
+    row,
+  );
 };
 
 Database.prototype.hasTimeSeriesFiles = function (this: Database, collection: string): boolean {

package/src/types.ts

@@ -21,11 +21,12 @@ export type DatabaseOptions = {
   consoleLevel?: number;
 };
 
-export type ScalarValue = number | bigint | string | null;
-export type ArrayValue = number[] | bigint[] | string[];
+/** A `boolean` is stored as the INTEGER 1 or 0 (see `readScalarBooleans` for the read side). */
+export type ScalarValue = number | bigint | boolean | string | null;
+export type ArrayValue = number[] | bigint[] | boolean[] | string[];
 export type Value = ScalarValue | ArrayValue;
 export type ElementData = Record<string, Value | undefined>;
-export type QueryParam = number | string | null;
+export type QueryParam = number | boolean | string | null;
 
 /** Native memory allocation result. Callers MUST hold `buf` in scope to prevent GC. */
 export type Allocation = {