skills/plugins/document-navigator/docs/persistence/database/db/README.md

@suaveplan/db - Universal relational database adapter interface: DatabaseAdapter (extends DatabaseLike), structured DB.* error codes, Zod-validated config types, injectable connection singletons, MigrationRunner interface, and full OTel instrumentation.

Summary

Universal relational database adapter interface for Suaveplan. Provides the DatabaseAdapter contract (extending DatabaseLike from @suaveplan/types), injectable connection singletons, structured DB.* error codes, Zod-validated config types, a MigrationRunner interface, and full OpenTelemetry instrumentation.

This package is the stable foundation that @suaveplan/db-sqlite and future adapters build upon.

Documentation tree

• adapter — (no submodules)
  • database-adapter — (no submodules)
• connection — (no submodules)
  • singleton — (no submodules)
• errors — (no submodules)
  • database-error — (no submodules)
• migration — (no submodules)
  • migration-runner — (no submodules)
• instruments — instruments.ts provides lazily-initialised OpenTelemetry metric instruments for @suaveplan/db. Rather than creating…
• trace — withDbSpan is a thin OTel tracing helper that wraps any async database operation in a named span. It handles the boil…
• types — (no submodules)
  • database-config — (no submodules)

- [database-adapter](./src/adapter/database-adapter.md) — _(no submodules)_- [connection](./src/connection/singleton.md) — _(no submodules)_- [singleton](./src/connection/singleton.md) — _(no submodules)_- [errors](./src/errors/database-error.md) — _(no submodules)_- [database-error](./src/errors/database-error.md) — _(no submodules)_- [migration](./src/migration/migration-runner.md) — _(no submodules)_- [migration-runner](./src/migration/migration-runner.md) — _(no submodules)_- [instruments](./src/telemetry/instruments.md) — `instruments.ts` provides lazily-initialised OpenTelemetry metric instruments for `@suaveplan/db`. Rather than creating…

• trace — withDbSpan is a thin OTel tracing helper that wraps any async database operation in a named span. It handles the boil…
• types — (no submodules)- database-config — (no submodules)- database-adapter — (no submodules)- connection — (no submodules)- singleton — (no submodules)- errors — (no submodules)- database-error — (no submodules)- migration — (no submodules)- migration-runner — (no submodules)- instruments — instruments.ts provides lazily-initialised OpenTelemetry metric instruments for @suaveplan/db. Rather than creating…
• trace — withDbSpan is a thin OTel tracing helper that wraps any async database operation in a named span. It handles the boil…
• types — (no submodules)- database-config — (no submodules)- database-adapter — (no submodules)- connection — (no submodules)- singleton — (no submodules)- errors — (no submodules)- database-error — (no submodules)- migration — (no submodules)- migration-runner — (no submodules)- instruments — instruments.ts provides lazily-initialised OpenTelemetry metric instruments for @suaveplan/db. Rather than creating…
• trace — withDbSpan is a thin OTel tracing helper that wraps any async database operation in a named span. It handles the boil…
• types — (no submodules)- database-config — (no submodules)- database-adapter — (no submodules)- connection — (no submodules) - singleton — (no submodules)- errors — (no submodules) - database-error — (no submodules)- migration — (no submodules) - migration-runner — (no submodules)- instruments — instruments.ts provides lazily-initialised OpenTelemetry metric instruments for @suaveplan/db. Rather than creating…
• trace — withDbSpan is a thin OTel tracing helper that wraps any async database operation in a named span. It handles the boil…
• types — (no submodules) - database-config — (no submodules)

Install

bun add @suaveplan/db

Quick Start

import { getSingleton, closeSingleton } from "@suaveplan/db";
import { SqliteAdapter } from "@suaveplan/db-sqlite";

// Get-or-create a named singleton connection
const db = await getSingleton("app", () => new SqliteAdapter({ filename: "./app.db" }));

// Query
const users = await db.query<{ id: number; name: string }>(
  "SELECT id, name FROM users WHERE active = ?",
  [1]
);

// Transaction
const result = await db.transaction(async (tx) => {
  await tx.execute("INSERT INTO audit (msg) VALUES (?)", ["login"]);
  return tx.query<{ id: number }>("SELECT last_insert_rowid() AS id");
});

// Cleanup
await closeSingleton("app");

Modules

Module	Description
src/adapter/database-adapter.md	DatabaseAdapter interface — full connection contract
src/connection/singleton.md	getSingleton / closeSingleton / hasSingleton / closeAllSingletons
src/errors/database-error.md	DatabaseError, MigrationError, DB_CODES
src/migration/migration-runner.md	MigrationRunner interface
src/telemetry/instruments.md	OTel metric instruments (histogram, counters)
src/telemetry/trace.md	withDbSpan tracing helper
src/types/database-config.md	DatabaseConfig, MigrationConfig, Zod schemas

Error Codes

Code	When thrown
DB.CONNECTION_FAILED	connect() fails
DB.NOT_CONNECTED	Operation attempted before connect()
DB.QUERY_FAILED	query() or execute() throws
DB.TRANSACTION_FAILED	transaction() throws or rolls back
DB.MIGRATION_FAILED	migrate() fails on a specific migration

Benchmarks

Operation	Median
getSingleton cache-hit	~2 µs
hasSingleton lookup	< 1 µs
DatabaseConfigSchema.parse	~5 µs
withDbSpan overhead (no-op OTel)	~3 µs