metal-kompanion/docs/dal-skeleton.md

DAL Skeleton (pgvector)

Interfaces

• IDatabase — connect/tx + memory ops (ensureNamespace, upsertItem/Chunks/Embeddings, searchText/searchVector).
• PgDal — stub implementation for now (no libpq linked).

SQL Calls (target)

• ensureNamespace: INSERT ... ON CONFLICT (name) DO UPDATE RETURNING id
• upsertItem: INSERT ... ON CONFLICT (id) DO UPDATE SET ... RETURNING id
• upsertChunks: batch insert w/ RETURNING id
• upsertEmbeddings: batch insert; ensure model, dim set, vector column populated.
• searchText: FTS/trigram query filtered by namespace/thread/tags.
• searchVector: ORDER BY embeddings.vector <-> $1 LIMIT k (with filters).

Next

• Wire Handlers::upsert_memory / search_memory to IDatabase.
• Add libpq (or pqxx) and parameterized statements.
• Add RLS/session GUCs & retries.

Implementation Checklist (2025-10-15)

• Detect libpq + pqxx in CMake, define HAVE_PG, and link kom_dal against PostgreSQL::PostgreSQL and pqxx::pqxx.
• During PgDal::connect, prepare statements for namespace ensure/upsert, chunk/embedding insert, text/vector search, and hybrid search.
• Guard runtime selection: stub:// DSN keeps the current in-memory store; non-stub DSNs require a live Postgres connection.
• Expose environment variables in docs: PG_DSN (full libpq connection string) and optional PGSSLMODE.
• Surface informative std::runtime_error messages when pqxx operations fail so MCP handlers can emit actionable errors.