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

# Connect a database

Register a read-only PostgreSQL, MySQL or MariaDB connection so an agent can answer callers from live data, and follow it from Reading schema to Ready.

A database connection lets an agent answer from your own data during a conversation.
You register the connection once, EchoNova reads the schema and drafts a list of
questions the database can answer, and you approve the ones the agent may use. This
page covers the connection itself. Approving the questions is
[Review and approve database questions](/docs/agents/database-tools-templates), and
what happens to your connection string is
[Database tool security](/docs/agents/database-tools-security).

A database is not a row in the workspace tool library the way a webhook tool or an
imported OpenAPI document is. [Tools overview](/docs/agents/tools-overview) explains
how the kinds differ.

## What you need

- Membership of the workspace. The database controls need access to the workspace and no
  extra permission, so anyone in it can connect a database or delete one.
- A PostgreSQL, MySQL or MariaDB database reachable over TLS. Those three engines
  are the whole list today.
- A database user with read-only access. Read
  [Database tool security](/docs/agents/database-tools-security) before you choose
  one.
- A connection string in SQLAlchemy form with an async driver, shaped like
  `postgresql+asyncpg://user:pass@host:5432/db?sslmode=require`.
- One or two sentences about the business. Drafting reads them, and the connection
  cannot be registered without them.

## Steps

### Step 1: Open the Add Tool form

On the agent, open the **Tools** tab and press **Add Tool**. In the dialog headed
**Add Tool**, choose the **Database** tab.

### Step 2: Name the connection

**Name** is required and holds up to 120 characters. It is the title every table and
sheet shows, instead of the host and database name.

### Step 3: Choose the engine

**Engine** lists MySQL, PostgreSQL and MariaDB in that order. MySQL is preselected,
so change it if your database is Postgres or MariaDB. It has to match the database
you are pointing at.

### Step 4: Paste the connection string

**Connection string** is required and holds up to 2000 characters. The field is
masked as you type. Point it at your read-only user and keep TLS on.

The string is sealed as it arrives and no screen or response returns it afterwards.
Keep your own copy: changing it means registering a new connection.

### Step 5: Describe the business

**Description** is the text that steers the questions EchoNova drafts. Write what
the business does and what callers usually ask about.

The form labels this field "(Optional)" and counts up to 500 characters. It is
required: submitting with it empty fails.

### Step 6: Press Test And Connect

**Test And Connect** seals the connection string, connects to your database over
TLS, checks whether the user is read-only, and starts drafting questions. The
connection appears immediately with the status **Reading schema…**.

> [!NOTE]
> **Sample values sent to the AI while drafting** offers **Masked (fake values)**
> and **Raw (real rows)**. Drafting uses masked values today whichever one you pick,
> so questions are drafted from your schema and fake samples. To keep a table out of
> drafting altogether, do not grant the read-only user access to it.

## Get it right

The description is the only thing that tells drafting what this database is for.
Name the business, the things callers ask about, and the words they use for them.

**Recommended**

```text
Online pharmacy in the UAE. Callers ask where their order is, whether a medicine
is in stock at a branch, and what a previous order contained. They say "parcel",
"prescription" and "branch".
```

**Less effective**

```text
Our main database.
```

## What happens next

Registering from an agent attaches the connection to that agent at once: it is added
to the agent's database list, database questions are switched on for that agent, and
the agent is saved without a further click. Registering it is the act of giving it
to the agent.

The connection then appears in the agent's tools table with the type **Database**,
the host and database string as its endpoint, and a status. It also appears on the
**Tool Library** page, with a chip counting its questions and a **TLS** chip that
fills in once TLS is verified.

While a connection is pending the list refreshes every 5 seconds and stops once
nothing is pending, so the status changes without a reload.

Nothing reaches a conversation yet. A new connection has no approved question, and
only approved questions reach the agent. Once the status is **Ready**, go to
[Review and approve database questions](/docs/agents/database-tools-templates).

## The three states

| Status    | Pill in the portal   | What it means                                                                         |
| --------- | -------------------- | ------------------------------------------------------------------------------------- |
| `pending` | **Reading schema…**  | EchoNova is reading the schema and drafting questions. There is nothing to review yet |
| `ready`   | **Ready**            | Drafting finished. The questions are listed for review                                |
| `failed`  | **Couldn't connect** | Connecting or drafting failed. The reason is shown on the connection                  |

Only a **Ready** connection reaches a conversation. One that is not ready is
skipped, and an agent left with no usable connection simply has no database to
query.

## Limits

| Limit                             | Value                                  | Applies to                         |
| --------------------------------- | -------------------------------------- | ---------------------------------- |
| Name                              | 120 characters                         | Registering                        |
| Connection string                 | 2000 characters                        | Registering                        |
| Description                       | 500 characters                         | Registering                        |
| Engines                           | `postgresql`, `mysql`, `mariadb`       | The whole feature today            |
| Connections per connection string | 1 per workspace                        | Registering the same string twice  |
| Reading the schema and drafting   | 30 seconds                             | Registering and resyncing          |
| Status refresh                    | Every 5 seconds while pending          | The tools screens                  |
| Editing a connection string       | Not offered. Register a new connection | The whole lifetime of a connection |

## Troubleshooting

### "Could not connect the database."

The message under the **Add Tool** form when registering fails. The common cause is
an empty **Description**, which the form allows and the request refuses. The others
are a database EchoNova could not reach, a TLS handshake that failed, and a
connection string the engine could not read. Fill in the description, check the host
and TLS, then submit again.

### The status is Couldn't connect

Connecting or drafting failed. Open the connection: the reason is printed in a red
box under the header. Fix the cause and press **Resync**, or delete the connection
and register it again.

### "Duplicate value for connection string"

This workspace already has a connection with that exact string. Use the existing
connection instead of a second one: the same connection can be attached to as many
agents as you like.

### The status stays at Reading schema…

Drafting has not finished, so no questions are listed. Press **Resync** to run it
again. If it is still pending after a resync, delete the connection and register it
again.

### The connection is Ready but the agent never uses it

A connection with no approved question gives the agent nothing. Approve at least
one, and check the connection is attached to the agent you are testing rather than
only present in the workspace.

## FAQ

### Can I see the connection string again?

No. It is sealed on the way in and no screen or response returns it. The portal
shows the host and database part only, never the credentials.

### Can two agents share one database?

Yes. Each agent holds its own list of the connections it may query, and the same
connection can appear in several of those lists.

### Does EchoNova write to my database?

No. Every approved question is a read. See
[Database tool security](/docs/agents/database-tools-security).

### What does deleting a connection do?

It removes the connection and its questions, and the agent stops reaching them. It
cannot be undone, and the connection string goes with it. An agent that still lists
a deleted connection is unaffected; the connection is simply skipped.

### Where else can I manage a connection?

The **Tool Library** page lists every database in the workspace alongside the other
tools, with the same review sheet behind the row menu. Registering a new one happens
from an agent's **Add Tool** form.

## Related

- [Review and approve database questions](/docs/agents/database-tools-templates): decide what the agent may ask
- [Database tool security](/docs/agents/database-tools-security): the user to create and what is kept
- [Tools overview](/docs/agents/tools-overview): how databases differ from the other tool kinds
- [OpenAPI tools](/docs/agents/openapi-tools): reach live data through an API instead