@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