first commit

docs/persistence/database/migration/src/adapters/surrealdb/surrealdb.md

@@ -0,0 +1,60 @@
+# surrealdb-adapter
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`SurrealDbAdapter` adapts a SurrealDB instance to the minimal `execute`/`query` interface required by `DatabaseMigrationStore` and migration context objects. Because SurrealDB uses named query variables rather than positional parameters, this adapter translates positional `params` arrays to `{ p0, p1, … }` named variable maps automatically. This allows the same migration SQL templates to work across SQLite (positional `?`) and SurrealDB (named `$p0`) by using a consistent calling convention.
+
+## Features
+
+- `query<T>(sql, params?)` — executes a SurrealDB query and returns typed results.
+- `execute(sql, params?)` — executes a non-query statement; always returns `{ rowsAffected: 0 }` (SurrealDB does not expose row counts).
+- Translates positional params array to named vars (`p0`, `p1`, …).
+- Wraps errors in `MigrationError(MIGRATION.STORE_ERROR)` or `MIGRATION.FAILED`.
+
+## Usage: Basic Example
+
+```ts
+import { SurrealDbAdapter } from "@suaveplan/migration";
+import { DatabaseMigrationStore } from "@suaveplan/migration";
+import Surreal from "surrealdb";
+
+const db = new Surreal();
+await db.connect("http://localhost:8000");
+
+const adapter = new SurrealDbAdapter({ db });
+const store = new DatabaseMigrationStore({ adapter });
+```
+
+## Usage: Advanced Example
+
+```ts
+import { SurrealDbAdapter } from "@suaveplan/migration";
+import { MigrationRunner, MemoryMigrationStore } from "@suaveplan/migration";
+
+const adapter = new SurrealDbAdapter({ db: surrealInstance });
+const store = new MemoryMigrationStore(); // or DatabaseMigrationStore
+const runner = new MigrationRunner({ migrations, store });
+```
+
+## API Reference
+
+### `class SurrealDbAdapter`
+
+**Constructor**: `(config: SurrealDbAdapterConfig)`
+
+- `config.db` — object implementing `query<T>(sql, vars?): Promise<T[]>`.
+
+### `query<T>(sql: string, params?: readonly unknown[]): Promise<T[]>`
+
+Translates params to named vars and delegates to `db.query`. Returns an empty array if the result is not an array.
+
+### `execute(sql: string, params?: readonly unknown[]): Promise<{ rowsAffected: number }>`
+
+Executes SQL via `db.query`. Always returns `{ rowsAffected: 0 }`.
+
+## Implementation Notes
+
+SurrealDB's `query` method returns an array of result sets per SQL statement. This adapter flattens the outer array and returns the first result set. For multi-statement SQL, callers should split statements and call `query` for each.