# @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.

<!-- begin:auto-docs -->
## Documentation tree

- [adapter](./src/adapter/adapter/adapter.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [adapter](./src/adapter/adapter/adapter.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [crud](./src/adapter/crud/crud.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [crud](./src/adapter/crud/crud.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [query-helpers](./src/adapter/query-helpers/query-helpers.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [query-helpers](./src/adapter/query-helpers/query-helpers.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [transaction](./src/adapter/transaction/transaction.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [transaction](./src/adapter/transaction/transaction.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [connection](./src/connection/connection.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [connection](./src/connection/connection.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [errors](./src/errors/error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [error](./src/errors/error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [init](./src/init/init.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [init](./src/init/init.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [schema](./src/schema/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [discovery](./src/schema/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [schemas](./src/schemas/schemas.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [schemas](./src/schemas/schemas.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [singleton](./src/singleton/singleton.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [singleton](./src/singleton/singleton.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [utils](./src/utils/version-detector.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [version-detector](./src/utils/version-detector.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
<!-- end:auto-docs -->  - [adapter](./src/adapter/adapter/adapter.md) — <!-- begin:auto-docs --> _(no submodules)_- [crud](./src/adapter/crud/crud.md) — <!-- begin:auto-docs --> _(no submodules)_  - [crud](./src/adapter/crud/crud.md) — <!-- begin:auto-docs --> _(no submodules)_- [query-helpers](./src/adapter/query-helpers/query-helpers.md) — <!-- begin:auto-docs --> _(no submodules)_  - [query-helpers](./src/adapter/query-helpers/query-helpers.md) — <!-- begin:auto-docs --> _(no submodules)_- [transaction](./src/adapter/transaction/transaction.md) — <!-- begin:auto-docs --> _(no submodules)_  - [transaction](./src/adapter/transaction/transaction.md) — <!-- begin:auto-docs --> _(no submodules)_- [connection](./src/connection/connection.md) — <!-- begin:auto-docs --> _(no submodules)_- [connection](./src/connection/connection.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/error.md) — <!-- begin:auto-docs --> _(no submodules)_- [error](./src/errors/error.md) — <!-- begin:auto-docs --> _(no submodules)_- [init](./src/init/init.md) — <!-- begin:auto-docs --> _(no submodules)_- [init](./src/init/init.md) — <!-- begin:auto-docs --> _(no submodules)_- [schema](./src/schema/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [discovery](./src/schema/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [singleton](./src/singleton/singleton.md) — <!-- begin:auto-docs --> _(no submodules)_- [singleton](./src/singleton/singleton.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [utils](./src/utils/version-detector.md) — <!-- begin:auto-docs --> _(no submodules)_- [version-detector](./src/utils/version-detector.md) — <!-- begin:auto-docs --> _(no submodules)_- [adapter](./src/adapter/adapter/adapter.md) — <!-- begin:auto-docs --> _(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](./src/adapter/crud/crud.md) — `crud` exposes the typed record-level CRUD primitives (`create`, `select`, `update`, `delete`, `selectAll`) used by `Su…
- [query-helpers](./src/adapter/query-helpers/query-helpers.md) — `query-helpers` holds the small, stateless utility functions shared by every public method on `SurrealAdapter` and its…
  - [query-helpers](./src/adapter/query-helpers/query-helpers.md) — `query-helpers` holds the small, stateless utility functions shared by every public method on `SurrealAdapter` and its…
- [transaction](./src/adapter/transaction/transaction.md) — `transaction` houses the SurrealDB transaction orchestration logic that wraps a caller-supplied function in a `BEGIN TR…
  - [transaction](./src/adapter/transaction/transaction.md) — `transaction` houses the SurrealDB transaction orchestration logic that wraps a caller-supplied function in a `BEGIN TR…
- [connection](./src/connection/connection.md) — <!-- begin:auto-docs --> _(no submodules)_- [connection](./src/connection/connection.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/error.md) — <!-- begin:auto-docs --> _(no submodules)_- [error](./src/errors/error.md) — <!-- begin:auto-docs --> _(no submodules)_- [init](./src/init/init.md) — <!-- begin:auto-docs --> _(no submodules)_- [init](./src/init/init.md) — <!-- begin:auto-docs --> _(no submodules)_- [schema](./src/schema/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [discovery](./src/schema/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [singleton](./src/singleton/singleton.md) — <!-- begin:auto-docs --> _(no submodules)_- [singleton](./src/singleton/singleton.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [utils](./src/utils/version-detector.md) — <!-- begin:auto-docs --> _(no submodules)_- [version-detector](./src/utils/version-detector.md) — <!-- begin:auto-docs --> _(no submodules)_- [adapter](./src/adapter/adapter/adapter.md) — <!-- begin:auto-docs --> _(no submodules)_- [crud](./src/adapter/crud/crud.md) — <!-- begin:auto-docs --> _(no submodules)_- [query-helpers](./src/adapter/query-helpers/query-helpers.md) — <!-- begin:auto-docs --> _(no submodules)_- [transaction](./src/adapter/transaction/transaction.md) — <!-- begin:auto-docs --> _(no submodules)_- [connection](./src/connection/connection.md) — <!-- begin:auto-docs --> _(no submodules)_- [connection](./src/connection/connection.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/error.md) — <!-- begin:auto-docs --> _(no submodules)_- [error](./src/errors/error.md) — <!-- begin:auto-docs --> _(no submodules)_- [init](./src/init/init.md) — <!-- begin:auto-docs --> _(no submodules)_- [init](./src/init/init.md) — <!-- begin:auto-docs --> _(no submodules)_- [schema](./src/schema/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [discovery](./src/schema/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [singleton](./src/singleton/singleton.md) — <!-- begin:auto-docs --> _(no submodules)_- [singleton](./src/singleton/singleton.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [utils](./src/utils/version-detector.md) — <!-- begin:auto-docs --> _(no submodules)_- [version-detector](./src/utils/version-detector.md) — <!-- begin:auto-docs --> _(no submodules)_## Packages

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

## Quick Start

```ts
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:

```bash
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.