Database-connector (read-only)

De database-connector geeft de patch-agent read-only toegang tot je eigen Postgres als context terwijl hij redeneert over BUG-tickets. Wat hij verzamelt, komt terecht als markdown-blok in de QA-notitie die de CTO-review daarna leest, en nergens anders. Er is geen schrijfpad en geen DDL-pad, en elke query draait binnen een READ ONLY-transactie.

Koppelen blijft bewust op het scherm. Deze connector draagt rechtstreeks een credential, en een geheim hoort nooit door een chattranscript te reizen. Command Center kan je vertellen of een connector gekoppeld en gezond is; de credentials invullen doe je op het instellingenscherm.

Wat de AI vandaag krijgt

Wees duidelijk over de huidige stand voordat je erop gaat plannen:

• Vandaag stelt de agent zelf geen queries voor. Is de connector bruikbaar, dan krijgt de QA-notitie een korte regel dat de connector beschikbaar is, welke schema's hij mag lezen (na je allowlist), en tot 20 tabelnamen uit het eerste van die schema's. In een normale run worden geen rijen gelezen.
• De querymachinerie is gebouwd en beveiligd, maar wordt nog niet gebruikt. De goedkeuring per shape, de allowlist-controle, de plafonds op rijen en bytes en het redigeren van kolommen hieronder staan klaar voor het moment dat de agent diagnostische queries gaat voorstellen. Tot die tijd blijft de goedkeuringswachtrij leeg.

Een database koppelen vertelt de agent vandaag dus vooral welke data er bestaat. Richt hem met dat in je achterhoofd in.

Poorten

Drie schakelaars moeten aan staan voordat de agent iets ziet:

De verbinding moet ook gekoppeld zijn (de credentials werken). Alleen BUG-issues krijgen databasecontext, en heb je meerdere verbindingen, dan wordt de eerste bruikbare gebruikt.

Wanneer aanzetten

Zet hem aan als:

• Bug-triage steeds vastloopt op "de AI ziet niet hoe de data eruitziet" en een engineer het schema uiteindelijk in de chat beschrijft.
• Je een Postgres-replica hebt (of een role op de primary) die je sowieso aan een junior developer zou geven voor diagnose.
• Je bereid bent een allowlist bij te houden van schema's en tabellen die de AI mag lezen.

Zet hem niet aan als je geen echte SELECT-only role kunt leveren, of als een redactor op kolomnaam voor jouw data niet genoeg is.

Alleen Postgres wordt ondersteund.

Inrichten

Je moet admin van je FixControl-organisatie zijn.

1. Maak een Postgres-role met alleen SELECT-rechten op de data die je wilt openstellen. Een read replica is de schoonste bron. Koppel altijd met een read-only role: de controles van FixControl zijn een tweede verdedigingslinie, geen vervanging voor correcte grants.
2. Open Instellingen → Kanalen → Databronnen → Database (read-only) en klik op Add database.
3. Vul Name, Host, Port, Database, Username en Password in.
4. Kies een SSL mode: require (de standaard), verify-ca, verify-full, of disable (alleen zinvol tegen een lokale sandbox).
5. Vul de Schema allowlist in voordat je iets aanzet. Een lege allowlist betekent default-deny: de AI kan niets lezen.
6. Versmal hem eventueel met de Table allowlist. Leeg betekent elke tabel binnen de toegestane schema's.
7. Klik op Test connection. FixControl controleert de credentials en probeert daarna een schrijfactie binnen een READ ONLY-transactie. Alleen als de database-engine die schrijfactie weigert, krijgt de verbinding het label Read-only verified. Toont hij Read-only not verified, dan kan de role nog schrijven: herstel de grants.
8. Zet Allow AI database context aan als je tevreden bent.

Of de agent toegang krijgt, hangt af van een gekoppelde verbinding en van Allow AI database context, niet van het read-only-label. Daarom is stap 1 belangrijk: het label vertelt je of je grants kloppen; het houdt de agent niet tegen.

Credentials worden versleuteld opgeslagen met een sleutel per workspace. Host, poort, database en gebruiker blijven zichtbaar op het scherm zonder dat het geheim wordt ontsleuteld. Je kunt één actieve verbinding per host en database hebben.

Allowlist-semantiek

Default-deny op schema's:

• Lege schema-allowlist → elke query faalt met "no schemas are configured for this integration".
• Niet-lege schema-allowlist → referenties met schema worden daartegen gecontroleerd. Referenties zonder schema gelden als public.
• De table-allowlist ligt daaroverheen. Leeg betekent geen extra filter; niet-leeg betekent dat elke gerefereerde tabel erop moet staan (als kale table of als schema.table).

Referenties in subqueries worden net zo gecontroleerd als die op het hoogste niveau. Glipt een referentie toch langs de controle, dan blokkeren de READ ONLY-transactie en de grants van de role nog steeds elke schrijfactie.

Goedkeuringsflow

Zo wordt een voorgestelde query behandeld zodra de agent queries voorstelt. Zoals hierboven beschreven gebeurt dat in normale runs nog niet.

Elke voorgestelde SELECT wordt genormaliseerd tot een shape: de SQL met de letterlijke waarden weggelaten. Eén goedkeuring geldt voor elke latere run van die query met andere waarden.

1. Er wordt een query voorgesteld voor een BUG-issue. FixControl normaliseert hem en zoekt een actieve goedkeuring.
2. Geen goedkeuring → de shape gaat naar de wachtrij en de query wordt voor deze run overgeslagen; de notitie vermeldt "awaiting approval".
3. Een admin opent Pending approvals vanaf het instellingenscherm van de database en klikt op Approve.
4. Latere runs van dezelfde shape gaan door.
5. Revoke stopt de shape; je kunt hem later opnieuw goedkeuren.

Keur je SELECT id, status FROM orders WHERE id = $1 goed, dan gaat elke latere run met elke id door. De wachtrij markeert shapes die tabellen met gevoelig klinkende namen raken als hint; de redactor handelt de echte kolommen hoe dan ook af.

Auto read-only diagnostics: de afweging

Auto read-only diagnostics (skip per-shape approval) slaat de goedkeuringswachtrij voor die verbinding over: elke voorgestelde query die door de allowlist komt, draait direct en wordt in de audit vastgelegd als auto-diagnostics. Gebruik dit alleen als de allowlist echt krap is (een paar weinig gevoelige tabellen op een replica). De allowlist-controle, de READ ONLY-transactie, de plafonds en de redactor blijven gelden; alleen de menselijke stap valt weg.

Audit en redactie

Elke query die draait, wordt vastgelegd met de ingekorte querytekst, geraakte tabellen, aantal rijen, teruggegeven bytes, afkapping, geredigeerde kolomnamen, duur, fout, actor (AI of mens), hoe hij is goedgekeurd, en het BUG-issue waarvoor hij draaide. Deze records zijn append-only en horen bij je organisatie; een verbinding verwijderen verwijdert niet de geschiedenis van wat erdoorheen ging.

Plafonds op resultaten:

• Maximaal 50 rijen per query; de rest wordt afgekapt.
• Maximaal 64 KB resultaat.
• Statement-timeout van 5 seconden en een korte lock-timeout, afgedwongen door de database.

Redactie op kolomnaam gebeurt voordat rijen de agent bereiken. Een kolom wordt geredigeerd als een van deze termen in de naam voorkomt als heel segment, gescheiden door _, - of . (of als de hele naam): email, e_mail, phone, phone_number, password, passwd, secret, token, api_key (ook apikey, api-key), access_token, refresh_token, ssn, social_security, credit_card, card_number, cvv, iban, bank_account. Hoofdletters maken niet uit.

Dus email, user_email en billing.iban worden geredigeerd, maar emailed_at en tokens niet (het segment is een ander woord), en ook een camelCase-naam als userEmail niet (er is geen scheidingsteken). Redactie gaat op kolomnaam, niet op waarde: een vrije-tekstkolom notes met een e-mailadres erin wordt niet herkend. Houd zulke kolommen buiten de allowlist.

Problemen oplossen

"Read-only not verified" blijft staan na een geslaagde test. De credentials werken, maar de schrijfpoging werd niet geweigerd. De role heeft nog schrijf- of DDL-rechten. Maak hem SELECT-only en test opnieuw.

"schema X is not on the allowlist" of "no schemas are configured". Default-deny. Voeg het schema toe aan de allowlist. Noemt de fout een systeemschema zoals pg_catalog, laat de allowlist dan met rust: die query hoort te falen.

"forbidden keyword: X" of "writable CTE rejected". Een niet-SELECT-keyword (INSERT, UPDATE, DELETE, MERGE, DROP, COPY, CALL, …) of een schrijvende CTE is bewust geweigerd.

Een query krijgt een timeout. Het plafond van 5 seconden greep in. De query is duur of de replica loopt achter. Diagnostische queries mogen productie nooit blokkeren.

De verbinding werd op mislukt gezet nadat hij werkte. Een read-only-overtreding bereikte de database en Postgres weigerde hem. De verbinding wordt op mislukt gezet zodat het opvalt. Bekijk de audit-regel en maak de allowlist krapper voordat je hem weer aanzet.

Gerelateerd: Database-connector (gebruikersgids) · Google Cloud (read-only) · Security & audit