@schemic/surrealdb 0.1.0-alpha.0

package/src/cli/surreal-connect.ts

@@ -0,0 +1,112 @@
+// SurrealDB connection runtime — split out of cli/config.ts so that module stays dialect-neutral
+// (config types + loadConfig only). This is the Surreal driver's `connect` implementation; it imports
+// the surrealdb SDK and belongs to @schemic/surrealdb at the physical split.
+
+import type { ConnectionOverrides, ResolvedConfig } from "@schemic/core";
+import { escapeIdent, Surreal } from "surrealdb";
+import type { AuthLevel, SurrealParams } from "../config";
+
+const errMsg = (e: unknown) => (e instanceof Error ? e.message : String(e));
+
+const CONNECT_TIMEOUT_MS = 5_000;
+
+/** Reject if `promise` doesn't settle within `ms` — guards against a hung connect. */
+function withTimeout<T>(
+  promise: Promise<T>,
+  ms: number,
+  message: string,
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(message)), ms);
+    promise.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        reject(e);
+      },
+    );
+  });
+}
+
+/** Connect + authenticate + select the namespace/database. Caller closes the handle. */
+export async function connect(
+  config: ResolvedConfig,
+  over: ConnectionOverrides = {},
+): Promise<Surreal> {
+  const params = config.params as unknown as SurrealParams;
+  const url = over.url ?? params.url;
+  const namespace = over.namespace ?? params.namespace;
+  const database = over.database ?? params.database;
+  const username = over.username ?? params.username;
+  const password = over.password ?? params.password;
+  const level: AuthLevel = (over.authLevel ??
+    params.authLevel ??
+    "root") as AuthLevel;
+
+  const db = new Surreal();
+  // On ANY failure, close the handle before throwing — otherwise the SDK's reconnect timer
+  // keeps the event loop alive and the command hangs instead of exiting.
+  try {
+    try {
+      // `reconnect: false` so a dead server rejects immediately instead of entering a retry
+      // loop; `withTimeout` is a fallback for an unreachable host that never rejects.
+      await withTimeout(
+        db.connect(url, { reconnect: false }),
+        CONNECT_TIMEOUT_MS,
+        "connection timed out",
+      );
+    } catch (e) {
+      throw new Error(
+        `Can't reach SurrealDB at ${url} — is the server running? (${errMsg(e)})`,
+      );
+    }
+    if (username && password) {
+      // Scope the signin to the requested level (mirrors `surreal sql --auth-level`).
+      const auth =
+        level === "root"
+          ? { username, password }
+          : level === "namespace"
+            ? { namespace, username, password }
+            : { namespace, database, username, password };
+      try {
+        await db.signin(auth);
+      } catch (e) {
+        throw new Error(
+          `Authentication failed (auth level "${level}") — check SURREAL_USER / SURREAL_PASS. (${errMsg(e)})`,
+        );
+      }
+    }
+    // Best-effort: create the namespace/database when we likely have the rights. A `database`
+    // user can't define either; a `namespace` user can define databases; `root` can do both.
+    try {
+      if (level === "root") {
+        await db.query(
+          `DEFINE NAMESPACE IF NOT EXISTS ${escapeIdent(namespace)};`,
+        );
+      }
+      if (level !== "database") {
+        await db.use({ namespace });
+        await db.query(
+          `DEFINE DATABASE IF NOT EXISTS ${escapeIdent(database)};`,
+        );
+      }
+    } catch {
+      // insufficient privileges — assume the namespace/database already exist
+    }
+    try {
+      await db.use({ namespace, database });
+    } catch (e) {
+      throw new Error(
+        `Couldn't select ${namespace}/${database} — does it exist and do you have access? (${errMsg(e)})`,
+      );
+    }
+    return db;
+  } catch (e) {
+    // Fire-and-forget: closing a half-open socket can be slow; don't block the error path.
+    void db.close().catch(() => {});
+    throw e;
+  }
+}

package/src/cli/surreal-diff.ts

@@ -0,0 +1,321 @@
+// The SurrealDB STATEMENT-diff engine: builds canonical `DEFINE` snapshots from authored schemas
+// and diffs two snapshots into SurrealQL up/down (clause-level ALTER where possible). This is the
+// Surreal driver's internal diff strategy — invoked via `surrealDriver.diff` and the migrations
+// capability's `render`. The dialect-free diff DISPLAY + types live in `./diff`. In the package
+// split this module moves to `@schemic/surrealdb` (see docs/AUTHORING-SPLIT.md / MULTI-DB-SPIKE.md).
+
+import { relative } from "node:path";
+import type { AnyTable, AuthoredDef, Diff, DiffItem } from "@schemic/core";
+import type { DefineStatement } from "../ddl";
+import {
+  alterField,
+  alterTable,
+  emitDefStatement,
+  emitStatements,
+  overwriteStatement,
+  removeStatement,
+} from "../ddl";
+import { schemaStruct } from "./lower";
+import { deepEqual } from "./struct";
+import type { DbStructured, Snapshot, SnapshotStatement } from "./structure";
+
+const keyOf = (s: Pick<DefineStatement, "kind" | "name" | "table">) =>
+  `${s.kind}:${s.table ?? ""}:${s.name}`;
+
+/** Index a normalized DbStructured by statement key (matching `keyOf`) for structural equality. */
+function structIndex(db: DbStructured): Map<string, unknown> {
+  const idx = new Map<string, unknown>();
+  for (const t of db.tables) {
+    // The table STATEMENT is just the head — fields/indexes/events are their own statements.
+    idx.set(`table::${t.name}`, {
+      kind: t.kind,
+      schemafull: t.schemafull,
+      drop: t.drop,
+      comment: t.comment,
+      changefeed: t.changefeed,
+      permissions: t.permissions,
+    });
+    for (const f of t.fields) idx.set(`field:${t.name}:${f.name}`, f);
+    for (const i of t.indexes) idx.set(`index:${t.name}:${i.name}`, i);
+    for (const e of t.events) idx.set(`event:${t.name}:${e.name}`, e);
+  }
+  for (const fn of db.functions) idx.set(`function::${fn.name}`, fn);
+  for (const a of db.accesses) idx.set(`access::${a.name}`, a);
+  return idx;
+}
+
+/**
+ * Build the canonical snapshot (keyed `DEFINE` statements) for the current schemas: every table's
+ * statements, plus any standalone defs (`defineEvent`/`defineFunction`), keyed by kind+table+name.
+ */
+export function buildSnapshot(
+  tables: AnyTable[],
+  defs: AuthoredDef[] = [],
+  opts: {
+    fileOf?: Map<unknown, string>;
+    root?: string;
+    /** Also compute + store the normalized Struct-IR (for `diff --ts`). Off by default. */
+    withStruct?: boolean;
+  } = {},
+): Snapshot {
+  const statements: Record<string, SnapshotStatement> = {};
+  // The source file each object came from, project-root-relative for portable, readable snapshots.
+  const fileFor = (obj: unknown): string | undefined => {
+    const abs = opts.fileOf?.get(obj);
+    return abs ? (opts.root ? relative(opts.root, abs) : abs) : undefined;
+  };
+  for (const t of tables) {
+    const file = fileFor(t);
+    try {
+      for (const s of emitStatements(
+        t as unknown as Parameters<typeof emitStatements>[0],
+      ))
+        statements[keyOf(s)] = file ? { ...s, file } : s;
+    } catch (e) {
+      // Pin an emit failure (e.g. a non-Surreal field type) to the source file.
+      const msg = e instanceof Error ? e.message : String(e);
+      throw new Error(file ? `${msg}\n  in ${file}` : msg);
+    }
+  }
+  for (const d of defs) {
+    const s = emitDefStatement(
+      d as unknown as Parameters<typeof emitDefStatement>[0],
+    );
+    const file = fileFor(d);
+    statements[keyOf(s)] = file ? { ...s, file } : s;
+  }
+  const snap: Snapshot = { version: 1, statements };
+  if (opts.withStruct)
+    // Bridge the lib/src type duality (AnyTable is the built-lib TableDef; schemaStruct uses src).
+    snap.struct = schemaStruct(
+      tables as unknown as Parameters<typeof schemaStruct>[0],
+      defs as unknown as Parameters<typeof schemaStruct>[1],
+    );
+  return snap;
+}
+
+// Within a table, create order is table -> field -> index (each depends on the prior); drop
+// order is the reverse. Statements are grouped by table (see `diffSnapshots`).
+const RANK: Record<DefineStatement["kind"], number> = {
+  analyzer: 0, // db-level; defined first (a FULLTEXT index references its analyzer)
+  function: 0, // db-level; defined first (tables/events may reference fn::…)
+  table: 1,
+  field: 2,
+  index: 3,
+  event: 4,
+  access: 5, // db-level; defined last (SIGNUP/SIGNIN reference tables)
+};
+const tableOf = (s: DefineStatement) => s.table ?? s.name;
+
+/**
+ * The up-migration statement(s) for a CHANGED object:
+ *   - `table` -> a clause-level `ALTER TABLE` (falls back to `DEFINE … OVERWRITE` when the delta
+ *     can't be expressed via ALTER, e.g. a `TYPE` NORMAL/RELATION change or an older snapshot),
+ *   - `field` -> a clause-level `ALTER FIELD` (falls back to `DEFINE … OVERWRITE` when the delta
+ *     can't be expressed via ALTER, e.g. a `COMPUTED` change or an older snapshot w/o clauses),
+ *   - `index` -> `REMOVE` + `DEFINE` (ALTER INDEX can't change fields/kind),
+ *   - everything else (event/function/access) -> `DEFINE … OVERWRITE`.
+ */
+function changeUp(old: DefineStatement, next: DefineStatement): string[] {
+  if (next.kind === "table") {
+    const alt = alterTable(next.name, old.clauses, next.clauses);
+    return [alt ?? overwriteStatement(next.ddl)];
+  }
+  if (next.kind === "field") {
+    const alt = alterField(tableOf(next), next.name, old.clauses, next.clauses);
+    return [alt ?? overwriteStatement(next.ddl)];
+  }
+  if (next.kind === "index") return [removeStatement(old), next.ddl];
+  return [overwriteStatement(next.ddl)];
+}
+/** The inverse (next -> old) statement(s) for the down migration. */
+function changeDown(old: DefineStatement, next: DefineStatement): string[] {
+  if (next.kind === "table") {
+    const alt = alterTable(old.name, next.clauses, old.clauses);
+    return [alt ?? overwriteStatement(old.ddl)];
+  }
+  if (next.kind === "field") {
+    const alt = alterField(tableOf(old), old.name, next.clauses, old.clauses);
+    return [alt ?? overwriteStatement(old.ddl)];
+  }
+  if (next.kind === "index") return [removeStatement(next), old.ddl];
+  return [overwriteStatement(old.ddl)];
+}
+
+/**
+ * Diff two snapshots into `up`/`down` SurrealQL. Added/changed objects → `DEFINE` (with
+ * `OVERWRITE` when changed); dropped objects → `REMOVE`. `down` is the exact inverse, so a
+ * migration can be rolled back. Fields of a dropped/added table are skipped (the `TABLE`
+ * statement covers them).
+ */
+export function diffSnapshots(prev: Snapshot, next: Snapshot): Diff {
+  const prevS = prev.statements;
+  const nextS = next.statements;
+
+  // Group output by table: tables in snapshot order, each followed by its own fields/indexes.
+  const tableOrder = new Map<string, number>();
+  for (const s of [...Object.values(nextS), ...Object.values(prevS)]) {
+    const t = tableOf(s);
+    if (!tableOrder.has(t)) tableOrder.set(t, tableOrder.size);
+  }
+  const ord = (s: DefineStatement) => tableOrder.get(tableOf(s)) ?? 0;
+  const byCreate = (a: DefineStatement, b: DefineStatement) =>
+    ord(a) - ord(b) || RANK[a.kind] - RANK[b.kind];
+  const byDrop = (a: DefineStatement, b: DefineStatement) =>
+    ord(b) - ord(a) || RANK[b.kind] - RANK[a.kind];
+
+  const removed = Object.keys(prevS)
+    .filter((k) => !(k in nextS))
+    .map((k) => prevS[k]);
+  const removedTables = new Set(
+    removed.filter((s) => s.kind === "table").map((s) => s.name),
+  );
+
+  // Structural change-detection: a DDL difference that normalizes away (e.g. an enum/union/record
+  // reorder) is NOT a real change. Only applies when BOTH snapshots carry a Struct; older snapshots
+  // (or keys absent from the struct, like folded array elements) fall back to the DDL comparison.
+  const prevIdx = prev.struct ? structIndex(prev.struct) : null;
+  const nextIdx = next.struct ? structIndex(next.struct) : null;
+  const added: SnapshotStatement[] = [];
+  const changed: { old: SnapshotStatement; next: SnapshotStatement }[] = [];
+  for (const k of Object.keys(nextS)) {
+    const s = nextS[k];
+    if (!(k in prevS)) {
+      added.push(s);
+      continue;
+    }
+    if (prevS[k].ddl === s.ddl) continue;
+    if (prevIdx && nextIdx) {
+      const a = prevIdx.get(k);
+      const b = nextIdx.get(k);
+      if (a !== undefined && b !== undefined && deepEqual(a, b)) continue; // cosmetic-only
+    }
+    changed.push({ old: prevS[k], next: s });
+  }
+  const addedTables = new Set(
+    added.filter((s) => s.kind === "table").map((s) => s.name),
+  );
+
+  // A field/index whose owning table is dropped (or added) is covered by the TABLE statement.
+  const isOrphan = (s: DefineStatement, droppedTables: Set<string>) =>
+    s.kind !== "table" && droppedTables.has(s.table ?? "");
+
+  const up: string[] = [];
+  for (const s of removed
+    .filter((s) => !isOrphan(s, removedTables))
+    .sort(byDrop)) {
+    up.push(removeStatement(s));
+  }
+  for (const s of [...added].sort(byCreate)) up.push(s.ddl);
+  for (const c of [...changed].sort((a, b) => byCreate(a.next, b.next)))
+    up.push(...changeUp(c.old, c.next));
+
+  const down: string[] = [];
+  for (const s of added.filter((s) => !isOrphan(s, addedTables)).sort(byDrop)) {
+    down.push(removeStatement(s));
+  }
+  for (const s of [...removed].sort(byCreate)) down.push(s.ddl);
+  for (const c of [...changed].sort((a, b) => byCreate(a.next, b.next)))
+    down.push(...changeDown(c.old, c.next));
+
+  // Structured display items, grouped by table (table → its fields → its indexes).
+  const tagged: { sort: [number, number]; item: DiffItem }[] = [];
+  const at = (s: DefineStatement): [number, number] => [ord(s), RANK[s.kind]];
+  for (const s of removed.filter((s) => !isOrphan(s, removedTables))) {
+    tagged.push({
+      sort: at(s),
+      item: {
+        op: "remove",
+        kind: s.kind,
+        key: keyOf(s),
+        table: tableOf(s),
+        file: s.file,
+        ddl: removeStatement(s),
+        old: s.ddl,
+      },
+    });
+  }
+  for (const s of added) {
+    tagged.push({
+      sort: at(s),
+      item: {
+        op: "add",
+        kind: s.kind,
+        key: keyOf(s),
+        table: tableOf(s),
+        file: s.file,
+        ddl: s.ddl,
+      },
+    });
+  }
+  for (const c of changed) {
+    tagged.push({
+      sort: at(c.next),
+      item: {
+        op: "change",
+        kind: c.next.kind,
+        key: keyOf(c.next),
+        table: tableOf(c.next),
+        file: c.next.file ?? c.old.file,
+        before: c.old.ddl,
+        after: c.next.ddl,
+      },
+    });
+  }
+  tagged.sort((a, b) => a.sort[0] - b.sort[0] || a.sort[1] - b.sort[1]);
+  const items = tagged.map((t) => t.item);
+
+  const full = Object.values(nextS)
+    .sort(byCreate)
+    .map((s) => ({ key: keyOf(s), table: tableOf(s), ddl: s.ddl }));
+
+  return { up, down, items, full };
+}
+
+/** The table a statement targets (for grouping the migration body). */
+function stmtTable(s: string): string {
+  const on = /\bON (?:TABLE )?`?([^\s`;]+)`?/.exec(s);
+  if (on) return on[1];
+  const t = /\bTABLE (?:OVERWRITE |IF (?:NOT )?EXISTS )?`?([^\s`;]+)`?/.exec(s);
+  return t ? t[1] : "";
+}
+
+/** Indent statements, with a blank line between consecutive table groups. */
+const indent = (stmts: string[]): string => {
+  const out: string[] = [];
+  let prev: string | undefined;
+  for (const s of stmts) {
+    const t = stmtTable(s);
+    if (prev !== undefined && t !== prev) out.push("");
+    out.push(`    ${s}`);
+    prev = t;
+  }
+  return out.join("\n");
+};
+
+/**
+ * Render a migration as a single self-contained SurrealQL program. Applied with the
+ * `$direction` parameter bound to `"up"` or `"down"` — verified to support `DEFINE`/`REMOVE`
+ * inside `IF` blocks on SurrealDB 3.x.
+ */
+export function renderMigration(tag: string, diff: Diff): string {
+  // A migration is REPLAYED from a fixed file regardless of the database's current state (unlike
+  // `diff`/`push`, which recompute a delta each run), so its DEFINEs must be idempotent: re-marking
+  // them DEFINE … OVERWRITE re-applies cleanly whether or not the object already exists — and
+  // OVERWRITE preserves row data (REMOVEs already use IF EXISTS). This is what lets `schemic migrate`
+  // run against a database whose objects were applied out-of-band (e.g. `schemic push`/`schemic pull`). The
+  // changed-object statements are already OVERWRITE/ALTER, and `overwriteStatement` is a no-op on
+  // those and on REMOVE/ALTER, so only plain DEFINEs (added objects) gain the keyword.
+  const idempotent = (stmts: string[]) => stmts.map(overwriteStatement);
+  return [
+    `-- ${tag}`,
+    "-- Generated by @schemic/core. Review before applying.",
+    "",
+    'IF $direction = "up" {',
+    indent(idempotent(diff.up)),
+    "} ELSE {",
+    indent(idempotent(diff.down)),
+    "};",
+    "",
+  ].join("\n");
+}

package/src/cli/surreal-filter.ts

@@ -0,0 +1,67 @@
+// The SurrealDB STATEMENT/STRUCT filters — the dialect halves of the per-kind object filter. They
+// operate on `DefineStatement`/`Snapshot` (the statement engine) and `DbStructured` (introspection).
+// The dialect-free `Filter` definition + the portable-IR filters live in `./filter`. In the package
+// split this module moves to `@schemic/surrealdb` (see docs/MULTI-DB-SPIKE.md).
+
+import { type Filter, inCat } from "@schemic/core";
+import type { DefineStatement } from "../ddl";
+import type { DbStructured, Snapshot } from "./structure";
+
+/** Whether a `DefineStatement` passes the filter (table-scoped objects also need their table in). */
+export function included(f: Filter, s: DefineStatement): boolean {
+  const table = s.table ?? s.name;
+  switch (s.kind) {
+    case "table":
+    case "field":
+    case "index":
+      return inCat(f.tables, table);
+    case "event":
+      return inCat(f.tables, table) && inCat(f.events, s.name);
+    case "function":
+      return inCat(f.functions, s.name);
+    case "access":
+      return inCat(f.access, s.name);
+    case "analyzer":
+      // Analyzers are shared infra a FULLTEXT index depends on — always kept (no filter category).
+      return true;
+  }
+}
+
+/** Keep only the snapshot statements that pass the filter (for `diff`/`sync`/`generate`). */
+export function filterSnapshot(snap: Snapshot, f: Filter): Snapshot {
+  const statements: Record<string, DefineStatement> = {};
+  for (const [k, s] of Object.entries(snap.statements))
+    if (included(f, s)) statements[k] = s;
+  return { ...snap, statements };
+}
+
+/**
+ * The snapshot to persist after a filtered `generate`: included kinds take their new state from
+ * `next`, excluded kinds keep their prior state from `prev`. So generating without `--access`
+ * leaves the snapshot's access untouched (no phantom add/remove) rather than dropping it.
+ */
+export function mergeSnapshot(
+  prev: Snapshot,
+  next: Snapshot,
+  f: Filter,
+): Snapshot {
+  const statements: Record<string, DefineStatement> = {};
+  for (const [k, s] of Object.entries(prev.statements))
+    if (!included(f, s)) statements[k] = s;
+  for (const [k, s] of Object.entries(next.statements))
+    if (included(f, s)) statements[k] = s;
+  return { ...next, statements };
+}
+
+/** Keep only the introspected objects that pass the filter (for `pull`). */
+export function filterStructured(db: DbStructured, f: Filter): DbStructured {
+  const tables = db.tables
+    .filter((t) => inCat(f.tables, t.name))
+    .map((t) => ({
+      ...t,
+      events: t.events.filter((e) => inCat(f.events, e.name)),
+    }));
+  const functions = db.functions.filter((fn) => inCat(f.functions, fn.name));
+  const accesses = db.accesses.filter((a) => inCat(f.access, a.name));
+  return { tables, functions, accesses, analyzers: db.analyzers };
+}

package/src/config.ts

@@ -0,0 +1,94 @@
+// SurrealDB-specific config types — relocated out of @schemic/core/config, which is now connections-only
+// and dialect-free. A `surrealConnection({ … })` carries these; the resolution engine strips the neutral
+// base (schema/key/migrations) and the rest lands in `ResolvedConfig.params` (read it as {@link SurrealParams}).
+
+/** Which level to authenticate at — mirrors `surreal sql --auth-level`. */
+export type AuthLevel = "root" | "namespace" | "database";
+
+/** A SurrealDB connection's params (the surreal-specific half of a `surrealConnection` config). */
+export interface SurrealZodConnection {
+  /** Endpoint, e.g. `ws://localhost:8000` or `http://localhost:8000`. */
+  url: string;
+  /** Target namespace. */
+  namespace: string;
+  /** Target database. */
+  database: string;
+  /** Auth username. */
+  username?: string;
+  /** Auth password. */
+  password?: string;
+  /**
+   * Level to sign in at: `root` (default), `namespace`, or `database`. Determines the
+   * signin payload — `namespace`/`database` scope the credentials to that ns/db.
+   */
+  authLevel?: AuthLevel;
+}
+
+/** An allow/deny list for a single capability — mirrors `@surrealdb/node`. */
+export interface CapabilityList {
+  allow?: boolean | string[];
+  deny?: boolean | string[];
+}
+
+/** Capabilities for the embedded check engine — mirrors `@surrealdb/node`'s `capabilities` option. */
+export interface EmbeddedCapabilities {
+  scripting?: boolean;
+  guest_access?: boolean;
+  live_query_notifications?: boolean;
+  functions?: boolean | string[] | CapabilityList;
+  network_targets?: boolean | string[] | CapabilityList;
+  experimental?: boolean | string[] | CapabilityList;
+}
+
+/**
+ * Run `schemic check`'s replay on an EMBEDDED in-process SurrealDB via the optional `@surrealdb/node`
+ * package (install it yourself — `npm i -D @surrealdb/node`). Options pass through to
+ * `createNodeEngines`; `backend`/`path` choose the storage. No external server, your data untouched.
+ */
+export interface SurrealZodCheckEmbedded {
+  /** Storage backend. `memory` (default) is throwaway in-RAM; the others persist to `path`. */
+  backend?: "memory" | "surrealkv" | "surrealkv+versioned" | "rocksdb";
+  /** Filesystem path for the persistent backends (ignored for `memory`). */
+  path?: string;
+  /** Capabilities for the instance. Default: all allowed, so asserts/defaults/functions work. */
+  capabilities?: boolean | EmbeddedCapabilities;
+  /** SurrealDB strict mode. */
+  strict?: boolean;
+  /** Query timeout. */
+  query_timeout?: number;
+  /** Transaction timeout. */
+  transaction_timeout?: number;
+}
+
+/** `schemic check` options (lives on a SurrealDB connection's config; rides into `params.check`). */
+export interface SurrealZodCheck {
+  /**
+   * Engine for the migration replay:
+   *  - `"auto"` (default) — if the `surreal` CLI is on PATH, spin up an ephemeral in-memory instance
+   *    (your EXACT SurrealDB version, no external server, your data untouched); otherwise fall back to
+   *    the `check.db` server.
+   *  - `"binary"` — require the local `surreal` CLI (error if it's missing).
+   *  - `"remote"` — always use the `check.db` server (throwaway scratch databases on it).
+   *  - an embedded object (`{ backend, capabilities, … }`) — run in-process via the optional
+   *    `@surrealdb/node` package. See {@link SurrealZodCheckEmbedded}.
+   */
+  engine?: "auto" | "binary" | "remote" | SurrealZodCheckEmbedded;
+  /** Path to the `surreal` CLI for the `auto`/`binary` engines. Default: `surreal` on PATH. */
+  binary?: string;
+  /**
+   * Connection used for the `remote` engine, merged field-by-field over the connection's own params.
+   * The replay spins up throwaway scratch databases and drops them — it NEVER reads or writes your real
+   * database — but it DOES reach the server. Point this at a local/scratch SurrealDB so `schemic check`
+   * never touches production. Falls back to the connection params for any field you omit.
+   */
+  db?: Partial<SurrealZodConnection>;
+}
+
+/**
+ * The SurrealDB-specific bag carried in `ResolvedConfig.params`: the connection params plus the optional
+ * `check` replay config. `connect`/`introspect`/`checkReplay` read `config.params as SurrealParams`.
+ */
+export interface SurrealParams extends SurrealZodConnection {
+  /** `schemic check` overrides — e.g. a dedicated connection for its migration replay. */
+  check?: SurrealZodCheck;
+}

package/src/connection.ts

@@ -0,0 +1,51 @@
+// The SurrealDB connection factory — binds the neutral `connectionEntry` (from @schemic/core) to the
+// SurrealDB connection shape, so `defineConfig({ connections: { … } })` gets a typed `surrealConnection`
+// with no hand-authored `driver: "…"` string. Design: @schemic/core docs/MULTI-CONNECTION.md.
+
+import {
+  type ConnectionConfigBase,
+  type ConnectionEntry,
+  type ConnectionInput,
+  connectionEntry,
+  type ResolveContext,
+} from "@schemic/core/driver";
+import type { SurrealZodCheck, SurrealZodConnection } from "./config";
+
+/**
+ * A SurrealDB connection's config: the dialect-neutral base (`schema`, optional `key`/`migrations`)
+ * plus the SurrealDB-specific connection params and the optional `check` replay config. Read env
+ * yourself in a resolver if you need it — there is no implicit `SURREAL_*` magic. The resolution engine
+ * strips the neutral base; the surreal half (url/namespace/…/check) lands in `ResolvedConfig.params`.
+ */
+export interface SurrealConnectionConfig
+  extends ConnectionConfigBase,
+    SurrealZodConnection {
+  /** `schemic check` overrides — e.g. a dedicated scratch connection for the migration replay. */
+  check?: SurrealZodCheck;
+}
+
+/**
+ * Build a SurrealDB {@link ConnectionEntry} for a config's `connections` map. Three forms:
+ * a single static config, a resolver returning one config, or a resolver returning a keyed
+ * COLLECTION (one connection per entry — `key` is then required and addressable as `<name>:<key>`).
+ */
+export function surrealConnection(
+  config: SurrealConnectionConfig,
+): ConnectionEntry;
+export function surrealConnection(
+  resolve: (
+    ctx: ResolveContext,
+  ) => SurrealConnectionConfig | Promise<SurrealConnectionConfig>,
+): ConnectionEntry;
+export function surrealConnection(
+  resolve: (
+    ctx: ResolveContext,
+  ) =>
+    | (SurrealConnectionConfig & { key: string })[]
+    | Promise<(SurrealConnectionConfig & { key: string })[]>,
+): ConnectionEntry;
+export function surrealConnection(
+  input: ConnectionInput<SurrealConnectionConfig>,
+): ConnectionEntry {
+  return connectionEntry<SurrealConnectionConfig>("surrealdb", input);
+}