How to Connect an AI Agent to a Database

To connect an AI agent to a database safely, give it a dedicated, scoped credential, start with read-only access, expose the schema so it writes correct queries, validate and parameterize every query before it runs, require a preview or approval before any write, and log every query the agent issues. The order matters: access scope first, schema awareness second, query safety third, audit always. Connecting an agent to a database is less about the connection string and more about deciding exactly what the agent is allowed to do once it is connected.

This guide treats the database as a tool the agent uses, the same way it might use an API or a file store. If you have not yet seen how agents call tools, tool use explained covers the general pattern; a database is one of the most powerful and most sensitive tools you can hand an agent, which is why the controls below are not optional.

The short answer

A safe agent-to-database connection has six parts, and you should put them in place before the agent runs against real data:

• Scoped credential: the agent connects with its own database user, not your admin login.
• Read-only by default: grant write access only where a specific task needs it.
• Schema awareness: the agent knows the tables, columns, and types so its queries are valid.
• Query validation: every query is parameterized and checked before it executes.
• Approval on writes: anything that changes data is previewed or approved first.
• Full audit log: every query the agent runs is recorded.

Skip any one of these and you have a gap. Skip the credential scope and a prompt-injection attack reaches your whole database. Skip schema awareness and the agent guesses at column names and fails or, worse, reads the wrong table. The rest of this guide takes each part in turn.

Read vs write access

The single most important decision is whether the agent can change data at all. Most agent tasks only need to read. An agent that answers questions about your orders, builds a weekly revenue summary, looks up a customer record, or enriches a row with data it fetched elsewhere is a reader. It runs SELECT statements and returns results. It never modifies anything.

Read access carries real but bounded risk: the agent could read data it should not, or return sensitive fields in an answer. You contain that by scoping which tables and columns the read role can see, which the next section covers. What read access cannot do is corrupt or delete your data, and that is the failure mode that keeps people up at night.

Write access is a different category. An agent that updates a status, inserts a record, or deletes a row can break data integrity, overwrite good values with bad ones, or remove rows that other systems depend on. Grant it only when the task genuinely requires it, and only for the specific operations and tables involved. An agent that enriches a CRM record needs UPDATE on a few columns of one table, not write access to the whole schema.

A useful default: split the work. Let the agent read freely within its scope to gather what it needs and reason about it, then route any write through a narrow, validated, approved path. This mirrors the broader principle in how to limit agent actions: the agent can think about anything, but it can only act within a tightly drawn boundary.

Least-privilege roles and scoped credentials

Least privilege means the agent's database role has exactly the permissions its job needs and nothing more. This is a foundational security principle: the United States National Institute of Standards and Technology defines least privilege in its glossary as allowing only the access "necessary to accomplish assigned tasks in accordance with organizational missions and business functions." Apply it literally to your agent.

In practice, that means:

• A dedicated database user for the agent. Never reuse your admin account or the credential your main application uses. The agent gets its own username, so its activity is separable in logs and its access is revocable on its own.
• Privileges granted, not inherited. Start the role with no privileges and add only what a task requires: SELECT on the tables it reads, and, where needed, INSERT or UPDATE on the specific tables and columns it writes. Withhold DELETE, DROP, ALTER, and TRUNCATE unless a task provably needs them.
• Table and column scoping. If the agent only needs three tables, grant access to three tables. If a table has sensitive columns the agent never needs, expose a view that omits them and point the role at the view instead.
• A read replica where possible. For read-heavy agents, point the connection at a replica rather than your primary database. The agent cannot write to a replica even if something goes wrong, and its queries do not compete with production traffic.

The credential itself needs care. Store the database secret in a secrets manager or an encrypted store, never in the prompt, never hardcoded in source, and never pasted into a chat. Rotate it on a schedule so an old leaked secret stops working. A scoped, rotated, separately stored credential means that even in the worst case, a leaked secret only exposes what that one narrow role could already do, and only until the next rotation. The same containment thinking runs through AI agent safety and guardrails.

Give the agent schema awareness

An agent cannot write a correct query against a schema it has never seen. If you ask it for "last month's revenue by region" and it does not know your tables are named orders and regions with a total_cents column, it will hallucinate plausible-looking SQL that references columns that do not exist. The query fails, or it silently reads the wrong field.

Schema awareness fixes this. Before the agent generates SQL, it needs the structure of the database in context: table names, column names, data types, primary and foreign keys, and ideally a short note on what each table holds. There are two ways to supply it:

• Let the agent introspect. Through its read role, the agent queries the database's system catalog to discover tables and columns at run time. This stays current automatically as the schema evolves, because the agent reads the live structure each time.
• Supply a schema description. You hand the agent a curated description of the relevant tables and columns, often with example values and relationship notes. This gives you control over what the agent sees and lets you add business context the raw schema lacks, such as that status = 3 means "shipped."

Most reliable setups combine both: introspection to stay accurate, plus a curated layer of business meaning the bare schema cannot express. With the schema in context, the agent maps a plain-language request to columns that actually exist, joins tables correctly, and produces SQL that runs the first time. Schema awareness is also what lets the agent explain its own query back to you, which matters for the preview step later. Giving an agent the right context to act is the same skill covered in how to give an agent multiple tool access, applied to one specific, high-value tool.

Validate and parameterize every query

Even with a correct schema and a scoped role, the query the agent generates needs checking before it runs. Two safeguards do most of the work: parameterization and validation.

Parameterize every query. User input, including anything an agent infers from a user's request, must be passed as bound parameters, not concatenated into the SQL string. This is the standard defense against SQL injection. The Open Web Application Security Project lists injection among the most critical web application security risks, and parameterized queries are its primary recommended defense. When values travel as parameters, a malicious string like '; DROP TABLE orders; -- is treated as data, not as code, and the attack does nothing. With an agent in the loop, this matters even more, because the text driving the query may originate from an untrusted email, document, or web page the agent processed.

Validate before execution. Beyond parameterization, check the generated query against rules before it runs:

• Statement type: for a read-only task, reject anything that is not a SELECT. The role should already block writes, but checking at the query layer too is cheap defense in depth.
• Scope: confirm the query only touches tables the task is allowed to use.
• Guardrails on writes: require a WHERE clause on any UPDATE or DELETE so a missing condition cannot modify every row, and cap the number of rows a single statement may affect.
• Resource limits: apply a query timeout and a row-return limit so a runaway query cannot exhaust the database.

Validation turns the agent's generated SQL from "whatever the model produced" into "a query that passed an explicit set of checks." If a query fails validation, the agent gets an error it can reason about and retry, rather than the query hitting your data. That retry path is part of good agent error handling and rollback: catch the bad query at the boundary, surface the error, and let the agent correct course instead of failing silently.

Preview and approve before writes

Reads can run unattended once scoped and validated. Writes are where you add a human checkpoint, because a write that goes wrong is far harder to undo than a read that returns too much.

Two patterns work well, and you can use both:

• Preview the effect. Before a write commits, show what it will do: the exact statement, the rows it will affect, and the before-and-after values for an UPDATE. For a destructive operation, run it inside a transaction, report the affected row count, and only commit once the count looks right. Seeing "this will update 4 rows" before it happens catches the case where a bad WHERE clause would have hit 40,000.
• Require approval. For higher-stakes writes, the agent stops and asks a person to confirm before it proceeds. This is the database-specific form of a human-in-the-loop control. You decide the threshold: approve every write, approve only deletes, approve only writes affecting more than a set number of rows, or approve only on tables you flag as sensitive.

Calibrate the friction to the risk. Inserting a log row needs no approval. Updating a customer's billing status, or deleting anything, should pause for a human. The goal is to make the irreversible reversible-by-default: nothing changes until someone, or some rule, has confirmed it should.

Audit every query the agent runs

Every query the agent issues should be logged, whether it read or wrote, whether it succeeded or failed. An agent with database access and no query log is an unaudited operator on your data, and that is a position you never want to be in when a question comes up about what changed and why.

A useful query log captures, for each query:

• Timestamp and which task or run issued the query.
• The exact SQL as executed, including the bound parameter values.
• The outcome: rows returned for a read, rows affected for a write, or the error if it failed.
• The decision trail for writes: whether it was previewed, who approved it, and when.

This log earns its keep in three ways. It lets you review what the agent actually did rather than what you assumed it would do. It catches mistakes early, when a single odd query stands out, instead of after a pattern has done damage. And it gives you an evidence trail if you ever need to prove what touched a record, which matters for compliance and for trust. Pair the query log with the agent's own action history so you can connect a database write back to the reasoning step that triggered it; that end-to-end trace is invaluable when you debug agent tool errors.

How Gravity handles database access

Gravity is an AI agent platform. You describe the work in plain words, and an expert-built agent runs it in about 60 seconds. When that work involves a database, the controls in this guide are built into how the agent connects, rather than something you assemble yourself.

The agent connects through a scoped credential, defaults to read access, and only writes where a task requires it. It works from the schema so its queries reference real columns, parameterizes and validates each query before it runs, and previews or asks for approval before any write that changes your data. Every query it issues is logged with its parameters and result, so you can review exactly what ran. You describe the outcome you want; the platform handles the connection, the scoping, and the audit trail. Pay per use: $1 equals 1,000 credits, and you only pay when the agent runs.

If this is your first time wiring an agent up to a real data source, setting up your first AI agent walks through the flow from plain-language description to running workflow, and what is an AI agent covers why an agent that reasons over your schema handles real requests better than a fixed query script. For agents that need to remember context across runs, building an agent with memory pairs naturally with database access. The glossary defines the terms used throughout if any are new.

FAQ

Should I give an AI agent write access to my database?

Start with read-only. Most agent tasks, such as answering questions, building reports, or enriching records, only need to read. Grant write access only for the specific tables and operations a task requires, and gate writes behind validation and, for anything irreversible, a human approval step. Read-only by default removes the largest class of database risk.

How does an AI agent write correct SQL against my schema?

Give the agent schema awareness. It needs the table names, column names, types, and relationships before it can write a query that runs. You provide this by exposing the schema to the agent, either by letting it introspect the database through its read role or by supplying a schema description. With the schema in context, the agent maps a plain-language request to columns that actually exist instead of guessing.

How do I stop an agent from running a destructive query?

Layer three controls. First, scope the database role so the agent physically cannot run operations outside its job, for example no DELETE or DROP privilege. Second, validate and parameterize every query before execution so malformed or injection-style input is rejected. Third, require a preview or human approval before any write commits. A query the role cannot run, that fails validation, or that a person has not approved never reaches your data.

What database credentials should an AI agent use?

A dedicated, scoped credential for the agent, never your admin or application login. Create a database role with only the privileges the task needs, on only the tables it touches, and issue the agent its own username and secret. Store the secret in a secrets manager, not in the prompt or in code, and rotate it on a schedule. A scoped credential limits the blast radius if the secret is ever exposed.

Can I see every query an AI agent ran?

Yes, and you should require it. Log every query the agent issues with a timestamp, the exact SQL, the parameters, the row count returned or affected, and the result. This audit trail lets you review what the agent did, catch mistakes, and prove what touched the data if a question comes up later. Treat an agent with no query log the same as an unaudited admin: a risk you do not need to take.