Database Connector
Connect structured data sources so agents can query databases and explain results
What is a Database Connector?
A database connector is a saved connection to a structured data source such as Postgres, MySQL, SQL Server, or MongoDB. Once connected, Chocolate Factory exposes built-in database tools that agents can use during a conversation:
Database connectors let agents query structured data sources directly from a conversation. Agents can list tables, run SQL queries, and explain results in plain language.
| Tool | Description |
|---|---|
| list_tables | Returns the tables and columns the agent is allowed to access, including any descriptions you have added. |
| execute_sql | Runs a SQL query against the connected database and returns the results. |
When a user chats with an agent, the agent can choose and run database tools automatically based on the prompt and its configuration.
Each connected database suffixes its tool names with a connection identifier to prevent collisions when multiple databases are attached to the same agent.
When to Use Database Connectors
Use database connectors when you want agents to work with live structured data:
- Answer data questions → “How many orders were placed last month?” or “What are the top five products by revenue?”
- Explore schema → “What tables are available?” or “Which columns does the customers table have?”
- Generate reports → summarize query results, compare metrics, or produce tables from SQL output.
- Support analysts and operators → let team members ask questions in natural language instead of writing SQL manually.
For unstructured documents and knowledge bases, use Knowledge Bases instead. For external APIs and third-party services, use MCP servers.
Authentication
Database connections support two authentication methods depending on the database type:
| Auth method | Description |
|---|---|
| Connection string | A standard database URI with username and password. Used for Postgres, MySQL, SQL Server, MariaDB, Oracle, IBM Db2, MongoDB, and Aurora clusters when connecting with credentials. |
| IAM authentication | AWS IAM-based authentication for Aurora Postgres and Aurora MySQL. Requires a dedicated database user with the rds_iam role and IAM DB authentication enabled on the cluster. Optional AWS access keys can be provided, or Chocolate Factory falls back to the instance role. |
When creating a connection, you can also enable Read Only mode to restrict the agent to read queries only and prevent unintended writes.
Connection strings and AWS credentials are sensitive. Only users with appropriate permissions can create or update database connections. Never share credentials in chat messages or public repositories.
Tips for Effective Prompts
To help your agent query the right data, be explicit about what you need:
- Name the database or subject → “From the sales database, show total revenue by region” instead of “show me revenue.”
- Specify the time range or filters → include dates, statuses, IDs, or other constraints the query needs.
- State the output format → “Return a table” or “Summarize the top three findings in bullet points.”
- Ask for explanations → “Explain what this query does before running it” if you want to review the SQL first.
When an agent uses a database tool, you will see an inline indicator in the chat showing the tool name and status. Expand the reasoning trail to review the SQL that was run and the results returned.
See Chat with Agents for more guidance on writing effective prompts and reviewing tool activity.
Ready to connect your first database? See Setup & Configuration.