SQL Database Connector

Overview

Critical business data often lives in SQL databases that only developers or analysts can query. When a customer asks “Is my subscription active?” or a manager asks “How many orders shipped this week?”, someone has to write a query, run it, and relay the answer. That loop can take hours.

The SQL Database Connector lets your AI agent query your database directly, translating natural language questions into SQL and returning results in real time. All queries are read-only with configurable table restrictions and row limits to keep your data safe.

When to Enable This

• Business users frequently request data that lives in a SQL database
• Your support team needs to look up customer records that aren't in a CRM
• You want your AI agent to answer questions using live transactional data
• Analysts are bottlenecked running ad-hoc queries for non-technical colleagues

Available Actions

Security & Safety

Data security is paramount. The SQL Database Connector enforces multiple layers of protection:

• Read-only enforcement: All queries run through a read-only database user. ChatSpark additionally parses and rejects any query containing INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, or TRUNCATE statements before execution.
• Table allowlist: You specify exactly which tables the agent can access. Queries referencing other tables are blocked.
• Row limit: Every query has a hard row cap (configurable, default 100) to prevent runaway result sets.
• Connection encryption: All connections use TLS/SSL. Credentials are encrypted at rest using AES-256.
• Query logging: Every query executed is logged in your ChatSpark audit trail for review.

Prerequisites

• A ChatSpark Enterprise plan
• A SQL database accessible from the internet (or via IP whitelisting)
• A read-only database user with SELECT privileges on target tables
• Supported database types: PostgreSQL, MySQL, Microsoft SQL Server, MariaDB

Setup Instructions

Step 1: Create a Read-Only Database User

1. Connect to your database as an admin
2. Create a new user with SELECT-only privileges on the tables you want to expose
3. Test the connection from an external client to confirm network access

Step 2: Whitelist ChatSpark IPs

1. In your ChatSpark Enterprise settings, find the list of egress IP addresses
2. Add these IPs to your database firewall or security group rules
3. Verify connectivity by testing from the ChatSpark AI Actions settings page

Step 3: Enable in ChatSpark

1. In ChatSpark, go to AI Actions
2. Find SQL Database Connector in the Library and click Enable
3. Select the agent(s) that should have access
4. Enter your database type, connection string, allowed tables, and max rows
5. Click Test Connection to verify
6. Click Save

Configuration Fields

Testing Your Integration

After setup, open your AI agent and try these realistic queries:

• “How many orders were placed this week?”
• “What tables are available?”
• “Show me the top 10 customers by total spend”
• “Is there an active subscription for user@example.com?”

Use the Test Connection button in settings first to verify the database is reachable and credentials work before testing through the chat widget.

Troubleshooting

Connection refused

Verify ChatSpark's egress IPs are whitelisted in your database firewall. Also check that the database is listening on the specified port and accepts external connections.

Authentication failed

Double-check the username, password, and database name in your connection string. Some databases require SSL; make sure sslmode=require is included if your server enforces encrypted connections.

Query blocked: table not allowed

The agent tried to query a table not in your Allowed Tables list. Add the table to the allowlist if it should be accessible, or rephrase the question to target an allowed table.

Results truncated

If the query returns more rows than your Max Rows setting, results are truncated. Increase the limit if needed, or ask more specific questions to narrow the result set.