Imported from nlqdb/nlqdb (
packages/db/AGENTS.md). Install upstream withnpx skills add nlqdb/nlqdb --skill db. Copyright stays with the author.
Packages · DB — Agents Guide
Engine-agnostic DB adapter. Phase 0 = Postgres via Neon.
This is the local guide. Read root
AGENTS.mdfirst for the three behavioral principles, the full path → feature map, and the project-wide tech stack. This file narrows that guide topackages/db/.
Features relevant to this area
db-adapter— mandatory pre-read for changes that touch the feature.multi-engine-adapter— mandatory pre-read for ClickHouse/Tinybird and any future non-PG engine.schema-widening— mandatory pre-read for changes that touch the feature.observability— mandatory pre-read for changes that touch the feature.
External systems owned here (GLOBAL-021)
packages/db/ is the canonical owner for every user-data engine the
product talks to. Each has exactly one entry point; reaching past it
from outside the package fails review.
| External system | Entry module | Notes |
|---|---|---|
| Neon Postgres | src/postgres.ts (createPostgresAdapter) |
All @neondatabase/serverless imports. Documented exception: apps/api/src/db-create/build-deps.ts for the control-plane provisioner — see SK-HDC-*. |
| ClickHouse via Tinybird | src/clickhouse-tinybird/adapter.ts (createTinybirdAdapter) + src/clickhouse-tinybird/query-log.ts (createQueryLogWriter / writeQueryLog) |
Owns the Tinybird HTTP client for both read (Pipe / SQL execution) and write (query_log Data Source append; W4 sink path). The adapter exposes typed intent-named methods (executePipe() / executeRawSql() via the execute() plan dispatch today; W5 adds createPipe() / dropPipe() for the workload analyser). The events-worker calls writeQueryLog (SK-EVENTS-009) — owner-to-owner library dependency, allowed by GLOBAL-021. The events-worker never imports Tinybird's HTTP client / SDK / wire format of its own; the token is delivered via env per Workers convention, which is fine — GLOBAL-021's ownership rule is about the SDK / wire surface, not about which Worker holds the credential. The Tinybird fetch client is never re-exported from this package — consumers go through the typed entry points. CI's no-restricted-imports rule for the Tinybird API token must reject any import of the HTTP client outside packages/db/src/clickhouse-tinybird/. |
When adding a new engine, follow the same pattern: a sibling directory
under src/ that owns the SDK / HTTP client and exposes only the
typed entry points the rest of the codebase needs.
Commands
bun run --filter @nlqdb/db build
bun run --filter @nlqdb/db testLocal rules
- Every change here must respect the
GLOBAL-NNNdecisions indocs/decisions.md. - A new external call (DB / LLM / HTTP / queue) needs an OTel span
(
GLOBAL-014). - If a request is ambiguous or an error is unfamiliar — web-research
current best practices first (see root
AGENTS.md§2 P2). - A decision change (new or amended) updates every place that copies
it, in the same PR (root
AGENTS.md§2 P3).
When you finish
- Run the commands above and ensure they all pass.
- If you added a decision, it has an ID, lives in the right place
(
docs/decisions.mdor the relevantFEATURE.md), and any duplicate of an affectedGLOBAL-NNNis updated. - Open a PR; the root
AGENTS.md§8 lists the pre-PR quality gates.