Database

Open the agent, find Database in its skills and press Settings. Add one entry per database:

• Name - a short label you would say in a sentence: prod, staging, reporting
• Host and Port - where the database answers (port defaults to 3306)
• Database - the schema name
• Username and Password - the account the agent will use
• Use SSL/TLS - turn on if your server expects an encrypted connection
• Safety - guarded (recommended) or unrestricted, explained below
• Ask before writing - when the agent must check with you first, explained below

Press Add for a second database. Removing an entry removes only that one; the others keep their own passwords.

Your database has to be reachable from the internet for the agent to connect. If it sits behind a firewall, allow Botonom's address or expose a tunnel endpoint. Addresses on a private network are refused on purpose.

Each connection carries its own safety mode, so a production database can be careful while a scratch one is not.

Guarded (the default):

• Statements that destroy or hand out access are refused outright: DROP, TRUNCATE, ALTER, RENAME, GRANT, REVOKE
• An UPDATE or DELETE with no WHERE is refused, because it would change every row
• A write that touches many rows is not run straight away: the agent first reports exactly how many rows it would change and waits for you to agree

Unrestricted: anything the database user can do, the agent can do, with no second look. Use it only on a database you could lose without consequence.

Permission decides whether the agent may write. This setting decides when it has to check with you first, and it lives on each connection:

• Wide changes (the default) - it asks when a change would touch many rows, or when it cannot tell how many it would touch
• Every write - it asks before any INSERT, UPDATE or DELETE, even one that turns out to change nothing
• Never ask - no confirmation step; on a guarded connection the destructive statements and the WHERE-less write are still refused

The two settings are independent, so "anything goes, but ask me first" is a valid combination: unrestricted safety with Every write.

When the agent asks, it does not run the statement. You get the statement it wants to run and how many rows it would change, and it only proceeds after you say so.

Reading and writing are separate permissions, and both are off until someone grants them.

If your workspace uses custom roles, open Roles & Access and grant the Database capabilities to the roles that should have them. A useful split is to give everyone the read tools (list tables, describe a table, sample rows, run a query) and keep the write tool for a smaller group.

Until a role is granted those capabilities, the agent does not even see the tools and will honestly say it cannot do it.

The agent works better when it can look before it writes:

• "What tables do we have?" - it lists them with rough row counts
• "Show me the orders table structure" - columns, types, keys and relationships
• "Show me a few rows from orders" - real examples, which is how it learns that your status column says iptal rather than cancelled
• "How many orders were cancelled last month?" - it writes the query and answers with the number

Ask for a number or a summary when that is what you want ("total revenue by month"), and the agent aggregates in the database instead of pulling thousands of rows back. Long lists are capped on purpose: an answer is not more true for being longer, and a huge result costs you tokens.

Ask for the file and you get one: "pull last month's orders and send it to me as Excel".

Behind the scenes the full result is written to a file and handed to the Data Export skill, which builds the spreadsheet and attaches it to the reply. The rows never travel through the conversation, so a 50,000-row export costs about the same as a short answer.

Data Export must be installed on the same agent for this. See Data Export.

"No database is configured" - the skill is installed but the connection details are empty, or the entry is missing a required field. Open Settings and complete it.

"Cannot reach the database" - your server did not answer in time. Usually a firewall: the connection has to be reachable from the internet.

"Access denied" - the username or password is wrong, or that user is not allowed to connect from outside. Check the grant.

The agent asks which database you mean - you have more than one connected and the question did not say. Name it ("in staging...") and it will go straight there. It never guesses, because a guess would eventually run a staging query against production.

The query took too long and stopped - queries are given a time limit so one heavy scan cannot stall everything. Narrow it with a date range or a WHERE and ask again.