db

10 modules

• db/assert_row.ts

  Assertion helper for INSERT RETURNING results.

• db/create_db.ts

  Database initialization with driver auto-detection.

  Selects the appropriate database driver based on database_url: - postgres:// or postgresql:// — uses pg (PostgreSQL) - file:// — uses @electric-sql/pglite (file-based) - memory:// — uses @electric-sql/pglite (in-memory)

  Both pg and @electric-sql/pglite are optional peer dependencies, dynamically imported only when needed. For direct driver construction without auto-detection, use db_pg.ts or db_pglite.ts.

• db/db_pg.ts

  PostgreSQL driver adapter for Db.

  Provides create_pg_db() to construct a Db backed by a pg.Pool. Only imports pg types — the actual pg package is dynamically imported by callers (e.g., create_db) that construct the Pool.

• db/db_pglite.ts

  PGlite driver adapter for Db.

  Provides create_pglite_db() to construct a Db backed by @electric-sql/pglite. Only imports PGlite types — the actual package is dynamically imported by callers (e.g., create_db) that construct the PGlite instance.

• db/db.ts

  Database wrapper with duck-typed interface.

  Accepts any client with a query(text, values) method. Both pg.Pool and @electric-sql/pglite satisfy this interface.

  Transaction safety is provided by an injected transaction callback — the driver adapters (db_pg.ts, db_pglite.ts) supply the driver-appropriate implementation. Close is handled externally (returned alongside the Db as DbDriverResult), not as a method on this class.

• db/migrate.ts

  Version-gated database migration runner.

  Migrations are functions in ordered arrays, grouped by namespace. A schema_version table tracks progress per namespace. Each migration runs in its own transaction.

  Forward-only: No down-migrations. Schema changes are additive. For pre-release development, collapse migrations into a single v0.

  Named migrations: Migrations can be bare functions or {name, up} objects. Names appear in error messages for debuggability.

  Advisory locking: Per-namespace PostgreSQL advisory locks serialize concurrent migration runs, preventing double-application in multi-instance deployments.

• db/pg_error.ts

  PostgreSQL error utilities.

  Works with both pg and @electric-sql/pglite — both set .code on error objects using standard PostgreSQL error codes.

• db/query_deps.ts

  Shared query dependency type.

  All query_* functions take deps: QueryDeps as their first argument. Widened per-function when additional capabilities are needed (e.g., log for token validation).

• db/sql_identifier.ts

  SQL identifier validation for dynamic DDL queries.

  PostgreSQL DDL operations (DROP TABLE, TRUNCATE, ALTER) do not support parameterized table/column names — only values can be parameterized. This validator ensures identifiers are safe for string interpolation in those specific cases.

• db/status.ts

  Database status utility for CLI and dev workflows.

  Queries migration state and table info without a running server. Returns structured data that consumer scripts can print however they like.