docs/en/integrations/cockroachdb/tools/cockroachdb-execute-sql.md
A cockroachdb-execute-sql tool executes ad-hoc SQL statements against a CockroachDB database. This tool is designed for interactive workflows where the SQL query is provided dynamically at runtime, making it ideal for developer assistance and exploratory data analysis.
The tool takes a single sql parameter containing the SQL statement to execute and returns the query results.
Note: This tool is intended for developer assistant workflows with human-in-the-loop and shouldn't be used for production agents. For production use cases with predefined queries, use cockroachdb-sql instead.
{{< compatible-sources >}}
The tool accepts a single runtime parameter:
| Parameter | Type | Description |
|---|---|---|
sql | string | The SQL statement to execute |
sources:
my_cockroachdb:
type: cockroachdb
host: your-cluster.cockroachlabs.cloud
port: "26257"
user: myuser
password: mypassword
database: defaultdb
queryParams:
sslmode: require
tools:
execute_sql:
type: cockroachdb-execute-sql
source: my_cockroachdb
description: Execute any SQL statement against the CockroachDB database
{
"sql": "SELECT * FROM users LIMIT 10"
}
{
"sql": "SELECT category, COUNT(*) as count, SUM(amount) as total FROM expenses GROUP BY category ORDER BY total DESC"
}
{
"sql": "SHOW TABLES"
}
{
"sql": "SHOW COLUMNS FROM expenses"
}
{
"sql": "SHOW REGIONS FROM DATABASE defaultdb"
}
{
"sql": "SHOW ZONE CONFIGURATIONS"
}
{
"sql": "SELECT version()"
}
{
"sql": "SELECT node_id, address, locality, is_live FROM crdb_internal.gossip_nodes"
}
{
"sql": "SELECT range_id, start_key, end_key, replicas, lease_holder FROM crdb_internal.ranges LIMIT 10"
}
{
"sql": "SHOW REGIONS FROM TABLE expenses"
}
| Field | Type | Description |
|---|---|---|
type | string | Must be cockroachdb-execute-sql |
source | string | Name of the CockroachDB source to use |
description | string | Human-readable description for the LLM |
| Field | Type | Description |
|---|---|---|
authRequired | array | List of authentication services required |
This tool is ideal for:
For production use cases, use cockroachdb-sql with parameterized queries.
While this tool can execute any SQL statement, be careful with:
INSERT, UPDATE, DELETE statementsDROP or ALTER statementsAlways use LIMIT clauses when exploring data:
SELECT * FROM large_table LIMIT 100
CockroachDB supports PostgreSQL syntax plus extensions:
-- Show database survival goal
SHOW SURVIVAL GOAL FROM DATABASE defaultdb;
-- View zone configurations
SHOW ZONE CONFIGURATION FOR TABLE expenses;
-- Check table localities
SHOW CREATE TABLE expenses;
Since this tool executes arbitrary SQL, it should only be used with:
Never expose this tool directly to end users without proper authorization controls.
Configure the authRequired field to restrict access:
tools:
execute_sql:
type: cockroachdb-execute-sql
source: my_cockroachdb
description: Execute SQL statements
authRequired:
- my-auth-service
For safer exploration, create read-only database users:
CREATE USER readonly_user;
GRANT SELECT ON DATABASE defaultdb TO readonly_user;
-- View database size
SELECT
table_name,
pg_size_pretty(pg_total_relation_size(table_name::regclass)) AS size
FROM information_schema.tables
WHERE table_schema = 'public'
ORDER BY pg_total_relation_size(table_name::regclass) DESC;
-- Find slow queries
SELECT query, count, mean_latency
FROM crdb_internal.statement_statistics
WHERE mean_latency > INTERVAL '1 second'
ORDER BY mean_latency DESC
LIMIT 10;
-- Find NULL values
SELECT COUNT(*) as null_count
FROM expenses
WHERE description IS NULL OR amount IS NULL;
-- Find duplicates
SELECT user_id, email, COUNT(*) as count
FROM users
GROUP BY user_id, email
HAVING COUNT(*) > 1;
The tool will return descriptive errors for: