skills/docs/persistence/database/db-sqlite/src/connection/connection.md

connection

(no submodules)

Purpose

Provides thin singleton-management wrappers for SqliteAdapter, built on top of the @suaveplan/db singleton helpers. These functions let callers share a single connected SqliteAdapter instance across an application without manually tracking the singleton lifecycle or passing the adapter through every layer of the call stack.

The helpers default the singleton name to "default" so simple applications need only call getDefaultSqlite() with no arguments. More complex applications with multiple databases use explicit names.

Features

• getDefaultSqlite(options?, config?, name?) — creates-or-returns a connected SqliteAdapter singleton
• closeSqlite(name?) — disconnects and removes the named singleton
• closeAllSqlite() — disconnects and removes all SqliteAdapter singletons
• hasSqlite(name?) — returns true if the named singleton exists and is connected
• Default name: "default" — single-database apps never need to supply a name

Usage: Basic Example

import { getDefaultSqlite } from "@suaveplan/db-sqlite/connection/connection";

const adapter = await getDefaultSqlite();
const rows = await adapter.query("SELECT * FROM users");

Usage: Advanced Example

import {
  closeAllSqlite,
  closeSqlite,
  getDefaultSqlite,
  hasSqlite,
} from "@suaveplan/db-sqlite/connection/connection";

// Primary database
const primary = await getDefaultSqlite(
  { filename: "/data/app.db" },
  undefined,
  "primary"
);

// Analytics read-only shard
const analytics = await getDefaultSqlite(
  { filename: "/data/analytics.db", readonly: true },
  undefined,
  "analytics"
);

console.log(hasSqlite("primary"));   // true
console.log(hasSqlite("analytics")); // true

await closeSqlite("analytics");
console.log(hasSqlite("analytics")); // false

// Shutdown — closes all remaining singletons
await closeAllSqlite();

API Reference

getDefaultSqlite(options?, config?, name?): Promise<SqliteAdapter>

Creates a new SqliteAdapter using the given options, calls connect(config) on it, caches it under name, and returns it. Subsequent calls with the same name return the cached instance without reconnecting.

closeSqlite(name?): Promise<void>

Disconnects and removes the singleton named name. No-op if no singleton by that name exists.

closeAllSqlite(): Promise<void>

Disconnects and removes all singletons. Throws AggregateError if any disconnect fails.

hasSqlite(name?): boolean

Returns true if a singleton exists under name.

Implementation Notes

These functions delegate entirely to @suaveplan/db's getSingleton, closeSingleton, closeAllSingletons, and hasSingleton. The SqliteAdapter-specific names (getDefaultSqlite, closeSqlite, etc.) exist for discoverability — callers working with SQLite need not know the generic singleton API. The return type is narrowed from DatabaseAdapter to SqliteAdapter via a cast so callers have access to SQLite-specific properties.