@terrascale/sdk 0.0.5 → 0.0.6

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.0.6 — relational SQL
+
+`db.execute(sql, args)`, `db.query(sql, args)` and `db.batch(statements)` call
+TerraBase's `POST /v1/projects/{project}/databases/{database}/sql/execute`.
+Each request is one transaction. Results are typed
+`{ columns, rows, rowsAffected, lastInsertRowid }`; a refused statement throws
+`SqlError` (a `TerraBaseV1Error`) with `statement` and `sqliteCode`. The
+read-only `db.sql` route is unchanged.
+
 ## Unreleased — collection TTL and vector near sort
 
 `collection.putTtl(path)`, `getTtl()` and `deleteTtl()` call

package/README.md

@@ -110,7 +110,8 @@ OpenAPI and immutable release qualification remain open gates.
 | Collections and declared JSON Schema | `db.collections.create/get/list/drop`; `collection.getSchema/putSchema/deleteSchema` |
 | Collection TTL | `collection.putTtl/getTtl/deleteTtl` |
 | Databases | `client.databases.create/list/get/update/delete/branch` |
-| SQL | `db.sql/checkSql/explainSql` |
+| Relational SQL | `db.execute/query/batch` |
+| Read-only SQL (older) | `db.sql/checkSql/explainSql` |
 | Changes | `db.changes` (SSE async iterator) |
 | Export | `db.export` (NDJSON async iterator) |
 
@@ -161,6 +162,37 @@ or replay mutations after an uncertain result; this release does not promise
 mutation deduplication. Validation, authentication, authorization and
 precondition failures are not automatically retried.
 
+Relational SQL runs statements on tables created with `CREATE TABLE` (rows
+are documents). `execute` runs one statement, `query` returns its rows as
+objects keyed by column name, and `batch` sends 1 to 256 statements as one
+transaction: all commit or none do. `BEGIN`, `COMMIT` and `ROLLBACK` are
+refused. Arguments are positional (`?`) or named (`:name`, `@name`, `$name`,
+passed without the prefix). Each is `null`, a number, an int64 `bigint`, a
+boolean (stored as 1 or 0) or a string. Reads need `documents:read`; writes and
+DDL also need `documents:write`.
+
+```js
+await db.batch([
+  "CREATE TABLE people (id INTEGER PRIMARY KEY, name TEXT NOT NULL)",
+  { sql: "INSERT INTO people (id, name) VALUES (?, ?)", args: [1, "Ada"] },
+  { sql: "INSERT INTO people (id, name) VALUES (:id, :name)", named: { id: 2, name: "Grace" } },
+]);
+const people = await db.query("SELECT id, name FROM people WHERE id > ?", [0]);
+const { columns, rows, rowsAffected, lastInsertRowid } = await db.execute("DELETE FROM people WHERE id = :id", { id: 2 });
+```
+
+A refused statement throws `SqlError`, a `TerraBaseV1Error` that adds
+`statement` (zero-based index) and `sqliteCode` (such as
+`SQLITE_CONSTRAINT_PRIMARYKEY`). Its `code` is `sql_error` (400),
+`forbidden_scope` (403), `sql_conflict` (409) or `sql_too_large` (413).
+Authentication, quota and availability errors keep their usual error classes.
+
+TerraBase sends integers as JSON numbers. A plain JavaScript number cannot hold
+an integer above 2^53 exactly, so the SDK decodes such a value (a row value or
+`lastInsertRowid`) as an `ExactDecimal` that keeps every digit. Convert it with
+`BigInt(String(value))`. Pass large integer arguments as `bigint`.
+
+The older `db.sql` route below is read-only.
 SQL is the producer's bounded read-only subset: `{ matched, truncated, rows }`,
 with row `{ id, value }` and no pagination cursor. `checkSql` returns `ok: false`
 for invalid SQL; `explainSql` returns an HTTP error for invalid SQL. All three

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terrascale/sdk",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "JavaScript SDK, typed with JSDoc, for project-scoped C# TerraBase v1 and hosted TerraScale identity.",
   "type": "module",
   "license": "Apache-2.0",

package/sdk-public-v1-route-manifest.json

@@ -71,6 +71,7 @@
     {"method":"PUT","path":"/v1/projects/{project}/databases/{database}/schema/{collection}","operation":"declareCollectionSchema","scopes":["databases:write"],"requestMediaTypes":["application/json"],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Schema/PutCollectionSchemaEndpoint.cs","request":"UniqueSchemaRequest"},
     {"method":"POST","path":"/v1/projects/{project}/databases/{database}/sql","operation":"runSql","scopes":["databases:read"],"requestMediaTypes":["application/json"],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Queries/RunSqlEndpoint.cs","request":"SqlRequest"},
     {"method":"POST","path":"/v1/projects/{project}/databases/{database}/sql/check","operation":"checkSql","scopes":["databases:read"],"requestMediaTypes":["application/json"],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Queries/CheckSqlEndpoint.cs","request":"SqlRequest"},
+    {"method":"POST","path":"/v1/projects/{project}/databases/{database}/sql/execute","operation":"executeSql","scopes":["documents:read"],"requestMediaTypes":["application/json"],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Sql/SqlExecuteEndpoint.cs","request":"SqlExecuteRequest","producerChange":"TerraScale/terrascale#420"},
     {"method":"POST","path":"/v1/projects/{project}/databases/{database}/sql/explain","operation":"explainSql","scopes":["databases:read"],"requestMediaTypes":["application/json"],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Queries/ExplainSqlEndpoint.cs","request":"SqlRequest"},
     {"method":"POST","path":"/v1/projects/{project}/databases/{database}/transactions","operation":"runTransaction","scopes":["documents:write"],"requestMediaTypes":["application/json"],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Documents/TransactionEndpoint.cs","request":"TransactionRequest"},
     {"method":"GET","path":"/v1/projects/{project}/databases/{database}/usage","operation":"getDatabaseUsage","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Usage/GetDatabaseUsageEndpoint.cs","request":"none"},
@@ -80,6 +81,10 @@
     {"method":"DELETE","path":"/v1/projects/{project}/saved-queries/{query}","operation":"deleteSavedQuery","scopes":["databases:write"],"requestMediaTypes":[],"statuses":[204],"responseMediaType":"","source":"src/TerraBase/Features/Management/Queries/DeleteSavedQueryEndpoint.cs","request":"none"},
     {"method":"GET","path":"/v1/projects/{project}/saved-queries/{query}","operation":"getSavedQuery","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Queries/GetSavedQueryEndpoint.cs","request":"none"},
     {"method":"PUT","path":"/v1/projects/{project}/saved-queries/{query}","operation":"updateSavedQuery","scopes":["databases:write"],"requestMediaTypes":["application/json"],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Queries/UpdateSavedQueryEndpoint.cs","request":"SavedQueryRequest"},
-    {"method":"GET","path":"/v1/projects/{project}/usage","operation":"getProjectUsage","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Usage/GetProjectUsageEndpoint.cs","request":"none"}
+    {"method":"GET","path":"/v1/projects/{project}/usage","operation":"getProjectUsage","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Usage/GetProjectUsageEndpoint.cs","request":"none"},
+    {"method":"POST","path":"/v1/projects/{project}/databases/{database}/collections/{collection}/webhooks","operation":"createChangeWebhook","scopes":["documents:read","documents:write"],"requestMediaTypes":["application/json"],"statuses":[201],"responseMediaType":"application/json","contract":"contracts/change-webhooks.md","request":"CreateWebhookRequest"},
+    {"method":"GET","path":"/v1/projects/{project}/databases/{database}/collections/{collection}/webhooks","operation":"listChangeWebhooks","scopes":["documents:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","contract":"contracts/change-webhooks.md","request":"none"},
+    {"method":"DELETE","path":"/v1/projects/{project}/databases/{database}/collections/{collection}/webhooks/{webhook}","operation":"deleteChangeWebhook","scopes":["documents:read","documents:write"],"requestMediaTypes":[],"statuses":[204],"responseMediaType":"","contract":"contracts/change-webhooks.md","request":"none"},
+    {"method":"GET","path":"/v1/projects/{project}/databases/{database}/collections/{collection}/webhooks/{webhook}/deliveries","operation":"listChangeWebhookDeliveries","scopes":["documents:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","contract":"contracts/change-webhooks.md","request":"none"}
   ]
 }

package/src/index.js

@@ -15,6 +15,7 @@ export {
   V1InvalidKeyError,
   V1ForbiddenScopeError,
   V1NotFoundError,
+  SqlError,
   V1ErrorCode,
   isTerraBaseV1Error,
 } from "./v1/errors.js";
@@ -76,6 +77,12 @@ export { V1SavedQueries } from "./v1/saved-queries.js";
 /** @typedef {import("./v1/sql.js").V1SqlResult} V1SqlResult */
 /** @typedef {import("./v1/sql.js").V1SqlIndexSuggestion} V1SqlIndexSuggestion */
 /** @typedef {import("./v1/sql.js").V1SqlCheck} V1SqlCheck */
+/** @typedef {import("./v1/sql-execute.js").V1SqlArgument} V1SqlArgument */
+/** @typedef {import("./v1/sql-execute.js").V1SqlArguments} V1SqlArguments */
+/** @typedef {import("./v1/sql-execute.js").V1SqlStatement} V1SqlStatement */
+/** @typedef {import("./v1/sql-execute.js").V1SqlValue} V1SqlValue */
+/** @typedef {import("./v1/sql-execute.js").V1SqlColumn} V1SqlColumn */
+/** @typedef {import("./v1/sql-execute.js").V1SqlExecuteResult} V1SqlExecuteResult */
 /** @typedef {import("./v1/changes.js").V1ChangeStreamRequest} V1ChangeStreamRequest */
 /** @typedef {import("./v1/changes.js").V1DatabaseChange} V1DatabaseChange */
 /** @typedef {import("./v1/changes.js").V1DatabaseChangeCursor} V1DatabaseChangeCursor */
@@ -114,6 +121,11 @@ export { V1ProjectUsageClient, V1DatabaseUsageClient } from "./v1/usage.js";
 /** @typedef {import("./v1/usage.js").V1AnalyticsRequest} V1AnalyticsRequest */
 
 export { V1Backups, V1BackupDestinationClient } from "./v1/backups.js";
+export { V1ChangeWebhooks } from "./v1/change-webhooks.js";
+/** @typedef {import("./v1/change-webhooks.js").V1ChangeWebhook} V1ChangeWebhook */
+/** @typedef {import("./v1/change-webhooks.js").V1CreatedChangeWebhook} V1CreatedChangeWebhook */
+/** @typedef {import("./v1/change-webhooks.js").V1ChangeWebhookDelivery} V1ChangeWebhookDelivery */
+/** @typedef {import("./v1/change-webhooks.js").V1ChangeWebhookListRequest} V1ChangeWebhookListRequest */
 /** @typedef {import("./v1/backups.js").V1Backup} V1Backup */
 /** @typedef {import("./v1/backups.js").V1BackupPage} V1BackupPage */
 /** @typedef {import("./v1/backups.js").V1BackupPolicy} V1BackupPolicy */

package/src/v1/change-webhooks.js

@@ -0,0 +1,78 @@
+import { requireId } from "../ids.js";
+import { requireName } from "./ids.js";
+import { object, string } from "./decode.js";
+import { list, nullable, numeric, record, text } from "./management-decode.js";
+import { members, mutationOptions, pageQuery } from "./management-validation.js";
+import { stringifyExactJson } from "./json.js";
+/** @import { V1Transport } from "./transport.js" */
+/** @import { V1RequestOptions } from "./terrabase-v1.js" */
+const webhook = record({ id: requireId, url: text, createdAt: text, status: text });
+const webhooks = list(webhook);
+const deliveries = list(record({ id: requireId, createdAt: text, status: text, attempts: numeric,
+  lastAttemptAt: nullable(text), nextAttemptAt: nullable(text), httpStatus: nullable(numeric), errorCode: nullable(text) }));
+/** @typedef {ReturnType<typeof webhook>} V1ChangeWebhook */
+/** @typedef {V1ChangeWebhook & { readonly secret: string }} V1CreatedChangeWebhook */
+/** @typedef {ReturnType<typeof deliveries>[number]} V1ChangeWebhookDelivery */
+/** @typedef {{ readonly after?: string; readonly limit?: number }} V1ChangeWebhookListRequest */
+
+/** @param {V1ChangeWebhookListRequest} request */
+function query(request) {
+  if (request.after !== undefined) requireId(request.after, "after");
+  return pageQuery(request);
+}
+
+/** Collection change webhook registration and sanitized delivery history. Requests are never replayed. */
+export class V1ChangeWebhooks {
+  /** @type {V1Transport} */
+  #transport;
+  /** @type {{database: string; collection: string}} */
+  #params;
+  /** @param {V1Transport} transport @param {string} database @param {string} collection */
+  constructor(transport, database, collection) {
+    this.#transport = transport;
+    this.#params = { database: requireName("database", database), collection: requireName("collection", collection) };
+    Object.freeze(this);
+  }
+  /**
+   * Registers from the current feed head. Requires documents:read and documents:write.
+   * Store secret immediately; it is non-enumerable to keep it out of JSON and ordinary diagnostics.
+   * @param {{ readonly url: string }} request @param {V1RequestOptions} [options] @returns {Promise<V1CreatedChangeWebhook>}
+   */
+  async create(request, options = {}) {
+    members(request, ["url"]);
+    if (typeof request.url !== "string" || request.url.length > 2048) throw new TypeError("Webhook URL must be an HTTPS URL of at most 2048 characters.");
+    let url;
+    try { url = new URL(request.url); } catch { throw new TypeError("Webhook URL must be absolute HTTPS."); }
+    if (url.protocol !== "https:" || url.port !== "" || url.username !== "" || url.password !== "" || url.hash !== "")
+      throw new TypeError("Webhook URL must be HTTPS on port 443, without credentials or a fragment.");
+    mutationOptions(options);
+    const raw = object((await this.#transport.call("createChangeWebhook", this.#params, {
+      body: stringifyExactJson(request, "change webhook"), signal: options.signal,
+    })).value, "created webhook");
+    const secret = string(raw.secret, "webhook secret");
+    return Object.freeze(Object.defineProperty({ ...webhook(raw), secret }, "secret", { enumerable: false }));
+  }
+  /**
+   * Requires documents:read. Ascending IDs; continue with the final ID until an empty array. No secrets.
+   * @param {V1ChangeWebhookListRequest} [request] @param {V1RequestOptions} [options] @returns {Promise<readonly V1ChangeWebhook[]>}
+   */
+  async list(request = {}, options = {}) {
+    return webhooks((await this.#transport.call("listChangeWebhooks", this.#params, { query: query(request), signal: options.signal })).value);
+  }
+  /**
+   * Requires documents:read and documents:write. An in-flight delivery may still complete. Unknown ID returns 404.
+   * @param {string} id @param {V1RequestOptions} [options] @returns {Promise<void>}
+   */
+  async delete(id, options = {}) {
+    mutationOptions(options);
+    await this.#transport.call("deleteChangeWebhook", { ...this.#params, webhook: requireId(id) }, { signal: options.signal });
+  }
+  /**
+   * Requires documents:read. Latest 100 retained records; paginate with the final ID until an empty array.
+   * @param {string} id @param {V1ChangeWebhookListRequest} [request] @param {V1RequestOptions} [options] @returns {Promise<readonly V1ChangeWebhookDelivery[]>}
+   */
+  async deliveries(id, request = {}, options = {}) {
+    return deliveries((await this.#transport.call("listChangeWebhookDeliveries", { ...this.#params, webhook: requireId(id) },
+      { query: query(request), signal: options.signal })).value);
+  }
+}

package/src/v1/errors.js

@@ -76,6 +76,7 @@ export const V1ErrorCode = Object.freeze({
   mustRefetch: "must_refetch", preconditionFailed: "precondition_failed", payloadTooLarge: "payload_too_large",
   unsupportedMediaType: "unsupported_media_type", uriTooLong: "uri_too_long", shapeBusy: "shape_busy",
   internalError: "internal_error", capacity: "capacity", notModified: "not_modified",
+  sqlError: "sql_error", sqlConflict: "sql_conflict", sqlTooLarge: "sql_too_large",
 });
 
 /** `412 precondition_failed`: an If-Match, If-None-Match, assert or assert_count failed. */
@@ -114,11 +115,36 @@ export class V1NotFoundError extends TerraBaseV1Error {
   }
 }
 
+/**
+ * A refused relational SQL statement: `sql_error` (400), `forbidden_scope` (403, writes and DDL need
+ * documents:write), `sql_conflict` (409) or `sql_too_large` (413). The whole request rolled back.
+ */
+export class SqlError extends TerraBaseV1Error {
+  /** @type {number} Zero-based index of the failing statement. */
+  statement;
+  /** @type {string | undefined} The SQLite error code, such as `SQLITE_CONSTRAINT_PRIMARYKEY`. */
+  sqliteCode;
+
+  /** @param {TerraBaseV1ErrorInit & { statement: number; sqliteCode?: string | undefined }} init */
+  constructor(init) {
+    super(init);
+    this.name = "SqlError";
+    this.statement = init.statement;
+    this.sqliteCode = init.sqliteCode;
+  }
+}
+
 /**
  * @param {TerraBaseV1ErrorInit} init
  * @returns {TerraBaseV1Error}
  */
 function typedError(init) {
+  // Only the SQL execute route reports a statement index.
+  const statement = init.details?.statement;
+  if (typeof statement === "number" && Number.isInteger(statement) && statement >= 0) {
+    const sqliteCode = init.details?.sqlite_code;
+    return new SqlError({ ...init, statement, sqliteCode: typeof sqliteCode === "string" ? sqliteCode : undefined });
+  }
   switch (init.code) {
     case "precondition_failed": return new V1PreconditionFailedError(init);
     case "invalid_key": return new V1InvalidKeyError(init);

package/src/v1/management-routes.js

@@ -1,10 +1,17 @@
-/** @typedef {"getShapeManifest" | "exportDatabase" | "putCollectionTtl" | "getCollectionTtl" | "deleteCollectionTtl" | "healthz" | "readyz" | "backupz" | "replicationHealth" | "listPlatformDatabases" | "listPlatformCollections" | "listPlatformDocuments" | "getPlatformDocument" | "createImport" | "getImport" | "uploadImportSource" | "updateImport" | "startImport" | "cancelImport" | "resumeImport" | "createBackup" | "listBackups" | "restoreBackup" | "getBackupPolicy" | "setBackupPolicy" | "getRestoreWindow" | "planPointInTime" | "restorePointInTime" | "getBackupDestination" | "setBackupDestination" | "deleteBackupDestination" | "getProjectUsage" | "getProjectAnalytics" | "getProjectReplication" | "getDatabaseUsage" | "getDatabaseAnalytics" | "getDatabaseReplication" | "createIndex" | "listIndexes" | "dropIndex" | "getAutoIndexPolicy" | "setAutoIndexPolicy" | "listIndexRecommendations" | "applyIndexRecommendation" | "getDatabaseSchema" | "inferCollectionSchema" | "declareCollectionSchema" | "listQueryShapes" | "createSavedQuery" | "listSavedQueries" | "getSavedQuery" | "updateSavedQuery" | "deleteSavedQuery"} ManagementOperation */
+/** @typedef {"getShapeManifest" | "exportDatabase" | "executeSql" | "putCollectionTtl" | "getCollectionTtl" | "deleteCollectionTtl" | "healthz" | "readyz" | "backupz" | "replicationHealth" | "listPlatformDatabases" | "listPlatformCollections" | "listPlatformDocuments" | "getPlatformDocument" | "createImport" | "getImport" | "uploadImportSource" | "updateImport" | "startImport" | "cancelImport" | "resumeImport" | "createBackup" | "listBackups" | "restoreBackup" | "getBackupPolicy" | "setBackupPolicy" | "getRestoreWindow" | "planPointInTime" | "restorePointInTime" | "getBackupDestination" | "setBackupDestination" | "deleteBackupDestination" | "getProjectUsage" | "getProjectAnalytics" | "getProjectReplication" | "getDatabaseUsage" | "getDatabaseAnalytics" | "getDatabaseReplication" | "createIndex" | "listIndexes" | "dropIndex" | "getAutoIndexPolicy" | "setAutoIndexPolicy" | "listIndexRecommendations" | "applyIndexRecommendation" | "getDatabaseSchema" | "inferCollectionSchema" | "declareCollectionSchema" | "listQueryShapes" | "createSavedQuery" | "listSavedQueries" | "getSavedQuery" | "updateSavedQuery" | "deleteSavedQuery" | "createChangeWebhook" | "listChangeWebhooks" | "deleteChangeWebhook" | "listChangeWebhookDeliveries"} ManagementOperation */
+const webhooks = "/v1/projects/{project}/databases/{database}/collections/{collection}/webhooks";
 const saved = "/v1/projects/{project}/saved-queries";
 const ttl = "/v1/projects/{project}/databases/{database}/collections/{collection}/ttl";
 /** @type {readonly import("./routes.js").V1Route[]} */
 export const managementV1Routes = Object.freeze([
+  route("createChangeWebhook", "POST", webhooks, 201),
+  route("listChangeWebhooks", "GET", webhooks),
+  route("deleteChangeWebhook", "DELETE", `${webhooks}/{webhook}`, 204),
+  route("listChangeWebhookDeliveries", "GET", `${webhooks}/{webhook}/deliveries`),
   route("getShapeManifest", "GET", "/v1/projects/{project}/databases/{database}/collections/{collection}/shape/manifest"),
   route("exportDatabase", "GET", "/v1/projects/{project}/databases/{database}/export"),
+  // Reads need documents:read; writes and DDL also need documents:write, checked per statement.
+  route("executeSql", "POST", "/v1/projects/{project}/databases/{database}/sql/execute"),
   route("putCollectionTtl", "PUT", ttl),
   route("getCollectionTtl", "GET", ttl),
   route("deleteCollectionTtl", "DELETE", ttl),
@@ -61,12 +68,13 @@ export const managementV1Routes = Object.freeze([
 /** @param {ManagementOperation} operation @param {import("./routes.js").V1Route["method"]} method @param {string} pathTemplate @param {number} [status] @returns {import("./routes.js").V1Route} */
 function route(operation, method, pathTemplate, status = 200) {
   const write = method !== "GET" && operation !== "planPointInTime";
+  const webhook = pathTemplate.startsWith(webhooks);
   const noBody = ["createBackup", "applyIndexRecommendation", "cancelImport", "resumeImport"].includes(operation);
   return Object.freeze({ operation, method, pathTemplate,
-    permission: operation === "getShapeManifest" || operation === "exportDatabase" || operation === "getCollectionTtl" ? "documents:read" : pathTemplate === ttl ? "documents:write" : pathTemplate.startsWith("/v1/platform/") ? "platform-admin" : !pathTemplate.startsWith("/v1/") ? "anonymous" : write ? "databases:write" : "databases:read",
-    additionalPermissions: Object.freeze(["createImport", "uploadImportSource", "updateImport", "startImport", "resumeImport"].includes(operation) ? ["documents:write"] : []),
+    permission: webhook ? write ? "documents:write" : "documents:read" : operation === "getShapeManifest" || operation === "exportDatabase" || operation === "executeSql" || operation === "getCollectionTtl" ? "documents:read" : pathTemplate === ttl ? "documents:write" : pathTemplate.startsWith("/v1/platform/") ? "platform-admin" : !pathTemplate.startsWith("/v1/") ? "anonymous" : write ? "databases:write" : "databases:read",
+    additionalPermissions: Object.freeze(webhook && write ? ["documents:read"] : ["createImport", "uploadImportSource", "updateImport", "startImport", "resumeImport"].includes(operation) ? ["documents:write"] : []),
     requestMediaTypes: Object.freeze(noBody ? [] : operation === "uploadImportSource" ? ["application/octet-stream"] : method === "POST" || method === "PUT" || method === "PATCH" ? ["application/json"] : []),
     responseMediaType: status === 204 ? "" : operation === "exportDatabase" ? "application/x-ndjson" : "application/json", successStatuses: Object.freeze(operation === "readyz" || operation === "backupz" ? [200, 503] : operation === "applyIndexRecommendation" || operation === "createImport" ? [200, 201] : [status]),
-    idempotencyKey: "none", replaySafe: !write, contract: "docs/terrabase/api.md", contractText: Object.freeze([]),
+    idempotencyKey: "none", replaySafe: !write, contract: webhook ? "docs/terrabase/change-webhooks.md" : "docs/terrabase/api.md", contractText: Object.freeze([]),
   });
 }

package/src/v1/sql-execute.js

@@ -0,0 +1,132 @@
+import { array, malformed, object, string } from "./decode.js";
+import { requireName } from "./ids.js";
+import { ExactDecimal, stringifyExactJson } from "./json.js";
+/**
+ * @import { JsonValue } from "./json.js"
+ * @import { V1RequestOptions } from "./terrabase-v1.js"
+ * @import { V1Transport } from "./transport.js"
+ */
+
+/**
+ * An argument: null, a finite number, an int64 `bigint` or ExactDecimal, a boolean (stored as 1 or 0) or a string.
+ * @typedef {null | boolean | number | bigint | ExactDecimal | string} V1SqlArgument
+ */
+/** @typedef {readonly V1SqlArgument[] | Readonly<Record<string, V1SqlArgument>>} V1SqlArguments Positional array, or named values keyed without their `:`, `@` or `$` prefix. */
+/**
+ * @typedef {object} V1SqlStatement
+ * @property {string} sql
+ * @property {readonly V1SqlArgument[] | undefined} [args] Positional arguments.
+ * @property {Readonly<Record<string, V1SqlArgument>> | undefined} [named] Named arguments, keys without their prefix.
+ */
+/**
+ * A result value. Integers beyond 2^53 decode as ExactDecimal, keeping every digit; `BigInt(String(value))` converts one.
+ * @typedef {null | number | ExactDecimal | string} V1SqlValue
+ */
+/** @typedef {{ readonly name: string; readonly decltype: string | null }} V1SqlColumn A column; `decltype` is null for an expression. */
+/**
+ * @typedef {object} V1SqlExecuteResult
+ * @property {readonly V1SqlColumn[]} columns
+ * @property {readonly (readonly V1SqlValue[])[]} rows One value per column.
+ * @property {number} rowsAffected
+ * @property {number | ExactDecimal | null} lastInsertRowid
+ */
+
+const maximumStatements = 256;
+const maximumSqlLength = 16_384;
+
+/** @param {unknown} value @param {string} where */
+function requireArgument(value, where) {
+  if (value === null || typeof value === "boolean" || typeof value === "string" || value instanceof ExactDecimal) return;
+  if (typeof value === "number" && Number.isFinite(value)) return;
+  if (typeof value === "bigint" && BigInt.asIntN(64, value) === value) return;
+  throw new TypeError(`SQL ${where} is null, a finite number, an int64 bigint, a boolean or a string.`);
+}
+
+/** @param {unknown} statement @param {number} index */
+function encodeStatement(statement, index) {
+  if (typeof statement !== "string" && (typeof statement !== "object" || statement === null || Array.isArray(statement)))
+    throw new TypeError(`SQL statement ${index} is a string or { sql, args, named }.`);
+  const { sql, args, named, ...extra } = /** @type {V1SqlStatement} */ (typeof statement === "string" ? { sql: statement } : statement);
+  for (const member of Object.keys(extra)) throw new TypeError(`Unknown SQL statement member ${member}.`);
+  if (typeof sql !== "string" || sql.length === 0 || sql.length > maximumSqlLength)
+    throw new TypeError(`SQL statement ${index} is a non-empty string of at most ${maximumSqlLength} UTF-16 code units.`);
+  /** @type {{ sql: string; args?: V1SqlArgument[]; named?: Record<string, V1SqlArgument> }} */
+  const encoded = { sql };
+  if (args !== undefined) {
+    if (!Array.isArray(args)) throw new TypeError(`SQL statement ${index} args is an array.`);
+    args.forEach((arg, position) => requireArgument(arg, `argument ${position}`));
+    encoded.args = [...args];
+  }
+  if (named !== undefined) {
+    if (named === null || typeof named !== "object" || Array.isArray(named)) throw new TypeError(`SQL statement ${index} named is an object.`);
+    for (const [name, value] of Object.entries(named)) {
+      if (/^[:@$]/u.test(name)) throw new TypeError(`SQL named argument ${name} is keyed without its prefix.`);
+      requireArgument(value, `named argument ${name}`);
+    }
+    encoded.named = { ...named };
+  }
+  return encoded;
+}
+
+/** @param {string} sql @param {V1SqlArguments | undefined} args @returns {V1SqlStatement} */
+export function sqlStatement(sql, args) {
+  if (args === undefined) return { sql };
+  return Array.isArray(args) ? { sql, args } : { sql, named: /** @type {Readonly<Record<string, V1SqlArgument>>} */ (args) };
+}
+
+/** @param {JsonValue | undefined} value @returns {V1SqlValue} */
+function decodeValue(value) {
+  if (value === null || typeof value === "number" || typeof value === "string" || value instanceof ExactDecimal) return value;
+  return malformed("SQL value");
+}
+
+/** @param {JsonValue | undefined} value @returns {V1SqlExecuteResult} */
+function decodeResult(value) {
+  const raw = object(value, "SQL statement result");
+  const columns = array(raw.columns, "SQL columns").map(entry => {
+    const column = object(entry, "SQL column");
+    const decltype = column.decltype === null || column.decltype === undefined ? null : string(column.decltype, "SQL column decltype");
+    return Object.freeze({ name: string(column.name, "SQL column name"), decltype });
+  });
+  const rows = array(raw.rows, "SQL rows").map(entry => {
+    const row = array(entry, "SQL row").map(decodeValue);
+    if (row.length !== columns.length) malformed("SQL row width");
+    return Object.freeze(row);
+  });
+  const affected = raw.rows_affected;
+  if (typeof affected !== "number" || !Number.isSafeInteger(affected) || affected < 0) malformed("SQL rows_affected");
+  const rowid = raw.last_insert_rowid ?? null;
+  if (rowid !== null && !(rowid instanceof ExactDecimal) && !(typeof rowid === "number" && Number.isInteger(rowid))) malformed("SQL last_insert_rowid");
+  return Object.freeze({ columns: Object.freeze(columns), rows: Object.freeze(rows), rowsAffected: affected, lastInsertRowid: rowid });
+}
+
+/**
+ * Runs 1 to 256 statements as one transaction: all commit or none do. BEGIN, COMMIT and ROLLBACK are refused.
+ * A refused statement throws SqlError with its index.
+ * @param {V1Transport} transport
+ * @param {string} database
+ * @param {readonly (string | V1SqlStatement)[]} statements
+ * @param {V1RequestOptions} [options]
+ * @returns {Promise<readonly V1SqlExecuteResult[]>}
+ */
+export async function executeSql(transport, database, statements, options = {}) {
+  if (!Array.isArray(statements) || statements.length === 0 || statements.length > maximumStatements)
+    throw new TypeError(`SQL batches hold 1 to ${maximumStatements} statements.`);
+  if (options === null || typeof options !== "object" || Array.isArray(options)) throw new TypeError("SQL request options must be an object.");
+  for (const member of Object.keys(options)) if (member !== "signal") throw new TypeError(`Unknown SQL request option ${member}.`);
+  const body = stringifyExactJson({ statements: statements.map(encodeStatement) }, "SQL statements");
+  const response = await transport.call("executeSql", { database: requireName("database", database) }, { body, signal: options.signal });
+  const results = array(object(response.value, "SQL execute response").results, "SQL results").map(decodeResult);
+  if (results.length !== statements.length) malformed("SQL result count");
+  return Object.freeze(results);
+}
+
+/**
+ * Rows as objects keyed by column name; a later duplicate column name wins.
+ * @template [T=Record<string, V1SqlValue>]
+ * @param {V1SqlExecuteResult} result
+ * @returns {T[]}
+ */
+export function sqlRowObjects(result) {
+  return result.rows.map(row => /** @type {T} */ (Object.fromEntries(result.columns.map((column, index) => [column.name, row[index] ?? null]))));
+}

package/src/v1/terrabase-v1.js

@@ -11,6 +11,7 @@ import { readShapeManifest } from "./shape-manifest.js";
 import { V1ShapeSubscription } from "./shape-subscription.js";
 import { decryptSealedShapePage, readShapePage, readShapeKey } from "./shape-reader.js";
 import { runSql, checkSql } from "./sql.js";
+import { executeSql, sqlRowObjects, sqlStatement } from "./sql-execute.js";
 import { streamChanges } from "./changes.js";
 import { exportDocuments } from "./export.js";
 import { V1Databases, getCollectionSchema, putCollectionSchema, deleteCollectionSchema, getCollectionTtl, putCollectionTtl, deleteCollectionTtl } from "./catalog.js";
@@ -22,6 +23,7 @@ import { V1ProjectUsageClient, V1DatabaseUsageClient } from "./usage.js";
 import { V1Indexes } from "./indexes.js";
 import { V1DatabaseSchemaClient } from "./database-schema.js";
 import { V1SavedQueries } from "./saved-queries.js";
+import { V1ChangeWebhooks } from "./change-webhooks.js";
 /**
  * @import { V1Document, V1Durability, V1WriteResult } from "./decode.js"
  * @import { V1Filter, V1Path } from "./filter.js"
@@ -301,6 +303,8 @@ function encodeDocument(document) {
 
 /** A collection handle by name. It performs no I/O until an operation runs. */
 export class V1Collection {
+  /** @type {V1ChangeWebhooks} */
+  webhooks;
   /** @type {V1Transport} */
   #transport;
   /** @type {Readonly<Record<string, string>>} */
@@ -319,6 +323,7 @@ export class V1Collection {
     this.#transport = transport;
     this.database = requireName("database", database);
     this.name = requireName("collection", name);
+    this.webhooks = new V1ChangeWebhooks(transport, this.database, this.name);
     this.#params = Object.freeze({ database: this.database, collection: this.name });
     Object.freeze(this);
   }
@@ -852,6 +857,39 @@ export class V1Database {
     return checkSql(this.#transport, this.name, statement, options, "explainSql");
   }
 
+  /**
+   * Runs one relational SQL statement as its own transaction. Reads need documents:read; writes and DDL need documents:write.
+   * @param {string} sql
+   * @param {import("./sql-execute.js").V1SqlArguments} [args] Positional array, or named values keyed without their prefix.
+   * @param {V1RequestOptions} [options]
+   * @returns {Promise<import("./sql-execute.js").V1SqlExecuteResult>}
+   */
+  async execute(sql, args, options = {}) {
+    const [result] = await executeSql(this.#transport, this.name, [sqlStatement(sql, args)], options);
+    return /** @type {import("./sql-execute.js").V1SqlExecuteResult} */ (result);
+  }
+
+  /**
+   * Runs one statement and returns its rows as objects keyed by column name.
+   * @template [T=Record<string, import("./sql-execute.js").V1SqlValue>]
+   * @param {string} sql
+   * @param {import("./sql-execute.js").V1SqlArguments} [args]
+   * @param {V1RequestOptions} [options]
+   * @returns {Promise<T[]>}
+   */
+  async query(sql, args, options = {}) {
+    return sqlRowObjects(await this.execute(sql, args, options));
+  }
+
+  /**
+   * Runs 1 to 256 statements as one transaction: all commit or none do. A refused statement throws SqlError.
+   * @param {readonly (string | import("./sql-execute.js").V1SqlStatement)[]} statements
+   * @param {V1RequestOptions} [options]
+   */
+  batch(statements, options = {}) {
+    return executeSql(this.#transport, this.name, statements, options);
+  }
+
   /** @param {import("./changes.js").V1ChangeStreamRequest} [request] @param {V1RequestOptions} [options] */
   changes(request = {}, options = {}) {
     return streamChanges(this.#transport, this.name, request, options.signal);

package/types/index.d.ts

@@ -6,6 +6,7 @@ export { V1Databases } from "./v1/catalog.js";
 export { V1SavedQueries } from "./v1/saved-queries.js";
 export { V1DatabaseSchemaClient } from "./v1/database-schema.js";
 export { V1Indexes } from "./v1/indexes.js";
+export { V1ChangeWebhooks } from "./v1/change-webhooks.js";
 export { V1Imports } from "./v1/imports.js";
 export type V1ShapeSubscribeOptions = import("./v1/shape-subscription.js").V1ShapeSubscribeOptions;
 export type V1ShapeDocument = import("./v1/shape-subscription.js").V1ShapeDocument;
@@ -56,6 +57,12 @@ export type V1SqlRow = import("./v1/sql.js").V1SqlRow;
 export type V1SqlResult = import("./v1/sql.js").V1SqlResult;
 export type V1SqlIndexSuggestion = import("./v1/sql.js").V1SqlIndexSuggestion;
 export type V1SqlCheck = import("./v1/sql.js").V1SqlCheck;
+export type V1SqlArgument = import("./v1/sql-execute.js").V1SqlArgument;
+export type V1SqlArguments = import("./v1/sql-execute.js").V1SqlArguments;
+export type V1SqlStatement = import("./v1/sql-execute.js").V1SqlStatement;
+export type V1SqlValue = import("./v1/sql-execute.js").V1SqlValue;
+export type V1SqlColumn = import("./v1/sql-execute.js").V1SqlColumn;
+export type V1SqlExecuteResult = import("./v1/sql-execute.js").V1SqlExecuteResult;
 export type V1ChangeStreamRequest = import("./v1/changes.js").V1ChangeStreamRequest;
 export type V1DatabaseChange = import("./v1/changes.js").V1DatabaseChange;
 export type V1DatabaseChangeCursor = import("./v1/changes.js").V1DatabaseChangeCursor;
@@ -86,6 +93,10 @@ export type V1Analytics = import("./v1/usage.js").V1Analytics;
 export type V1Replication = import("./v1/usage.js").V1Replication;
 export type V1UsageRequest = import("./v1/usage.js").V1UsageRequest;
 export type V1AnalyticsRequest = import("./v1/usage.js").V1AnalyticsRequest;
+export type V1ChangeWebhook = import("./v1/change-webhooks.js").V1ChangeWebhook;
+export type V1CreatedChangeWebhook = import("./v1/change-webhooks.js").V1CreatedChangeWebhook;
+export type V1ChangeWebhookDelivery = import("./v1/change-webhooks.js").V1ChangeWebhookDelivery;
+export type V1ChangeWebhookListRequest = import("./v1/change-webhooks.js").V1ChangeWebhookListRequest;
 export type V1Backup = import("./v1/backups.js").V1Backup;
 export type V1BackupPage = import("./v1/backups.js").V1BackupPage;
 export type V1BackupPolicy = import("./v1/backups.js").V1BackupPolicy;
@@ -110,7 +121,7 @@ export type V1ShapeKeyRequest = import("./v1/shape-reader.js").V1ShapeKeyRequest
 export type V1ShapeKey = import("./v1/shape-reader.js").V1ShapeKey;
 export { createTerraBaseV1Client as createTerraBaseClient, TerraBaseV1Client as TerraBaseClient, createTerraBaseV1Client, TerraBaseV1Client, V1Database, V1Collection, V1Collections, V1Transaction } from "./v1/terrabase-v1.js";
 export { terraScaleReleaseBlockers, TerraScaleCapabilityUnavailableError } from "./management-contracts.js";
-export { TerraBaseV1Error, V1PreconditionFailedError, V1InvalidKeyError, V1ForbiddenScopeError, V1NotFoundError, V1ErrorCode, isTerraBaseV1Error } from "./v1/errors.js";
+export { TerraBaseV1Error, V1PreconditionFailedError, V1InvalidKeyError, V1ForbiddenScopeError, V1NotFoundError, SqlError, V1ErrorCode, isTerraBaseV1Error } from "./v1/errors.js";
 export { generateId, isValidId, requireId } from "./ids.js";
 export { V1ProjectUsageClient, V1DatabaseUsageClient } from "./v1/usage.js";
 export { V1Backups, V1BackupDestinationClient } from "./v1/backups.js";

package/types/v1/change-webhooks.d.ts

@@ -0,0 +1,59 @@
+/** Collection change webhook registration and sanitized delivery history. Requests are never replayed. */
+export class V1ChangeWebhooks {
+    /** @param {V1Transport} transport @param {string} database @param {string} collection */
+    constructor(transport: V1Transport, database: string, collection: string);
+    /**
+     * Registers from the current feed head. Requires documents:read and documents:write.
+     * Store secret immediately; it is non-enumerable to keep it out of JSON and ordinary diagnostics.
+     * @param {{ readonly url: string }} request @param {V1RequestOptions} [options] @returns {Promise<V1CreatedChangeWebhook>}
+     */
+    create(request: {
+        readonly url: string;
+    }, options?: V1RequestOptions): Promise<V1CreatedChangeWebhook>;
+    /**
+     * Requires documents:read. Ascending IDs; continue with the final ID until an empty array. No secrets.
+     * @param {V1ChangeWebhookListRequest} [request] @param {V1RequestOptions} [options] @returns {Promise<readonly V1ChangeWebhook[]>}
+     */
+    list(request?: V1ChangeWebhookListRequest, options?: V1RequestOptions): Promise<readonly V1ChangeWebhook[]>;
+    /**
+     * Requires documents:read and documents:write. An in-flight delivery may still complete. Unknown ID returns 404.
+     * @param {string} id @param {V1RequestOptions} [options] @returns {Promise<void>}
+     */
+    delete(id: string, options?: V1RequestOptions): Promise<void>;
+    /**
+     * Requires documents:read. Latest 100 retained records; paginate with the final ID until an empty array.
+     * @param {string} id @param {V1ChangeWebhookListRequest} [request] @param {V1RequestOptions} [options] @returns {Promise<readonly V1ChangeWebhookDelivery[]>}
+     */
+    deliveries(id: string, request?: V1ChangeWebhookListRequest, options?: V1RequestOptions): Promise<readonly V1ChangeWebhookDelivery[]>;
+    #private;
+}
+export type V1ChangeWebhook = ReturnType<typeof webhook>;
+export type V1CreatedChangeWebhook = V1ChangeWebhook & {
+    readonly secret: string;
+};
+export type V1ChangeWebhookDelivery = ReturnType<typeof deliveries>[number];
+export type V1ChangeWebhookListRequest = {
+    readonly after?: string;
+    readonly limit?: number;
+};
+import type { V1RequestOptions } from "./terrabase-v1.js";
+import type { V1Transport } from "./transport.js";
+/** @import { V1Transport } from "./transport.js" */
+/** @import { V1RequestOptions } from "./terrabase-v1.js" */
+declare const webhook: import("./management-decode.js").Decoder<Readonly<{
+    id: string;
+    url: string;
+    createdAt: string;
+    status: string;
+}>>;
+declare const deliveries: import("./management-decode.js").Decoder<readonly Readonly<{
+    id: string;
+    createdAt: string;
+    status: string;
+    attempts: number | import("./json.js").ExactDecimal;
+    lastAttemptAt: string | null;
+    nextAttemptAt: string | null;
+    httpStatus: number | import("./json.js").ExactDecimal | null;
+    errorCode: string | null;
+}>[]>;
+export {};

package/types/v1/errors.d.ts

@@ -92,6 +92,9 @@ export const V1ErrorCode: Readonly<{
     internalError: "internal_error";
     capacity: "capacity";
     notModified: "not_modified";
+    sqlError: "sql_error";
+    sqlConflict: "sql_conflict";
+    sqlTooLarge: "sql_too_large";
 }>;
 /** `412 precondition_failed`: an If-Match, If-None-Match, assert or assert_count failed. */
 export class V1PreconditionFailedError extends TerraBaseV1Error {
@@ -105,6 +108,21 @@ export class V1ForbiddenScopeError extends TerraBaseV1Error {
 /** `404 not_found`: absent or deleted; `etag` carries a tombstone version. */
 export class V1NotFoundError extends TerraBaseV1Error {
 }
+/**
+ * A refused relational SQL statement: `sql_error` (400), `forbidden_scope` (403, writes and DDL need
+ * documents:write), `sql_conflict` (409) or `sql_too_large` (413). The whole request rolled back.
+ */
+export class SqlError extends TerraBaseV1Error {
+    /** @param {TerraBaseV1ErrorInit & { statement: number; sqliteCode?: string | undefined }} init */
+    constructor(init: TerraBaseV1ErrorInit & {
+        statement: number;
+        sqliteCode?: string | undefined;
+    });
+    /** @type {number} Zero-based index of the failing statement. */
+    statement: number;
+    /** @type {string | undefined} The SQLite error code, such as `SQLITE_CONSTRAINT_PRIMARYKEY`. */
+    sqliteCode: string | undefined;
+}
 export type TerraBaseV1ErrorInit = {
     status: number;
     code: string;

package/types/v1/management-routes.d.ts

@@ -1,3 +1,3 @@
 /** @type {readonly import("./routes.js").V1Route[]} */
 export const managementV1Routes: readonly import("./routes.js").V1Route[];
-export type ManagementOperation = "getShapeManifest" | "exportDatabase" | "putCollectionTtl" | "getCollectionTtl" | "deleteCollectionTtl" | "healthz" | "readyz" | "backupz" | "replicationHealth" | "listPlatformDatabases" | "listPlatformCollections" | "listPlatformDocuments" | "getPlatformDocument" | "createImport" | "getImport" | "uploadImportSource" | "updateImport" | "startImport" | "cancelImport" | "resumeImport" | "createBackup" | "listBackups" | "restoreBackup" | "getBackupPolicy" | "setBackupPolicy" | "getRestoreWindow" | "planPointInTime" | "restorePointInTime" | "getBackupDestination" | "setBackupDestination" | "deleteBackupDestination" | "getProjectUsage" | "getProjectAnalytics" | "getProjectReplication" | "getDatabaseUsage" | "getDatabaseAnalytics" | "getDatabaseReplication" | "createIndex" | "listIndexes" | "dropIndex" | "getAutoIndexPolicy" | "setAutoIndexPolicy" | "listIndexRecommendations" | "applyIndexRecommendation" | "getDatabaseSchema" | "inferCollectionSchema" | "declareCollectionSchema" | "listQueryShapes" | "createSavedQuery" | "listSavedQueries" | "getSavedQuery" | "updateSavedQuery" | "deleteSavedQuery";
+export type ManagementOperation = "getShapeManifest" | "exportDatabase" | "executeSql" | "putCollectionTtl" | "getCollectionTtl" | "deleteCollectionTtl" | "healthz" | "readyz" | "backupz" | "replicationHealth" | "listPlatformDatabases" | "listPlatformCollections" | "listPlatformDocuments" | "getPlatformDocument" | "createImport" | "getImport" | "uploadImportSource" | "updateImport" | "startImport" | "cancelImport" | "resumeImport" | "createBackup" | "listBackups" | "restoreBackup" | "getBackupPolicy" | "setBackupPolicy" | "getRestoreWindow" | "planPointInTime" | "restorePointInTime" | "getBackupDestination" | "setBackupDestination" | "deleteBackupDestination" | "getProjectUsage" | "getProjectAnalytics" | "getProjectReplication" | "getDatabaseUsage" | "getDatabaseAnalytics" | "getDatabaseReplication" | "createIndex" | "listIndexes" | "dropIndex" | "getAutoIndexPolicy" | "setAutoIndexPolicy" | "listIndexRecommendations" | "applyIndexRecommendation" | "getDatabaseSchema" | "inferCollectionSchema" | "declareCollectionSchema" | "listQueryShapes" | "createSavedQuery" | "listSavedQueries" | "getSavedQuery" | "updateSavedQuery" | "deleteSavedQuery" | "createChangeWebhook" | "listChangeWebhooks" | "deleteChangeWebhook" | "listChangeWebhookDeliveries";

package/types/v1/sql-execute.d.ts

@@ -0,0 +1,61 @@
+/** @param {string} sql @param {V1SqlArguments | undefined} args @returns {V1SqlStatement} */
+export function sqlStatement(sql: string, args: V1SqlArguments | undefined): V1SqlStatement;
+/**
+ * Runs 1 to 256 statements as one transaction: all commit or none do. BEGIN, COMMIT and ROLLBACK are refused.
+ * A refused statement throws SqlError with its index.
+ * @param {V1Transport} transport
+ * @param {string} database
+ * @param {readonly (string | V1SqlStatement)[]} statements
+ * @param {V1RequestOptions} [options]
+ * @returns {Promise<readonly V1SqlExecuteResult[]>}
+ */
+export function executeSql(transport: V1Transport, database: string, statements: readonly (string | V1SqlStatement)[], options?: V1RequestOptions): Promise<readonly V1SqlExecuteResult[]>;
+/**
+ * Rows as objects keyed by column name; a later duplicate column name wins.
+ * @template [T=Record<string, V1SqlValue>]
+ * @param {V1SqlExecuteResult} result
+ * @returns {T[]}
+ */
+export function sqlRowObjects<T = Record<string, V1SqlValue>>(result: V1SqlExecuteResult): T[];
+/**
+ * An argument: null, a finite number, an int64 `bigint` or ExactDecimal, a boolean (stored as 1 or 0) or a string.
+ */
+export type V1SqlArgument = null | boolean | number | bigint | ExactDecimal | string;
+/**
+ * Positional array, or named values keyed without their `:`, `@` or `$` prefix.
+ */
+export type V1SqlArguments = readonly V1SqlArgument[] | Readonly<Record<string, V1SqlArgument>>;
+export type V1SqlStatement = {
+    sql: string;
+    /**
+     * Positional arguments.
+     */
+    args?: readonly V1SqlArgument[] | undefined;
+    /**
+     * Named arguments, keys without their prefix.
+     */
+    named?: Readonly<Record<string, V1SqlArgument>> | undefined;
+};
+/**
+ * A result value. Integers beyond 2^53 decode as ExactDecimal, keeping every digit; `BigInt(String(value))` converts one.
+ */
+export type V1SqlValue = null | number | ExactDecimal | string;
+/**
+ * A column; `decltype` is null for an expression.
+ */
+export type V1SqlColumn = {
+    readonly name: string;
+    readonly decltype: string | null;
+};
+export type V1SqlExecuteResult = {
+    columns: readonly V1SqlColumn[];
+    /**
+     * One value per column.
+     */
+    rows: readonly (readonly V1SqlValue[])[];
+    rowsAffected: number;
+    lastInsertRowid: number | ExactDecimal | null;
+};
+import type { V1Transport } from "./transport.js";
+import type { V1RequestOptions } from "./terrabase-v1.js";
+import { ExactDecimal } from "./json.js";

package/types/v1/terrabase-v1.d.ts

@@ -22,6 +22,8 @@ export class V1Collection {
      * @param {string} name
      */
     constructor(transport: V1Transport, database: string, name: string);
+    /** @type {V1ChangeWebhooks} */
+    webhooks: V1ChangeWebhooks;
     /** @type {string} */
     name: string;
     /** @type {string} */
@@ -293,6 +295,29 @@ export class V1Database {
     checkSql(statement: string, options?: V1RequestOptions): Promise<import("./sql.js").V1SqlCheck>;
     /** @param {string} statement @param {V1RequestOptions} [options] */
     explainSql(statement: string, options?: V1RequestOptions): Promise<import("./sql.js").V1SqlCheck>;
+    /**
+     * Runs one relational SQL statement as its own transaction. Reads need documents:read; writes and DDL need documents:write.
+     * @param {string} sql
+     * @param {import("./sql-execute.js").V1SqlArguments} [args] Positional array, or named values keyed without their prefix.
+     * @param {V1RequestOptions} [options]
+     * @returns {Promise<import("./sql-execute.js").V1SqlExecuteResult>}
+     */
+    execute(sql: string, args?: import("./sql-execute.js").V1SqlArguments, options?: V1RequestOptions): Promise<import("./sql-execute.js").V1SqlExecuteResult>;
+    /**
+     * Runs one statement and returns its rows as objects keyed by column name.
+     * @template [T=Record<string, import("./sql-execute.js").V1SqlValue>]
+     * @param {string} sql
+     * @param {import("./sql-execute.js").V1SqlArguments} [args]
+     * @param {V1RequestOptions} [options]
+     * @returns {Promise<T[]>}
+     */
+    query<T = Record<string, import("./sql-execute.js").V1SqlValue>>(sql: string, args?: import("./sql-execute.js").V1SqlArguments, options?: V1RequestOptions): Promise<T[]>;
+    /**
+     * Runs 1 to 256 statements as one transaction: all commit or none do. A refused statement throws SqlError.
+     * @param {readonly (string | import("./sql-execute.js").V1SqlStatement)[]} statements
+     * @param {V1RequestOptions} [options]
+     */
+    batch(statements: readonly (string | import("./sql-execute.js").V1SqlStatement)[], options?: V1RequestOptions): Promise<readonly import("./sql-execute.js").V1SqlExecuteResult[]>;
     /** @param {import("./changes.js").V1ChangeStreamRequest} [request] @param {V1RequestOptions} [options] */
     changes(request?: import("./changes.js").V1ChangeStreamRequest, options?: V1RequestOptions): AsyncGenerator<import("./changes.js").V1DatabaseChange | import("./changes.js").V1DatabaseChangeCursor, void, undefined>;
     /**
@@ -483,6 +508,7 @@ export type V1TransactionResult = {
 };
 import type { JsonValue } from "./json.js";
 import type { TerraBaseV1ClientConfig } from "./transport.js";
+import { V1ChangeWebhooks } from "./change-webhooks.js";
 import type { V1Document } from "./decode.js";
 import type { JsonInputObject } from "./json.js";
 import type { V1WriteResult } from "./decode.js";