docs: define postgres diagnostic alignment

2026-08-22 13:21:13 +02:00
parent ef7ae7053c
commit 1f75b81214
1 changed files with 58 additions and 0 deletions
@@ -0,0 +1,58 @@
+# Workspace PostgreSQL diagnostic alignment
+
+## Context
+
+The `psd-clinical` runtime reaches PostgreSQL successfully with the configured
+`postgres_direct` transport and operates in the declared `datawarehouse` schema.
+The workspace diagnostic reports `connector_unavailable` because its Node `pg`
+probe differs from the runtime contract in two ways:
+
+- it always enables strict TLS, even when the installation declares no TLS CA or
+  server name;
+- it compares `current_schema()` with the workspace schema without first applying
+  or otherwise validating that declared schema.
+
+This is a diagnostic false negative. Qdrant and embedding diagnostics already
+match the workspace descriptor.
+
+## Decision
+
+Align the direct PostgreSQL diagnostic with the effective runtime connection:
+
+1. Use a plain PostgreSQL connection when no TLS configuration is declared.
+2. Enable strict TLS only when a TLS CA and/or server name is explicitly bound.
+3. Verify the connected database and that the authenticated role can use the
+   schema declared by the workspace, without interpolating an untrusted SQL
+   identifier.
+4. Retain the existing sanitized `connector_unavailable` public error boundary;
+   credentials, database errors, and server details must not reach the API.
+
+The runtime connection, workspace descriptor, secrets, and deployment topology
+remain unchanged.
+
+## Alternatives rejected
+
+- Switching the test installation to `rest_api` would test a different transport
+  from the one used by sessions and require another credential path.
+- Disabling or weakening the connector diagnostic would hide real connection,
+  authentication, database, and schema failures.
+
+## Verification
+
+Test-first coverage will prove:
+
+- a direct connection without TLS bindings is created without SSL;
+- explicit TLS bindings still produce strict certificate verification;
+- the declared schema is checked through parameterized SQL and an inaccessible or
+  missing schema fails closed;
+- existing wrong-database, authentication, Qdrant, embedding, timeout, and secret
+  redaction tests remain green.
+
+After rebuilding only the test core, the live checks must show:
+
+- workspace diagnostic `activatable: true` with no connector error;
+- the selected model remains available;
+- session creation through Django/Nginx/core returns `200`, followed by deletion
+  of the diagnostic session.
+
+No production cutover is part of this change.