Step 6: 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 | 2 | Look up records and read the table's structure |
| Write | 5 | Everything in Read, plus add records (one at a time or in bulk) and update existing ones |
| Full | 7 | Everything in Write, plus delete records and run custom look-ups |
Tools by permission level
| Tool | Read | Write | Full |
|---|---|---|---|
| Get table info | Yes | Yes | Yes |
| Select records | Yes | Yes | Yes |
| Insert record | — | Yes | Yes |
| Bulk insert | — | Yes | Yes |
| Update records | — | Yes | Yes |
| Delete records | — | — | Yes |
| Custom query | — | — | 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. Each connected database adds tools based on its permission level:
| Permission | Tools added per database |
|---|---|
| Read | 2 |
| Write | 5 |
| Full | 7 |
For example, connecting 3 databases at Full permission uses 21 tools — leaving room for 4 custom tools.
If you're close to the limit, give Read permission to databases the agent only needs to look up. Save Write and Full for the databases it actually has to change.
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 7: Skills to give your agent extra abilities beyond tools and knowledge.