skills/plugins/document-navigator/docs/api-stack/api/api-db-sqlite-memory/README.md

@suaveplan/api-db-sqlite-memory — in-memory SQLite database adapter for the @suaveplan/api plugin host testing kit. Wraps bun:sqlite in :memory: mode (or an on-disk file for persistent test fixtures) behind the AdminDatabaseLike + TenantScopedDatabaseLike contracts, applies WAL + foreign_keys pragmas by default, ships a lexicographic migration runner with __plugin_migrations bookkeeping, and registers itself in the @suaveplan/api-db-adapter engine registry under the sqlite-memory key so createDbAdapter({ engine: 'sqlite-memory' }) resolves transparently.

Stage-5 in-memory SQLite database adapter for the @suaveplan/api plugin host testing kit. Wraps bun:sqlite (in :memory: mode by default, or a file path for longer-lived fixtures) behind the AdminDatabaseLike + TenantScopedDatabaseLike contracts from @suaveplan/api-types/db, ships a lexicographic migration runner with __plugin_migrations bookkeeping, and self-registers in the @suaveplan/api-db-adapter engine registry under the sqlite-memory key so createDbAdapter({ engine: "sqlite-memory" }) resolves transparently.

The adapter is production-grade — it happens to keep state in process memory. Real SQLite drives every query, transaction semantics match, foreign-key enforcement is on by default, and the migration runner is fully transactional. Tests boot in milliseconds without testcontainers or any other external service.

Documentation tree

• engine — Registers the in-memory SQLite adapter under engine: "sqlite-memory" in the open @suaveplan/api-db-adapter engine r…
  • register-engine — Registers the in-memory SQLite adapter under engine: "sqlite-memory" in the open @suaveplan/api-db-adapter engine r…
• error-codes — This module declares the stable error-code registry for @suaveplan/api-db-sqlite-memory. Every error thrown from the…
  • error-codes — This module declares the stable error-code registry for @suaveplan/api-db-sqlite-memory. Every error thrown from the…
• create-sqlite-memory-adapter — Opens a real bun:sqlite Database and wraps it as an AdminDatabaseLike. The default zero-argument call yields a `:…
• create-sqlite-memory-db — Stage-5 top-level testing factory. Combines createSqliteMemoryAdapter with the tenant-scoping wrapper from this packa…
• migrations — Lexicographic forward-only migration runner for the in-memory SQLite adapter. Applies every *.sql file in a directory…
  • migrations — Lexicographic forward-only migration runner for the in-memory SQLite adapter. Applies every *.sql file in a directory…
• options — Defines the Zod-validated options object accepted by createSqliteMemoryDb, createSqliteMemoryAdapter, and the engin…
  • sqlite-memory-db-options — Defines the Zod-validated options object accepted by createSqliteMemoryDb, createSqliteMemoryAdapter, and the engin…
• tenant-scoping — Wraps an AdminDatabaseLike as a TenantScopedDatabaseLike that transparently injects the resolved tenant id into eve…
  • tenant-scoping — Wraps an AdminDatabaseLike as a TenantScopedDatabaseLike that transparently injects the resolved tenant id into eve…
• testing — Convenience builder for plugin test files. Wraps createSqliteMemoryDb with an idempotent cleanup() so the canonical…
  • harness — Convenience builder for plugin test files. Wraps createSqliteMemoryDb with an idempotent cleanup() so the canonical…

Connection string

The canonical connection string is ":memory:" — the default. Any non-empty string passed as filename is forwarded straight to bun:sqlite's Database constructor, so an absolute path opens a persistent file-backed fixture:

import { createSqliteMemoryAdapter } from "@suaveplan/api-db-sqlite-memory";

const ephemeral = createSqliteMemoryAdapter(); // ":memory:"
const persisted = createSqliteMemoryAdapter({ filename: "/tmp/fixture.sqlite" });

Default pragmas

Every fresh connection has these pragmas applied at open time:

• journal_mode = WAL — write-ahead logging. No-op for :memory:, useful for file-backed fixtures.
• foreign_keys = ON — SQLite ships with FK enforcement disabled by default. The adapter flips it on so referential integrity is honoured.

Operators that want to override either default supply pragmas in the options object:

const adapter = createSqliteMemoryAdapter({
    pragmas: { foreign_keys: "OFF", synchronous: "FULL" },
});

The final merged pragma map is { ...DEFAULT_PRAGMAS, ...options.pragmas }, so any default can be overridden by repeating its key.

Subpath exports

Subpath	Purpose
.	Root barrel — re-exports every public symbol.
./adapter	createSqliteMemoryAdapter + OTel instrument hooks.
./factory	createSqliteMemoryDb returning { admin, scoped, close }.
./engine	registerSqliteMemoryEngine for the api-db-adapter registry.
./migrations	runSqliteMemoryMigrations + SqliteMigrationsFsReader.
./options	Zod schema + parseSqliteMemoryDbOptions + resolvePragmas.
./tenant-scoping	createTenantScopedSqliteWrapper + pure SQL rewriters.
./error-codes	DB_SQLITE_MEMORY_CODES + DbSqliteMemoryError.
./testing	createInMemorySqliteHarness convenience builder.

Error codes

• DB_SQLITE_MEMORY.OPEN_FAILED — bun:sqlite constructor threw.
• DB_SQLITE_MEMORY.INVALID_OPTIONS — Zod validation failed.
• DB_SQLITE_MEMORY.MIGRATION_FAILED — a migration file threw; transaction rolled back.
• DB_SQLITE_MEMORY.TENANT_SCOPE_VIOLATION — cross-tenant write or unsupported SQL shape.

License

MIT.