Step 5: Database Connections
Connecting a database to your agent is like handing it the keys to a spreadsheet (think Excel or Google Sheets) and letting it work the rows for you — it can look up entries, add new ones, update what's there, and remove what's outdated, all by chatting in plain language. Once connected, your agent can answer questions and make changes against your real data instead of guessing.
You can connect one or more Nirvai databases to a single agent.
Before you start
- A saved agent (at least the Profile step completed)
- At least one database created in your workspace — see Creating databases
- A clear idea of what you want the agent to do with the data (just look things up, or also change them)
How it works
When you connect a database to an agent, Nirvai automatically sets up a set of tools for that database. The agent uses these tools to work with your data, the same way it uses any other tool.
Step-by-step
- Open your agent in the Agent Control Panel
- Go to the Databases panel
- Click Connect Database
- Select a database from your workspace
- Choose a permission level (what the agent is allowed to do — see below)
- The database tools are added to your agent automatically
Image: The databases panel showing connected databases with permission levels
You can also start from the database itself. Open a database, click the tools menu in the header, and choose Create AI Tools or Create AI Agent. The full walkthrough is in Database AI Features.
Permission levels
When you connect a database, you decide what the agent is allowed to do with it. Pick the lowest level that still does the job.
| Permission | Tools granted | What the agent can do |
|---|---|---|
| Read | 1 | Look up records |
| Write | 5 | Everything in Read, plus add records, update existing ones, and read/update long-form content fields |
| Full | 6 | Everything in Write, plus delete records |
Tools by permission level
| Tool | Read | Write | Full |
|---|---|---|---|
| Look up records | Yes | Yes | Yes |
| Add records | — | Yes | Yes |
| Update records | — | Yes | Yes |
| Read long-form content | — | Yes | Yes |
| Update long-form content | — | Yes | Yes |
| Delete records | — | — | Yes |
Choose the minimum permission level your agent needs. A FAQ bot that only looks things up should have Read. An agent that manages leads or processes orders needs Write or Full.
Database tools and the tool limit
Database tools count toward the 25-tool limit your agent shares with its custom tools. But all your connected databases share one set of database tools — the agent simply points each action at the right table — so connecting more databases doesn't keep adding tools. The cost is based on the highest permission among your connected databases:
| Highest permission among your databases | Tools used |
|---|---|
| Read only | 1 |
| Write | 5 |
| Full | 6 |
So your databases use at most 6 tools total, no matter how many you connect — leaving at least 19 slots for custom tools. For example, connecting 3 databases at Full permission still uses only 6 tools.
Databases are cheap on the tool budget — even a dozen connected tables use at most 6 slots. Still pick the lowest permission each one needs, for safety, not to save tool slots.
How the agent uses database tools
The agent decides when to use a database tool based on the user's request and your instructions. For example:
| User says | Agent does |
|---|---|
| "Show me all leads from last week" | Uses Select records with a date filter |
| "Add a new contact: John, john@email.com" | Uses Insert record with the provided values |
| "Mark task #42 as complete" | Uses Update records to change the status |
| "Delete the duplicate entry for Acme Corp" | Uses Delete records matching the condition |
| "How many orders did we process this month?" | Uses Select records with a count |
The agent knows the shape of your data (which columns it has and what kind of value each one holds) and formats values correctly. A currency column receives decimal numbers, a multi-select column receives a list of values, and so on.
Real-time notifications
When an agent changes your database (adds, updates, or deletes a record), an alert pops up in your browser right away if you have that database open. The alert shows:
- What operation was performed
- How many records were affected
- Which agent made the change
This way you always know when an agent is changing your data, even when you're not in the chat.
Use cases
| Scenario | Setup |
|---|---|
| Customer lookup bot | Connect your customers database with Read permission. The agent finds records by email, name, or order number. |
| Lead management agent | Connect your leads database with Write permission. The agent adds new leads from WhatsApp, updates their status, and flags duplicates. |
| Inventory tracker | Connect your products database with Full permission. The agent runs custom look-ups for stock reports and updates quantities in bulk. |
| Data entry assistant | Connect any database with Write permission. The agent reads incoming data (emails, forms, messages) and adds tidy records. |
Troubleshooting
| Problem | Fix |
|---|---|
| Agent can't find records | Check the permission level — it needs at least Read. Make sure the user's wording matches your column names. |
| Agent adds data incorrectly | Check the column types. The agent follows the format hints from your database. If data is consistently wrong, add an instruction like "The status column accepts: Open, In Progress, Done." |
| "Too many tools" error | You've gone over the 25-tool limit. Connect fewer databases or lower their permission levels. |
| Agent changes the wrong records | Add clearer instructions about when to update or delete. Consider using Read permission until you've tested how the agent behaves. |
What's next
After connecting your data, continue to Step 6: Skills to give your agent extra abilities beyond tools and knowledge.