Database-connector (read-only)

De database-connector laat de patch-agent read-only SELECTs draaien tegen jullie eigen Postgres terwijl 'ie redeneert over BUG-tickets. De data komt terug als een markdown-blok in de QA-notes die de CTO-handler downstream leest — verder niets. Geen write-pad, geen DDL-pad, en geen executie buiten een READ ONLY transactie.

Standaard staat 'ie uit. Twee tenant-gates moeten open voordat één rij de agent bereikt: de per-integratie toggle Allow AI database context, en een per-shape approval (of de per-integratie auto-diagnostics-override). Eén missen en de agent blijft blind.

Wanneer aanzetten

Aan zetten als:

• Bug-triage steeds vastloopt op "de AI ziet niet wat de status van de rij is" en een engineer uiteindelijk een SELECT in chat plakt.
• Je een Postgres-replica hebt (of een role op de primary) die je sowieso aan een junior dev zou geven voor diagnostics.
• Je bereid bent een allowlist van schemas/tables te onderhouden die de AI mag lezen.

Niet aan zetten als je geen écht SELECT-only role kunt leveren, of als de data zo gevoelig is dat een column-name redactor op zichzelf niet voldoende is.

Vandaag wordt alleen Postgres ondersteund.

Gates

De per-integratie toggle is de master-schakelaar voor die database. De per-shape approval is de chirurgische laag: elke structureel andere query die de AI voorstelt wordt de eerste keer gepauzeerd voor menselijke review.

Een optionele Auto read-only diagnostics-toggle omzeilt de per-shape approval queue voor die integratie. Zie hieronder.

Setup

1. Provisioneer een Postgres-role met SELECT-only privileges op de data die je wilt blootleggen. Een read replica is de schoonste source. De connector werkt ook tegen een primary zolang de role écht niet kan schrijven.
2. Settings → Integrations → Data sources → Database → Add database. Of de host/port/db/user/password-velden of een libpq connection string — als beide ingevuld zijn wint de connection string.
3. Kies een SSL-mode. require is de UI-default. disable mag, maar slaat alleen ergens op tegen een lokale sandbox.
4. Vul de schema-allowlist voordat je iets aanzet. Lege allowlist is default-deny — elke concrete table-referentie faalt op de guard.
5. Versmal optioneel met de table-allowlist. Leeg betekent "elke table binnen de toegestane schemas"; anders moet elke gerefereerde table erop staan.
6. Klik Test connection. FixControl checkt de credentials en verifieert vervolgens dat de role écht niet kan schrijven door een write-poging in een READ ONLY transactie te doen. De integratie wordt alleen op Read-only verified gezet als die write-probe door de engine wordt afgewezen. Slaagt de probe juist, dan heb je een role die kan schrijven — fix de grants vóór je 'm blootlegt.
7. Toggle Allow AI database context als je tevreden bent. De integratie staat dan op connected, maar de agent blijft blind tot deze aan staat.

Credentials worden versleuteld opgeslagen met een per-tenant key. Host/port/database/user blijven zichtbaar in de UI zonder dat het secret ontsleuteld hoeft te worden.

Eén actieve integratie per (host, database). Opnieuw toevoegen na delete werkt.

Allowlist-semantiek

Default-deny op schemas. Concreet:

• Lege schema-allowlist → elke query faalt met "no schemas are configured for this integration".
• Niet-lege schema-allowlist → schema-qualified referenties worden hiertegen gecheckt. Niet-qualified referenties worden als public behandeld.
• De table-allowlist ligt eroverheen. Leeg betekent "geen extra table-filter"; niet-leeg betekent dat elke gerefereerde table erop moet staan (gematched als kale table of fully qualified schema.table).

Referenties in subqueries worden net zo gewalkt als top-level. Mocht een referentie alsnog langs de schema-check glippen, dan zitten de READ ONLY transactie en de role-grants nog steeds vóór elke write.

Approval-flow

De agent normaliseert elke voorgestelde SELECT naar een shape — de SQL met literal-waarden geblankt — zodat één approval elke latere run van die query met andere keys dekt. Revoken en daarna re-approven van een shape werkt zonder handmatige cleanup.

Lifecycle:

1. Agent stelt een query voor bij een BUG-ticket. FixControl normaliseert 'm en zoekt een active approval.
2. Geen approval → de shape komt in de pending-approvals queue. De agent slaat deze query over voor deze run; het markdown-blok noteert (awaiting approval).
3. Admin reviewt de queue op Settings → Integrations → Database → Pending approvals, klikt Approve.
4. Volgende runs van dezelfde shape glijden door.
5. Revoke stopt de shape; een toekomstige re-approval werkt prima.

Approve een shape — geen letterlijke query. Approven van SELECT id, status FROM orders WHERE id = $1 laat elke toekomstige run met om het even welke id-waarde door. Dat is precies de bedoeling: bug-redenering raakt vaak dezelfde query op verschillende keys.

De approval queue markeert shapes waarvan de touched tables er gevoelig uitzien op naam (users, customers, payments, tokens, secrets, …) als UI-hint. De runtime-redactor pakt de daadwerkelijke kolommen sowieso.

Auto-diagnostics — de tradeoff

De Auto read-only diagnostics-toggle omzeilt de per-shape approval queue voor die integratie. Elke voorgestelde query die de allowlist passeert draait direct en wordt in de audit als auto-diagnostics genoteerd. Gebruik 'm als:

• De allowlist écht strak is (een handvol low-sensitivity tables op een replica).
• Je de agent wilt laten itereren zonder mens-in-de-loop op elke nieuwe shape.

Niet gebruiken als:

• De allowlist tables bevat met PII die de column-redactor niet kent.
• Je een papieren spoor wilt van wie wat goedkeurde voordat data de database verliet.

De allowlist-guard, de READ ONLY transactie, de row/byte caps, en de redactor blijven gelden. Auto-diagnostics haalt alleen de mens-in-de-loop-stap weg.

Audit & redactie

Elke executie wordt vastgelegd met de geclipte query text, tables touched, row count, bytes returned, truncation-flag, redacted column names, duration, error, actor (AI vs mens), approval-bron, en het BUG-ticket waarvoor 'ie liep. De records zijn append-only en tenant-scoped.

Resultaatcaps:

• 50 rijen max per query — alles erboven wordt afgekapt.
• 64 KB max stringified payload — eerste rij die over de grens gaat triggert truncation.
• 5-seconden statement-timeout en een korte lock-timeout, beide door de engine afgedwongen.

Column-name redactie draait vóór de rijen de agent bereiken. Elke kolom waarvan de naam eruit ziet als email, phone, password, secret, token, api_key, access_token, refresh_token, ssn, social_security, credit_card, card_number, cvv, iban, of bank_account (met gangbare snake/dash-varianten) wordt herschreven naar [redacted], en de geredacteerde kolomnamen worden op de audit-rij genoteerd. Redactie is column-name-based, niet value-based — een free-text notes-kolom met een email erin wordt niet gepakt. Is dat een probleem voor jullie data, zet die kolom dan niet op de allowlist.

Troubleshooting

"Read-only not verified"-badge blijft staan na een succesvolle test. De credentials werken, maar een write-probe in de READ ONLY transactie werd niet afgewezen door de engine. De role heeft nog write- of DDL-grants. Re-grant als SELECT-only en test opnieuw.

"schema X is not on the allowlist" of "no schemas are configured". Default-deny-gedrag. Voeg het schema toe aan de schema-allowlist van de integratie en probeer opnieuw. Noemt de error een schema dat je niet verwachtte (bijv. pg_catalog), dan stelde de AI een system-table query voor — laat de allowlist zo, die query hoort te falen.

"forbidden keyword: X" of "writable CTE rejected". Een non-SELECT keyword (INSERT, UPDATE, DELETE, MERGE, DROP, COPY, CALL, …) of een writable CTE werd by design afgewezen. De agent herformuleert, of jij draait 'm handmatig. De audit-log noteert het keyword.

Query timet out. De 5-seconden cap vuurde. Of de query is écht duur (zet een index op de replica, of trim de query) of de replica loopt achter. Diagnostische queries mogen nooit productie blokkeren.

Resultaten op elke run getruncate. Je raakt de 50-rijen / 64 KB cap. Knijp de WHERE aan; resultaten worden niet gepagineerd.

De engine wees een query af als read-only-violation nadat de integratie eerst werkte. Een allowlist-misser bereikte de engine en Postgres deed z'n werk. De integratie wordt automatisch op failed gezet zodat 'ie op het dashboard verschijnt. Inspecteer de audit-entry en versmal de allowlist vóór re-enable.