DB Query Tool

A DB Query Tool lets agents run parameterized SQL queries against your own databases. Unlike the BigQuery and Snowflake integrations (which use dedicated cloud data warehouse connectors), the DB Query tool connects directly to relational databases you host.

Supported databases: PostgreSQL, MySQL, Microsoft SQL Server, SQLite, Oracle

When to use DB Query

Use DB Query when:

• You have a relational database the agent needs to look up data from
• You want to query internal operational data (user accounts, orders, records)
• You need full parameterized SQL control with custom filtering

Use BigQuery or Snowflake for cloud data warehouses — they use optimized connectors for those platforms.

Creating a DB Query Tool

1. Go to your project → Integrations
2. Click Add Integration → Browse → DB Query
3. Fill in the tool name and description
4. Configure the connection and query in the form

Configuring the connection

Field	Description
Database type	postgresql, mysql, mssql, sqlite, or oracle
Host	Database server hostname or IP
Port	Port number (5432 for PostgreSQL, 3306 for MySQL, 1433 for MSSQL)
Database	Database name to connect to
Username	Database user
Password	Stored as a secret

Writing the query

Enter a SQL query template. Use {{param_name}} placeholders for values the agent will provide:

SELECT id, email, plan, created_at
FROM customers
WHERE email = '{{customer_email}}'
LIMIT 1

The platform uses parameterized queries to prevent SQL injection — {{param_name}} values are bound as query parameters, not interpolated as raw strings.

Defining parameters

For each {{param_name}} in your query, define a parameter:

Field	Description
Name	Must match the placeholder (e.g. customer_email)
Type	string, number, boolean
Required	Whether it must be provided to run the query
Description	What this value is — guides the agent on what to collect

Security best practices

• Grant minimum permissions — the database user should only have SELECT on the tables the agent needs. Grant INSERT/UPDATE/DELETE only if the tool requires writes.
• Avoid raw table joins over sensitive data — write targeted queries that return only the columns needed
• Use read-only replicas — for high-traffic agents, point the tool at a replica rather than your primary database
• Never expose credentials in the system prompt — credentials are stored in vault and injected securely

Example: customer account lookup

Query:

SELECT
  c.id,
  c.full_name,
  c.email,
  c.subscription_plan,
  c.status,
  COUNT(o.id) AS order_count
FROM customers c
LEFT JOIN orders o ON o.customer_id = c.id
WHERE c.email = '{{email}}'
GROUP BY c.id
LIMIT 1

Parameters:

Name	Type	Required	Description
email	string	Yes	The customer's email address (collect from the user)

System prompt fragment:

When a customer asks about their account:
1. Ask for their email address if not already provided.
2. Use the Account Lookup tool to retrieve their account details.
3. Share their plan, status, and order count in a friendly response.
Do not expose the raw database ID.

Troubleshooting

Connection refused

The database host or port is wrong, or the database server is not accepting connections from Vois AI's backend. Verify the host, port, and that your firewall allows inbound connections from Vois AI IP ranges.

Authentication failed

The username or password is incorrect. Re-enter them carefully — passwords are case-sensitive.

relation does not exist / table not found

The table name in the query doesn't exist, or the database user doesn't have access to it. Check spelling and case (PostgreSQL table names are case-sensitive unless quoted).

Query returns no results

The parameter value doesn't match any rows. This is usually correct behaviour — instruct the agent to handle empty results gracefully in the system prompt: "If no results are found, tell the user you couldn't find an account with that email."

Slow queries

Add an index on the columns used in WHERE clauses. For high-frequency agents, avoid full table scans.