metal-kompanion/docs/dal-skeleton.md

DAL Skeleton (pgvector)

Interfaces

• IDatabase — connect/tx + memory ops (ensureNamespace, upsertItem/Chunks/Embeddings, searchText/searchVector).
• PgDal — Qt6/QSql-based implementation with in-memory fallback.

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.
• Harden SQL with RLS/session GUCs & retries.
• Expand hybrid search scoring (RRF weights, secret filters).

Implementation Checklist (2025-10-15)

• Require Qt6::Sql (QPSQL driver) at configure time; bail out early when unavailable.
• During PgDal::connect, parse DSNs with QUrl, open QSqlDatabase, and retain in-memory fallback for stub://.
• Use QSqlQuery with INSERT ... RETURNING for namespace/item/chunk/embedding operations.
• Derive DSNs from kompanionrc (KConfig) or CLI wizard, and surface informative std::runtime_error messages when QSql operations fail.