HyperTeamsConnecting a database
What you will learn How to attach a database to a workspace, which four kinds are supported, and the one thing you must settle before attaching — not a tool setting, but account permissions.
If tables and SQL are new, start with What a database is.
What changes
Until now a person pulled the data and pasted it into the conversation. Attach a database and the agent queries it directly.
The grounding from attaching sources extends from documents to your own data.
Four kinds are supported
| Kind | Connection string |
|---|---|
| PostgreSQL | postgres://… or postgresql://… |
| MySQL | mysql://… |
| MongoDB | mongodb://… · mongodb+srv://… |
| SQLite | a file path — file:… or .sqlite · .sqlite3 · .db |
You do not pick the kind separately. It is inferred from the scheme at the
front of the connection string. Which means a missing scheme means no connection
— writing user:pass@host/db without postgres:// is most first failures.
How to attach it
Same route as "outward" in connecting an MCP server. Add the database MCP address as a connection and pass the connection string as a header.
Attaching more than one
Put a name in the middle of the header name.
They are then distinguished as primary and analytics. With a single
connection the name is default.
Never paste a connection string into a conversation. It contains a password. Put it in the connection settings only — the same principle as managing credentials.
The ten tools the agent gets
Sorted into the three classes from tools are permissions:
| Class | Tools | Nature |
|---|---|---|
| Connection | db_connect · db_disconnect · db_list_connections | state |
| Read | db_list_tables · db_describe_table · db_select | changes nothing |
| Raw query | db_query | runs the SQL it is handed, as given |
| Irreversible | db_insert · db_update · db_delete | writes and deletes |
Read that db_query row again
db_query is not read-only. It executes the SQL string it receives. Turn off
db_insert, db_update and db_delete and you still have not blocked writes if
db_query is on.
db_delete does require a where clause, which prevents whole-table deletions —
but deleted rows do not come back.
So block it with the account
A read-only account is more reliable than turning tools off.
The difference is who enforces it. Tool settings can be changed by someone inside the workspace; account permissions are enforced by the database. Least privilege here is a question about the database account, not the tool list.
Connections are cleaned up after 30 minutes
A connection opened by db_connect closes 30 minutes after it was last used.
Mid-way through a long job you will see exactly this:
Just call db_connect again. For unattended work such as a schedule, put
"reconnect if the connection has dropped" into the instruction.
Before you attach it
The last line matters most. It creates a path where a sentence from outside
becomes a query — the structure from when what it reads becomes a
command. If an email body from a customer can reach
db_query, a read-only account is a condition, not a choice.
Common misconceptions
"Can't I just tell it to only SELECT?"
Deciding by instruction and blocking by permission are different things. Instructions can drift or be invented, and they can be overridden by outside input. Blocking is the account's job.
"There are a lot of tables — does it see all of them?"
db_list_tables lists them and db_describe_table shows the columns. But only
what the account can see is visible — which is why narrowing the account is
narrowing the scope.
Check yourself
1. Why is turning off every write tool not enough?
Answer
Because db_query executes the SQL it is handed. It is not read-only, so it
alone permits writes.
2. Why is a read-only account more reliable than a tool setting?
Answer
Different enforcers. Tool settings can be changed inside the workspace; account permissions are enforced by the database itself.
3. Why is an inbound path in the same workspace dangerous?
Answer
A sentence from outside can turn into a query. It is the same structure as prompt injection, so in that configuration a read-only account is a condition rather than a choice.
Next, try the attached tools by hand → The playground