neoorm 0.9.5 → 0.9.7

package/dist/seed/runner.js

@@ -0,0 +1,99 @@
+import { stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { schemaError } from "../runtime/error-builders.js";
+import { SchemaErrorCode } from "../runtime/error-codes.js";
+import { importTsModule } from "../utils/load-ts.js";
+const SEED_EXTENSIONS = [".ts", ".mts", ".cts"];
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+async function isFile(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function firstExisting(paths) {
+    for (const path of paths) {
+        if (await isFile(path)) {
+            return path;
+        }
+    }
+    return undefined;
+}
+function seedFileSuggestions(lookedFor) {
+    return [
+        `Create ${lookedFor[0]} exporting \`export async function seed(db) { ... }\``,
+        "Or pass an explicit path with --file <path>",
+    ];
+}
+/**
+ * Resolve which seed file to run. Precedence: `--file` → config
+ * `seed.file` → `seeds/<env>.ts` → `seed.ts` next to the schema.
+ * Throws `invalid_seed` when nothing resolves.
+ */
+export async function resolveSeedFile(options) {
+    if (options.file) {
+        return resolve(options.cwd, options.file);
+    }
+    if (options.configFile) {
+        return resolve(options.cwd, options.configFile);
+    }
+    const schemaDir = dirname(options.schemaPath);
+    if (options.env) {
+        const candidates = SEED_EXTENSIONS.map((ext) => join(schemaDir, "seeds", `${options.env}${ext}`));
+        const found = await firstExisting(candidates);
+        if (!found) {
+            throw schemaError(SchemaErrorCode.invalid_seed, `No seed file found for --env "${options.env}". Looked for: ${candidates.join(", ")}.`, undefined, seedFileSuggestions(candidates));
+        }
+        return found;
+    }
+    const candidates = SEED_EXTENSIONS.map((ext) => join(schemaDir, `seed${ext}`));
+    const found = await firstExisting(candidates);
+    if (!found) {
+        throw schemaError(SchemaErrorCode.invalid_seed, `No seed file found. Looked for: ${candidates.join(", ")}.`, undefined, seedFileSuggestions(candidates));
+    }
+    return found;
+}
+/**
+ * Load the `seed(db)` export from a seed file. Accepts a named `seed`
+ * export or a default-exported function.
+ */
+export async function loadSeedFunction(seedPath) {
+    let mod;
+    try {
+        mod = await importTsModule(seedPath);
+    }
+    catch (err) {
+        throw schemaError(SchemaErrorCode.invalid_seed, `Could not load seed file "${seedPath}": ${err instanceof Error ? err.message : String(err)}`, undefined, ["Check the path and that the file compiles"]);
+    }
+    const exported = mod.seed;
+    const defaultExport = mod.default;
+    const fromDefault = typeof defaultExport === "function"
+        ? defaultExport
+        : isRecord(defaultExport)
+            ? defaultExport.seed
+            : undefined;
+    const fn = exported ?? fromDefault;
+    if (typeof fn !== "function") {
+        throw schemaError(SchemaErrorCode.invalid_seed, `Seed file "${seedPath}" must export a seed function: \`export async function seed(db) { ... }\`.`, undefined, ["Export a named `seed` function or a default function"]);
+    }
+    return fn;
+}
+/**
+ * Run a seed file inside a single transaction. Any failure rolls the whole
+ * seed back, so failed runs are safe to retry. Execution errors propagate
+ * unwrapped so their original code and context are preserved.
+ */
+export async function runSeed(db, seedPath) {
+    const seed = await loadSeedFunction(seedPath);
+    await db.$transaction(async (tx) => {
+        // The runtime shape is identical for every manifest (repositories by
+        // accessor); only the static table types differ, so seed files may
+        // annotate with their own `TransactionClient<typeof schema._tables>`.
+        await seed(tx);
+    });
+}
+//# sourceMappingURL=runner.js.map

package/dist/seed/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/seed/runner.ts"],"names":[],"mappings":"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"}

package/dist/sql/split-statements.d.ts

@@ -0,0 +1,15 @@
+export type SplitStatementsOptions = {
+    /**
+     * Treat `\` as an escape character inside quoted strings and quoted
+     * identifiers (MySQL/MariaDB string syntax). Off by default: SQLite and
+     * PostgreSQL treat a backslash as a literal character in strings.
+     */
+    backslashEscapes?: boolean;
+};
+/**
+ * Split a SQL script into individual statements on `;` boundaries, honoring
+ * quoted strings, quoted identifiers (backticks/double quotes), and
+ * line/block comments — so `;` inside any of them never splits.
+ */
+export declare function splitStatements(sql: string, options?: SplitStatementsOptions): string[];
+//# sourceMappingURL=split-statements.d.ts.map

package/dist/sql/split-statements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"split-statements.d.ts","sourceRoot":"","sources":["../../src/sql/split-statements.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,sBAAsB,GAAG;IACpC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,eAAe,CAC9B,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,sBAAsB,GAC9B,MAAM,EAAE,CA6HV"}

package/dist/sql/split-statements.js

@@ -0,0 +1,132 @@
+/**
+ * Split a SQL script into individual statements on `;` boundaries, honoring
+ * quoted strings, quoted identifiers (backticks/double quotes), and
+ * line/block comments — so `;` inside any of them never splits.
+ */
+export function splitStatements(sql, options) {
+    const backslash = options?.backslashEscapes === true;
+    const statements = [];
+    let current = "";
+    let inSingle = false;
+    let inDouble = false;
+    let inBacktick = false;
+    let inLineComment = false;
+    let inBlockComment = false;
+    for (let i = 0; i < sql.length; i++) {
+        const ch = sql[i];
+        const next = sql[i + 1];
+        if (inLineComment) {
+            current += ch;
+            if (ch === "\n")
+                inLineComment = false;
+            continue;
+        }
+        if (inBlockComment) {
+            current += ch;
+            if (ch === "*" && next === "/") {
+                current += next;
+                i++;
+                inBlockComment = false;
+            }
+            continue;
+        }
+        if (inSingle) {
+            current += ch;
+            if (backslash && ch === "\\") {
+                if (next !== undefined) {
+                    current += next;
+                    i++;
+                }
+                continue;
+            }
+            if (ch === "'") {
+                if (next === "'") {
+                    current += next;
+                    i++;
+                }
+                else {
+                    inSingle = false;
+                }
+            }
+            continue;
+        }
+        if (inDouble) {
+            current += ch;
+            if (backslash && ch === "\\") {
+                if (next !== undefined) {
+                    current += next;
+                    i++;
+                }
+                continue;
+            }
+            if (ch === '"') {
+                if (next === '"') {
+                    current += next;
+                    i++;
+                }
+                else {
+                    inDouble = false;
+                }
+            }
+            continue;
+        }
+        if (inBacktick) {
+            current += ch;
+            if (backslash && ch === "\\") {
+                if (next !== undefined) {
+                    current += next;
+                    i++;
+                }
+                continue;
+            }
+            if (ch === "`") {
+                if (next === "`") {
+                    current += next;
+                    i++;
+                }
+                else {
+                    inBacktick = false;
+                }
+            }
+            continue;
+        }
+        if (ch === "-" && next === "-") {
+            inLineComment = true;
+            current += ch;
+            continue;
+        }
+        if (ch === "/" && next === "*") {
+            inBlockComment = true;
+            current += ch;
+            continue;
+        }
+        if (ch === "'") {
+            inSingle = true;
+            current += ch;
+            continue;
+        }
+        if (ch === '"') {
+            inDouble = true;
+            current += ch;
+            continue;
+        }
+        if (ch === "`") {
+            inBacktick = true;
+            current += ch;
+            continue;
+        }
+        if (ch === ";") {
+            if (current.trim().length > 0) {
+                statements.push(current.trim());
+            }
+            current = "";
+            continue;
+        }
+        current += ch;
+    }
+    if (current.trim().length > 0) {
+        statements.push(current.trim());
+    }
+    return statements.length > 0 ? statements : [sql];
+}
+//# sourceMappingURL=split-statements.js.map

package/dist/sql/split-statements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"split-statements.js","sourceRoot":"","sources":["../../src/sql/split-statements.ts"],"names":[],"mappings":"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"}

package/docs/cli.md

@@ -30,7 +30,7 @@ neoorm generate [options]
 ```
 
 Options:
-- `-n, --name <name>` — migration name (e.g. `--name add_users`). Required when a migration is created; prompts interactively on a TTY when omitted, errors in CI. Folders are `<timestamp>_<slug>` with the slug capped at 50 chars. No-change runs (client regeneration only) succeed without `--name`.
+- `-n, --name <name>` — migration name (e.g. `--name add_users`). Only needed when a migration is created: prompts on a TTY at that point, errors in CI. Folders are `<timestamp>_<slug>` with the slug capped at 50 chars. No-change runs (client regeneration only) and pending-apply-only `dev` runs never prompt and succeed without `--name`.
 - `--accept-data-loss` — include destructive DDL changes (column drops, type changes)
 
 ## `neoorm migrate dev`
@@ -41,7 +41,22 @@ Apply pending migrations, then generate a new migration if the schema changed. I
 neoorm migrate dev --name <name>
 ```
 
-- `-n, --name <name>` — same as `generate`: required when `dev` creates a migration, prompts on a TTY, errors in CI. Not used by `deploy`, `status`, `reset`, or `down`.
+- `-n, --name <name>` — same as `generate`: only needed when `dev` creates a migration, prompts on a TTY at that point, errors in CI. Applying pending migrations never requires `--name`. Not used by `deploy`, `status`, `reset`, or `down`.
+
+## `neoorm migrate diff`
+
+Preview the migration SQL `generate` / `migrate dev` would write, without writing anything.
+
+```
+neoorm migrate diff [--accept-data-loss] [--json]
+```
+
+Read-only: diffs `schema.ts` against `snapshot.json` only. No database connection, no files written, and `--name` is never needed (ignored if passed). Shows the exact statements that would go into `migration.sql`, so you can inspect a change before naming it.
+
+- `--accept-data-loss` — include destructive DDL in the preview (by default destructive changes are reported as blocked, same as `generate`)
+- `--json` — print `{ schemaChanged, sql, blocked, destructiveBlocked, warnings }` instead of human-readable text
+
+Exit code is `1` when destructive changes would block the migration (mirrors `generate`), `0` otherwise. For already-written but unapplied migrations, use `migrate status`.
 
 ## `neoorm migrate deploy`
 
@@ -86,6 +101,19 @@ neoorm migrate reset --force [--skip-apply]
 
 PostgreSQL: the connecting role owns the recreated schema. `PUBLIC` is not granted.
 
+## `neoorm seed`
+
+Run a seed script against the database inside a single transaction. Any failure rolls the whole seed back.
+
+```
+neoorm seed [--env <name>] [--file <path>]
+```
+
+- `--env <name>` — run `seeds/<name>.ts` (next to `schema.ts`) instead of `seed.ts`
+- `--file <path>` — run a specific seed file (wins over `--env` and config)
+
+Resolution order: `--file` → config `seed.file` → `seeds/<env>.ts` → `seed.ts`. The client is compiled from `schema.ts`, so seeding works on a fresh checkout with no codegen. Write idempotent seeds (`upsert`, `findOrCreate`, `createMany` with `skipDuplicates`) — re-runs are by convention, there is no seed ledger. See [Seeding](seeding.md).
+
 ## `neoorm docs`
 
 Serve the NeoOrm documentation locally in your browser.

package/docs/configuration.md

@@ -33,6 +33,8 @@ CLI commands load `.env` from the project directory before evaluating this file,
 | `generate.zod` | `boolean` | `false` | Emit Select/Create/Update Zod schemas to `out/zod.ts`. See [Zod schemas](zod.md). |
 | `generate.typebox` | `boolean` | `false` | Emit Select/Create/Update TypeBox schemas to `out/typebox.ts`. See [TypeBox schemas](typebox.md). |
 | `generate.elysia` | `boolean` | `false` | Emit Select/Create/Update Elysia `t` schemas to `out/elysia.ts`. See [Elysia schemas](elysia.md). |
+| `seed.file` | `string` | unset | Default seed file, project-root relative. CLI `--file` overrides it. See [Seeding](seeding.md). |
+| `seed.env` | `string` | unset | Default environment: runs `seeds/<env>.ts` next to the schema. CLI `--env` overrides it. |
 
 ### Validation emit
 

package/docs/migrate-dev-workflow.md

@@ -0,0 +1,84 @@
+# `migrate dev` Workflow
+
+This guide records the workflow contract and the implementation changes behind `neoorm migrate dev`. The refactor preserves the command's migration order and user-visible output timing.
+
+## Runtime contract
+
+`runMigrateDev` derives `migrationsDir` from `outDir` and runs the complete sequence inside `withMigrateDevLock`:
+
+1. Read the snapshot, compile the target schema, reconcile pending `CREATE TABLE` migrations against the live database, then apply remaining pending migrations.
+2. Generate from the current schema. If generation fails with the existing missing-migration-name error, no explicit name was supplied, and the CLI provided an interactive prompt callback, ask once and retry once. Other errors propagate unchanged. If generation needs no migration, it does not prompt.
+3. Emit the generation summary and warnings, then reconcile a newly written migration against existing tables or apply it when reconciliation did not record it.
+4. Return whether destructive changes were blocked; the CLI sets `process.exitCode` after the workflow completes.
+
+The lock covers snapshot reading, both reconciliation/deployment phases, generation, and the optional prompt. Progress events keep the CLI output at the same stage as before: pending-migration output precedes a possible prompt, while generation output precedes post-generation reconciliation/application.
+
+## File-by-file changes
+
+### `src/migrate/dev-workflow.ts`
+
+- **Before:** The ordered `migrate dev` sequence had no dedicated workflow module; the CLI path coordinated it.
+- **After:** `runMigrateDev` owns snapshot reading, initial reconciliation/deployment, generation, the optional one-shot prompt/retry, and post-generation reconciliation/deployment. A typed progress-event union reports completed stages, while existing migration and code-generation helpers remain responsible for their work. The migration directory is derived from `outDir`.
+- **Why it is useful:** The lock scope and ordering have one owner, and the workflow can be tested through a small interface without a CLI/TTY harness.
+
+### `src/bin/neoorm.ts`
+
+- **Before:** The CLI command path contained the `migrate dev` orchestration alongside the separate `migrate deploy` path.
+- **After:** `migrate dev` calls `runMigrateDev`, adapts its progress events to the existing console output, supplies the prompt callback only for interactive runs, and handles the returned destructive-blocked status. `migrate deploy` remains on its separate path.
+- **Why it is useful:** Terminal interaction and presentation stay in the CLI, while moving orchestration does not delay or reorder output around the prompt.
+
+### `src/codegen/generate.ts`
+
+- **Before:** The missing-migration-name predicate lived in the CLI even though both regular `generate` and `migrate dev` use it.
+- **After:** The same predicate lives beside `missingMigrationNameError` in the code-generation module and is shared by both callers.
+- **Why it is useful:** There is one definition of the narrow prompt-eligibility check; its error conditions are unchanged, not broadened into general error handling.
+
+### `test/migrate-dev-workflow.test.ts`
+
+- **Before:** Existing tests covered migration, generation, and lock helpers separately, but not their ordering at the workflow boundary.
+- **After:** Real in-memory SQLite tests verify that a pending migration is applied and the lock remains held when the controlled name prompt runs, and that an unchanged schema completes without prompting or creating another migration.
+- **Why it is useful:** The regression coverage checks observable database state and timing rather than mocked helper forwarding or CLI wiring.
+
+### `docs/migrations.md`
+
+- **Before:** The migration guide described command behavior but did not state the full `migrate dev` lock interval.
+- **After:** It documents that the lock starts before pending reconciliation and remains held through the optional name prompt, generation, and post-generation reconciliation/application; it links to this implementation guide.
+- **Why it is useful:** Readers can reason about concurrency and prompt timing from the documented contract.
+
+### `llms-full.txt`
+
+- **Before:** The generated documentation aggregate did not include the updated lock-lifetime note or this guide.
+- **After:** Regeneration mirrors the migration-guide update and includes the new workflow page.
+- **Why it is useful:** The aggregate stays aligned with the source documentation instead of presenting stale workflow details.
+
+### `examples/blog/seed.ts`
+
+- **Before:** The schema was imported as a runtime value even though it was used only for a type.
+- **After:** The import is type-only.
+- **Why it is useful:** TypeScript erases the import from emitted JavaScript, and lint no longer reports the type-only usage.
+
+### `docs/migrate-dev-workflow.md`
+
+- **Before:** There was no durable, file-by-file record of the workflow ownership, preserved behavior, and verification.
+- **After:** This page records the execution contract, concrete before/after changes, and their rationale.
+- **Why it is useful:** Future maintenance can distinguish an ownership refactor from an intended behavior change.
+
+## Preserved behavior and scope
+
+- Pending migrations are reconciled and applied before a missing name can be requested.
+- The prompt is limited to the existing missing-name condition and is attempted at most once; unchanged schemas do not prompt.
+- The migrate-dev lock remains held during the prompt and until post-generation reconciliation/application finishes.
+- The existing second schema compilation remains; this change does not optimize it.
+- `migrate deploy` keeps its separate execution path.
+
+## Verification
+
+The implementation verification below was recorded before this documentation continuation; it was not rerun as part of the documentation-only changes:
+
+- `bun run build` — passed.
+- `bun run test` — 128 files passed, 4 skipped; 1,215 tests passed, 42 skipped.
+- `bun run typecheck` and `bun run lint` — passed; lint was clean.
+- Focused migration suites — 4 files and 34 tests passed.
+- CLI fixture smoke — `migrate dev --name initial`, a no-name no-op `migrate dev`, and a no-op `migrate deploy` each exited 0; the SQLite database had the expected table and one applied ledger entry.
+
+The generated documentation is refreshed with `bun run docs:llms` after editing this page.

package/docs/migrations.md

@@ -5,8 +5,9 @@
 | Command | Description |
 |---------|-------------|
 | `neoorm init` | Scaffold `neoorm.config.ts`, `schema.ts`, `.env.example` only (no codegen or migrations; run `neoorm migrate dev` after) |
-| `neoorm generate --name <name>` | Emit manifest, typed client, models, includes, and migrations |
-| `neoorm migrate dev --name <name>` | Apply pending migrations (or record colliding CREATE TABLE files against the live schema), then generate a new one if `schema.ts` changed |
+| `neoorm generate [--name <name>]` | Emit manifest, typed client, models, includes, and migrations (`--name` only when a migration is created) |
+| `neoorm migrate dev [--name <name>]` | Apply pending migrations (or record colliding CREATE TABLE files against the live schema), then generate a new one if `schema.ts` changed (`--name` only when a new migration is created) |
+| `neoorm migrate diff [--accept-data-loss] [--json]` | Preview the SQL a new migration would contain — no files written, no `--name` needed |
 | `neoorm migrate deploy` | Apply pending migrations (throws `migration_drift` if a pending `CREATE TABLE` targets a relation that already exists) |
 | `neoorm migrate status` | List applied vs pending migrations |
 | `neoorm migrate down [--steps N]` | Roll back the last N applied migrations (default 1) |
@@ -25,7 +26,10 @@
 | Migration created | New `migrations/<timestamp>_<name>/migration.sql` written |
 | Migration blocked | Destructive or manual changes prevented writing SQL |
 
-Migration names are slugified (`Add Users` → `add_users`, capped at 50 chars) and prefixed with a timestamp so folders sort in apply order. `--name` is required when a migration is created: the CLI prompts on a TTY and errors in non-interactive runs. Runs with no schema changes (client regeneration only) succeed without `--name`. Older `*_migration` folders still apply in order.
+Migration names are slugified (`Add Users` → `add_users`, capped at 50 chars) and prefixed with a timestamp so folders sort in apply order. `--name` is only needed when a migration is created: the CLI prompts on a TTY at that point (after pending migrations are applied in `dev`) and errors in non-interactive runs. Runs with no schema changes (client regeneration only) and pending-apply-only `dev` runs succeed without `--name` and never prompt. Older `*_migration` folders still apply in order.
+
+`migrate dev` holds its lock from before pending reconciliation through the optional name prompt, generation, and post-generation reconciliation/application.
+For the implementation ordering and regression coverage, see [the workflow guide](migrate-dev-workflow.md).
 
 When migration is blocked, the CLI explains why — for example unsupported type casts (`alter_column_type_manual`), enum value changes, or destructive drops. Re-run with `--accept-data-loss` to include destructive DDL:
 
@@ -33,6 +37,13 @@ When migration is blocked, the CLI explains why — for example unsupported type
 neoorm generate --name add_users --accept-data-loss
 ```
 
+To inspect the SQL before naming the migration, preview it first (read-only, needs no `--name`):
+
+```bash
+neoorm migrate diff
+neoorm migrate diff --json
+```
+
 ## Existing tables vs pending CREATE TABLE
 
 `generate` diffs `snapshot.json`. If that file is missing, the first migration is a full `CREATE TABLE` script. `migrate deploy` will not run that SQL when those relations already exist (for example after `db push`). It throws `migration_drift` before any user statement.

package/docs/seeding.md

@@ -0,0 +1,67 @@
+# Seeding
+
+`neoorm seed` runs a seed script against the database inside a single transaction. Any failure rolls the whole seed back, so failed runs are safe to retry.
+
+```
+neoorm seed [--env <name>] [--file <path>]
+```
+
+## Seed files
+
+By convention the seed lives next to the schema as `seed.ts` and exports a `seed(db)` function. `db` is a transaction-scoped client, so every write in the file is atomic:
+
+```ts
+// seed.ts
+import type { TransactionClient } from "neoorm";
+import { schema } from "./schema.js";
+
+export async function seed(db: TransactionClient<typeof schema._tables>) {
+	await db.users.upsert({
+		where: { email: "admin@example.com" },
+		create: { email: "admin@example.com", name: "Admin" },
+		update: {},
+	});
+	await db.tags.createMany({
+		data: [
+			{ slug: "news", name: "News" },
+			{ slug: "guides", name: "Guides" },
+		],
+		skipDuplicates: true,
+	});
+}
+```
+
+Annotating with `TransactionClient<typeof schema._tables>` gives fully typed repositories — the same types as the generated client. A default-exported function works too, and `SeedContext` from `neoorm` is available for manifest-agnostic helpers.
+
+## Environments
+
+`--env <name>` runs `seeds/<name>.ts` instead of `seed.ts`:
+
+```bash
+neoorm seed --env dev
+neoorm seed --file ./seeds/manual.ts
+```
+
+`--file` wins over `--env`, and both win over config (see below).
+
+## Idempotency
+
+Seeds are re-run by convention — there is no seed ledger. Write seeds so running them twice is safe: `upsert`, `findOrCreate`, and `createMany({ skipDuplicates: true })` are the building blocks. The transaction guarantees all-or-nothing per run, not across runs.
+
+## Configuration
+
+Pin defaults in `neoorm.config.ts` (CLI flags override them):
+
+```ts
+export default defineConfig({
+	// ...
+	seed: { env: "dev", file: "./seeds/base.ts" },
+});
+```
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `seed.file` | `string` | Default seed file, project-root relative |
+| `seed.env` | `string` | Default environment, runs `seeds/<env>.ts` next to the schema |
+
+See [Configuration](configuration.md) for the full config reference.

package/docs/sqlite.md

@@ -60,6 +60,8 @@ const db = createNeoOrmClient(manifest, {
 
 `busyTimeout` can also be a millisecond wait (`sqlite: { busyTimeout: 10_000 }`).
 
+SQLite runs `search`/`REGEXP` patterns in-process as JavaScript `RegExp`, so a catastrophic-backtracking pattern (e.g. `(a+)+$`) could freeze the whole process. neoorm rejects patterns that nest unbounded quantifiers; pass `sqlite: { unsafeAllowRegex: true }` to allow them anyway.
+
 ### Custom driver
 
 Pass any object implementing `prepare(sql)`, `exec(sql)`, and `close()` — the `node:sqlite` and `bun:sqlite` APIs both match. Useful for sandboxed runtimes or existing database handles: