# 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.