skills/plugins/document-navigator/docs/persistence/database/surrealdb

@suaveplan/surrealdb - Universal SurrealDB client wrapper implementing DatabaseAdapter: connection lifecycle, singleton registry, typed CRUD, schema discovery, initialisation, version detection, OTel instrumentation, retry integration, and structured SURREAL.* error codes.

Summary

Universal SurrealDB client wrapper for Suaveplan. Implements @suaveplan/db's DatabaseAdapter interface with connection lifecycle management, typed CRUD, schema discovery, database initialisation, version detection, structured SURREAL.* error codes, and OTel instrumentation.

Documentation tree

• adapter — (no submodules)
  • adapter — (no submodules)
• crud — (no submodules)
  • crud — (no submodules)
• query-helpers — (no submodules)
  • query-helpers — (no submodules)
• transaction — (no submodules)
  • transaction — (no submodules)
• connection — (no submodules)
  • connection — (no submodules)
• errors — (no submodules)
  • error — (no submodules)
• init — (no submodules)
  • init — (no submodules)
• schema — (no submodules)
  • discovery — (no submodules)
• schemas — (no submodules)
  • schemas — (no submodules)
• singleton — (no submodules)
  • singleton — (no submodules)
• types — (no submodules)
  • types — (no submodules)
• utils — (no submodules)
  • version-detector — (no submodules)

- [adapter](./src/adapter/adapter/adapter.md) — _(no submodules)_- [crud](./src/adapter/crud/crud.md) — _(no submodules)_ - [crud](./src/adapter/crud/crud.md) — _(no submodules)_- [query-helpers](./src/adapter/query-helpers/query-helpers.md) — _(no submodules)_ - [query-helpers](./src/adapter/query-helpers/query-helpers.md) — _(no submodules)_- [transaction](./src/adapter/transaction/transaction.md) — _(no submodules)_ - [transaction](./src/adapter/transaction/transaction.md) — _(no submodules)_- [connection](./src/connection/connection.md) — _(no submodules)_- [connection](./src/connection/connection.md) — _(no submodules)_- [errors](./src/errors/error.md) — _(no submodules)_- [error](./src/errors/error.md) — _(no submodules)_- [init](./src/init/init.md) — _(no submodules)_- [init](./src/init/init.md) — _(no submodules)_- [schema](./src/schema/discovery.md) — _(no submodules)_- [discovery](./src/schema/discovery.md) — _(no submodules)_- [schemas](./src/schemas/schemas.md) — _(no submodules)_- [schemas](./src/schemas/schemas.md) — _(no submodules)_- [singleton](./src/singleton/singleton.md) — _(no submodules)_- [singleton](./src/singleton/singleton.md) — _(no submodules)_- [types](./src/types/types.md) — _(no submodules)_- [types](./src/types/types.md) — _(no submodules)_- [utils](./src/utils/version-detector.md) — _(no submodules)_- [version-detector](./src/utils/version-detector.md) — _(no submodules)_- [adapter](./src/adapter/adapter/adapter.md) — _(no submodules)_- [crud](./src/adapter/crud/crud.md) — `crud` exposes the typed record-level CRUD primitives (`create`, `select`, `update`, `delete`, `selectAll`) used by `Su…

• crud — crud exposes the typed record-level CRUD primitives (create, select, update, delete, selectAll) used by `Su…
• query-helpers — query-helpers holds the small, stateless utility functions shared by every public method on SurrealAdapter and its…
  • query-helpers — query-helpers holds the small, stateless utility functions shared by every public method on SurrealAdapter and its…
• transaction — transaction houses the SurrealDB transaction orchestration logic that wraps a caller-supplied function in a `BEGIN TR…
  • transaction — transaction houses the SurrealDB transaction orchestration logic that wraps a caller-supplied function in a `BEGIN TR…
• connection — (no submodules)- connection — (no submodules)- errors — (no submodules)- error — (no submodules)- init — (no submodules)- init — (no submodules)- schema — (no submodules)- discovery — (no submodules)- schemas — (no submodules)- schemas — (no submodules)- singleton — (no submodules)- singleton — (no submodules)- types — (no submodules)- types — (no submodules)- utils — (no submodules)- version-detector — (no submodules)- adapter — (no submodules)- crud — (no submodules)- query-helpers — (no submodules)- transaction — (no submodules)- connection — (no submodules)- connection — (no submodules)- errors — (no submodules)- error — (no submodules)- init — (no submodules)- init — (no submodules)- schema — (no submodules)- discovery — (no submodules)- schemas — (no submodules)- schemas — (no submodules)- singleton — (no submodules)- singleton — (no submodules)- types — (no submodules)- types — (no submodules)- utils — (no submodules)- version-detector — (no submodules)## Packages

Module	Description
errors/error	SurrealError class and SURREAL_CODES registry
types/types	Shared TypeScript types and the SurrealClientLike injection interface
schemas/schemas	Zod schemas for all public option types
connection/connection	Connection lifecycle and singleton registry
adapter/adapter	SurrealAdapter implementing DatabaseAdapter
adapter/crud	Typed record-level CRUD primitives
adapter/transaction	BEGIN/COMMIT/CANCEL TRANSACTION orchestration
adapter/query-helpers	Positional-param conversion, error wrapping, result flattening
schema/discovery	Schema file discovery, sorting, and reading
init/init	Database initialisation from schema files
utils/version-detector	SurrealDB version parsing and detection
singleton/singleton	Adapter-level singleton registry

Quick Start

import { SurrealAdapter } from "@suaveplan/surrealdb";

const adapter = new SurrealAdapter({
  url: "ws://localhost:8000",
  namespace: "prod",
  database: "app",
  username: "root",
  password: "root",
});

await adapter.connect();
const user = await adapter.create("user", { name: "Alice", email: "alice@example.com" });
console.log(user.id); // "user:alice..."
await adapter.disconnect();

Integration tests

The package ships a parallel test suite under tests/integration/ that exercises the adapter against a real SurrealDB v3.0.4 container via @suaveplan/testing-integration-surrealdb. The unit suite (src/**/*.test.ts) runs against a dependency-injected fake; the integration suite proves the same code paths work against the live engine.

Run the integration suite:

bunx turbo test:integration --filter=@suaveplan/surrealdb
# or, from the package directory:
bun run test:integration

Requirements:

• Docker available locally; the fixture pulls surrealdb/surrealdb:v3.0.4 on first run.
• @suaveplan/testing-integration and @suaveplan/testing-integration-surrealdb resolve as devDependencies (already wired).
• The integration config points at vitest.integration.config.ts (separate from the unit vitest.config.ts) and only matches tests/integration/**/*.integration.test.ts.

What the suite covers:

• connect → use → signin → query → close round-trip and parameter passthrough.
• DDL via execute("DEFINE TABLE …") followed by INFO FOR DB to confirm the schema took.
• transaction() commit-on-resolve / rollback-on-throw semantics.
• Lifecycle: getSingleton deduplication and closeAllSingletons ordering.
• Connection failure surfaces DB.CONNECTION_FAILED with the documented ConnectionRefused / Unable to connect patterns.
• Version detection against the pinned v3.0.4 image.
• The INSERT INTO workaround for the db.create() content-drop bug.
• Schema discovery returns the expected table/field shapes.

If Docker is unavailable, every integration test is skipped via skipIfUnavailable("surrealdb", inject) so CI does not falsely fail when the runner has no Docker daemon.