> For the full page index, fetch https://echonova.ai/llms.txt

# Database tool security

How your connection string is protected, why database tools are read-only, what the agent can see, and what is stored and logged.

Connecting a database hands EchoNova a live credential to your data, so decide the
credential and the question list with that in mind. This page covers what the agent
can do with the connection, what you should grant it, and what is kept afterwards.
The steps are on [Connect a database](/docs/agents/database-tools-connect) and
[Review and approve database questions](/docs/agents/database-tools-templates).

## Read-only, and fixed in advance

The feature reads. There is no path that writes, and all three supported engines are
read-only sources. Every approved question is a read.

Just as important, the agent does not compose SQL during a conversation. It picks
from the questions you approved, each one a fixed query with named parameters, and
supplies the parameter values. A question nobody approved is not in the conversation
at all, so the surface the agent can reach is whatever list you signed off, and
nothing else.

When a connection is registered, EchoNova checks whether TLS verified and whether
the user looks read-only, and shows both on the connection: a **TLS** chip and, when
the second check did not pass, a **read-only: advisory** chip reading "The role can
create temp tables. Sessions are forced read-only regardless — advisory only."
That second result is advisory rather than a blocker.

## Give it the smallest user you can

The advisory check is not a substitute for a restricted user. Whatever the
credential can do, a question approved against it can do.

> [!WARNING]
> Create a dedicated read-only database user for EchoNova, grant it `SELECT` on only
> the tables the agent needs, and give it nothing else. The connection string cannot
> be read back or edited after you save it, so a user with more access than intended
> has to be fixed on your side and the connection registered again.

**Recommended**

```sql
CREATE ROLE echonova_ro LOGIN PASSWORD '…';
GRANT CONNECT ON DATABASE shop TO echonova_ro;
GRANT USAGE ON SCHEMA public TO echonova_ro;
GRANT SELECT ON orders, order_lines, shipments TO echonova_ro;
ALTER ROLE echonova_ro SET default_transaction_read_only = on;
```

**Less effective**

```sql
CREATE ROLE echonova_ro LOGIN PASSWORD '…';
GRANT SELECT ON ALL TABLES IN SCHEMA public TO echonova_ro;
```

Two more choices are worth making deliberately:

- Point the connection at a read replica rather than the primary where you have one.
  Queries run during live conversations, so they compete with your own traffic.
- Require TLS on the user or on the server, so a connection without it cannot
  succeed at all rather than relying on the connection string to ask for it.

Anything the read-only user cannot see is also invisible to drafting, which is the
cleanest way to keep a table out of the question list entirely.

## Where the connection string lives

The connection string is sealed the moment it arrives and is never held in plain
text. It is encrypted with `AES-256-GCM` under a key issued by AWS KMS for that one
connection and bound to your workspace, so a sealed string cannot be opened under
another workspace.

Nothing returns it. Registering answers with the connection id, the status, the
engine, the host and database string, and the two check results. The connection list
adds the name you gave it, a schema fingerprint and the number of questions. Your
browser never receives the connection string, in any shape, at any point. The same
string cannot be registered twice in one workspace, and detecting that does not
require keeping a second copy of it.

The sealed string is opened only when it is needed: to start a conversation, to
resync the connection, and to re-check a question you edited. An opened value is
held in memory for at most five minutes and is not written anywhere.

## Your approvals are the authority

A question's approval decides whether the agent can call it, even when a rename has
not reached the matching text a caller's wording is compared against. When the two
disagree, press **Resync** on the connection; that rebuilds the matching text from
the approved questions.

## What the agent gets

At the start of each conversation the agent receives, for each connection it is
allowed to query: the connection string, the business description you wrote, the
engine, the host and database string, the schema fingerprint, and your approved
questions with their parameters, their row and time limits and their result hints.
Queries run against your database directly, read-only, and the connection string is
never logged.

What it does not get is as specific:

- Questions you have not approved. They are filtered out before anything is sent.
- Connections that are not attached to that agent, that are not **Ready**, or that
  belong to another workspace. Each is skipped, and an agent left with no usable
  connection has no database to query.
- Anything at all when the agent has databases switched off.

## What is kept afterwards

A conversation's record never contains your connection string; it is removed before
the record is written.

The query behind each approved question is kept, because it is what runs, and it is
never returned: no screen and no response shows the SQL, to you or to a caller.

Connection strings and request bodies are not written to logs.

## Who can do this

The database controls need access to the workspace and no extra permission. Anyone
in the workspace can therefore register a database, approve or un-approve a
question, resync a connection, and delete one along with its questions.

Every action is scoped to the workspace you are signed in to.

## FAQ

### Can the agent run SQL a caller dictates?

No. The agent chooses from the approved questions and fills their named parameters.
It cannot write a query, change one, or reach a question you did not approve.

### Can EchoNova write to, or delete from, my database?

No. Every approved question is a read, and the feature has no write path. Granting
the user only `SELECT` makes that true at your end as well.

### Can I change the connection string without losing my approvals?

No. A connection string is fixed once saved. Rotating the database password means
registering a new connection and approving its questions again.

### Does my database have to be reachable from the internet?

It has to be reachable by EchoNova over TLS. Queries run against it directly during
conversations, so allow that path deliberately and keep the user read-only.

### What happens to the data a question returns?

It goes to the agent for that turn so it can answer the caller, and it appears in
the conversation's transcript as part of what was said. See
[Data retention](/docs/agents/data-retention) for how long conversations are kept.

## Related

- [Connect a database](/docs/agents/database-tools-connect): register the connection and its user
- [Review and approve database questions](/docs/agents/database-tools-templates): decide what the agent may ask
- [Data retention](/docs/agents/data-retention): how long conversations and their contents are kept