Why database access needs a gateway
An offboarded contractor’s CI pipeline continues to run Claude‑driven code that queries the company’s customer database. The pipeline still holds a static credential that was never rotated, and every night the agent pulls rows that contain personally identifiable information. Because the job runs unattended, no human ever sees the queries or the results.
At the same time, a data‑science team grants a service account read‑write privileges across multiple schemas, assuming the account will only be used for model training. In practice the same account can be invoked by any Claude request, giving the model the ability to modify tables, drop indexes, or export data to an external bucket.
The result is a wide‑open attack surface: anyone who can trigger a Claude generation can issue arbitrary SQL, exfiltrate data, or corrupt production state. Without a centralized enforcement point there is no record of who ran which query, no way to hide sensitive columns from the model’s output, and no chance to require an explicit approval before a destructive command runs.
To close the gap you need a layer‑7 gateway that sits between the Claude agent and the database. The gateway must authenticate the request, enforce fine‑grained policies, optionally mask column values, require just‑in‑time approval for high‑risk statements, and record the entire session for later replay.
How hoop.dev enforces database access for Claude
hoop.dev provides exactly that. It acts as an identity‑aware proxy: users and agents present OIDC or SAML tokens, the gateway validates the token, extracts group membership, and then decides whether the request may proceed. The actual database credentials never leave the gateway, so the Claude process never sees a secret.
hoop.dev records each session, enabling replay and forensic analysis long after the query finishes. It masks sensitive fields in result sets, ensuring that personally identifiable information never reaches the Claude model unless a policy explicitly allows it. For commands that could alter schema or delete data, hoop.dev requires a just‑in‑time approval workflow, pausing execution until an authorized reviewer grants permission.
When a statement matches a deny rule, such as a DROP DATABASE or an export to an external endpoint, hoop.dev blocks the command before it reaches the database engine. This prevents accidental or malicious data loss without requiring changes to the Claude code itself.
Setting up the control plane
The first step is to configure identity. Connect an OIDC or SAML provider (Okta, Azure AD, Google Workspace, etc.) to the gateway so that every Claude request carries a verifiable token. The token conveys the user’s group membership, which the gateway uses to look up fine‑grained database access policies.
Next, deploy the network‑resident agent close to the target database. The agent holds the database credential and presents it to the database only after the gateway has approved the request. Because the credential remains inside the agent, the Claude runtime never handles it directly.
Finally, define policy rules that describe which groups may read, write, or administer each schema. Policies can also specify columns to mask, thresholds for JIT approval, and audit‑log retention requirements. All of these rules are enforced at the data path, the only place where access decisions can be reliably applied.
Benefits of a gateway approach
- Complete audit trail: hoop.dev logs who executed which query, when, and what the result looked like.
- Reduced blast radius: only the gateway can speak to the database, so compromised Claude agents cannot bypass controls.
- Inline data protection: sensitive columns are masked in real time, preventing accidental leakage to AI models.
- Just‑in‑time governance: high‑risk statements pause for human approval, eliminating silent destructive actions.
- Evidence for compliance: session recordings and policy enforcement logs satisfy audit requirements for standards such as SOC 2.
Getting started
Begin with the getting‑started guide to spin up the gateway using Docker Compose. The guide walks you through connecting an OIDC provider, registering a PostgreSQL target, and defining a simple read‑only policy for a Claude service account.
For deeper policy design, the learn section explains how to compose masking rules, configure approval workflows, and tune session retention.
When you are ready to explore the source code or contribute, view the open‑source repository on GitHub.
FAQ
Can I use hoop.dev with an on‑prem PostgreSQL instance?
Yes. The gateway supports PostgreSQL connections both in the cloud and on‑premises. The agent runs in the same network segment as the database, and the gateway forwards traffic after applying all configured policies.
What happens if the Claude model tries to run a query that is not covered by any policy?
If no explicit allow rule matches, hoop.dev denies the request by default and logs the attempt. You can then add a policy or create an approval flow for that specific statement.
Do I need to change my existing Claude integration code?
No code changes are required. Claude continues to use its standard database client libraries; the only difference is that the connection endpoint points to the gateway instead of the database directly.
