OneQuery vs raw database access

OneQuery vs Direct Database Credentials: Safe AI Agent Access

Direct database credentials can be fast for a human, but they make the agent runtime the security boundary. OneQuery moves that boundary into a governed execution layer.

Connect a source View connectors

Direct answer

OneQuery vs direct database credentials: which should agents use?

Use OneQuery instead of direct database credentials when an AI agent needs production context. Direct credentials put the password, DSN, or cloud token inside the agent runtime; OneQuery keeps the credential server-side and gives the agent a bounded source interface.

The practical difference

A direct credential turns the agent environment into the control plane. If the credential can reach production, the agent can try to use that authority whenever its plan points there.

OneQuery keeps the useful part of the workflow: the agent can still ask focused database questions. The difference is that the source, credential, validation, limits, and audit record stay outside the prompt and outside the shell environment.

Recommended rollout

Start with the smallest read-only source that answers a real debugging question. Remove the raw DSN from the agent setup, give the agent the OneQuery source identifier, and treat denied or truncated requests as normal feedback instead of reasons to broaden the credential.

Comparison criteria

Where the boundary lives

Factor	OneQuery	direct database credentials
Credential exposure	Credentials stay in OneQuery source configuration and the agent receives only a source identifier and command surface.	The agent receives a password, DSN, IAM credential, or environment variable that can reach the database.
Query boundary	SQL requests pass through read-only validation, single-statement enforcement, limits, and source-specific execution controls.	Read-only behavior depends on the database role and on the agent choosing safe SQL.
Audit trail	Each request records actor, source, operation, outcome, and time in a purpose-built access history.	Teams often reconstruct agent activity from shell history, database logs, or model transcripts.
Rotation	Rotate the source credential centrally while keeping the agent workflow pointed at the same approved source.	Credential rotation requires updating every place where the agent or tool runtime received the secret.
Failure mode	Denied writes, oversized responses, missing permissions, and broad queries become explicit blocked states.	A prompt rule can tell the agent to be careful, but it cannot reduce the authority attached to the credential.

Choose OneQuery when

Production debugging where agents need real database context but should not hold secrets.
Teams that need an audit trail for agent data access.
Workflows where prompt rules are not enough to enforce read-only behavior.

Choose direct database credentials when

A local development database that contains no production data.
A one-off human DBA session where the operator already owns the credential.
A throwaway read-only role that can be revoked immediately after testing.

Rollout pattern

Move access without changing the agent job.

Create a read-only upstream database role for the data the agent is allowed to inspect.
Connect that role as a named OneQuery source.
Replace the agent's DSN or password with the OneQuery source identifier and command pattern.
Run a small production debugging workflow and review the resulting audit history.

FAQ

Common questions

When are direct database credentials acceptable for an AI agent?

Use a direct credential only for low-risk human workflows or isolated test data. For production data, the safer pattern is to give the agent a controlled source interface while the credential stays outside the model runtime.

Does OneQuery replace database-level permissions?

OneQuery is not a replacement for scoped database roles. It works best with read-only upstream roles, then adds source resolution, validation, limits, and audit records around the agent workflow.

How do I move from direct credentials to OneQuery?

Point the agent at a OneQuery source identifier, remove the database secret from the agent environment, and review the first runs in audit history before adding more sources.

Reference points

Docs behind the comparison

Governed access OneQuery docs on keeping raw provider credentials outside the agent runtime. Query boundaries OneQuery docs on read-only validation, single-statement execution, limits, and blocked requests.