Query Your Database in Plain English: FoundryDB's AI Query Console

Most database dashboards give you a SQL editor and wish you luck. That works fine when you remember the exact name of the pg_stat_user_tables view or the difference between information_schema.TABLES in MySQL versus PostgreSQL. For everyone else, there is the AI Query Console.

FoundryDB's AI Query Console lets you type a question in plain English, translates it to a database-native SQL query using Claude, and executes it against your running service. The entire flow is read-only by design. You cannot accidentally drop a table by asking a question.

How It Works

The AI Query Console is a two-step pipeline: translate, then execute. These are separate API calls, which means you always see the generated SQL before anything runs against your database. You can review it, edit it, or discard it entirely.

Step 1: Translate

You send a natural language question to the translate endpoint. FoundryDB passes your question to Claude along with the database dialect (PostgreSQL or MySQL) and the engine version. Claude generates a read-only SQL query and a brief explanation of what it does.

curl -u user:password -X POST \
  https://api.foundrydb.com/managed-services/{service-id}/ai-query/translate \
  -H "Content-Type: application/json" \
  -d '{"question": "Show the top 10 largest tables by size"}'

The response includes the generated SQL, an explanation, and the database dialect used:

{
  "sql": "SELECT tablename, pg_total_relation_size(quote_ident(tablename)) AS size FROM pg_tables WHERE schemaname = 'public' ORDER BY size DESC LIMIT 10",
  "explanation": "Lists the 10 largest tables in the public schema",
  "database_type": "postgresql"
}

If Claude generates a query that violates safety rules, the sql field is returned empty and a warning field explains why the query was blocked.

Step 2: Execute

Once you have the SQL (or have edited it to your liking), you send it to the execute endpoint:

curl -u user:password -X POST \
  https://api.foundrydb.com/managed-services/{service-id}/ai-query/execute \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT tablename, pg_total_relation_size(quote_ident(tablename)) AS size FROM pg_tables WHERE schemaname = '\''public'\'' ORDER BY size DESC LIMIT 10"}'

The response contains column names, row data, the row count, and execution time in milliseconds:

{
  "columns": ["tablename", "size"],
  "rows": [
    ["orders", 2147483648],
    ["events", 1073741824],
    ["users", 536870912]
  ],
  "row_count": 3,
  "execution_ms": 15,
  "truncated": false
}

Results are capped at 1,000 rows. If the result set exceeds that limit, truncated is set to true.

Safety Guardrails

The AI Query Console enforces read-only access at three layers, so no single point of failure can allow a write operation.

1. Prompt-level constraints. The system prompt instructs Claude to generate only SELECT, SHOW, DESCRIBE, and EXPLAIN statements. It explicitly forbids INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE, and multi-statement queries.

2. Server-side SQL validation. Before execution, the controller parses the SQL and rejects anything that is not a recognized read-only statement. It strips comments, blocks semicolons (preventing multi-statement injection), and scans for dangerous keywords even inside subqueries and CTEs.

3. Database-level read-only mode. The connection to your database is opened in read-only transaction mode. On PostgreSQL, this sets default_transaction_read_only = ON and a 30-second statement_timeout. On MySQL, it uses SET SESSION TRANSACTION READ ONLY and max_execution_time = 30000. Even if a write query somehow passes the first two layers, the database itself rejects it.

These layers are independent. A failure at the AI level is caught by validation. A failure at validation is caught by the database. Your data stays safe.

Supported Database Engines

Engine	Translate	Execute	Dialect-Aware System Catalogs
PostgreSQL	Yes	Yes	pg_stat_statements, pg_stat_user_tables, pg_stat_activity, information_schema, pg_indexes, pg_class, pg_namespace
MySQL	Yes	Yes	information_schema, performance_schema, mysql system database

The translate endpoint generates dialect-correct SQL based on your service's engine type and version. If you have a PostgreSQL 17 service, it generates PostgreSQL 17-compatible queries. If you have a MySQL 8.4 service, it generates MySQL 8.4-compatible queries. You do not need to specify the dialect yourself.

Schema Context Awareness

When Claude generates SQL for your service, it knows the database dialect and version. This means it can reference engine-specific system views accurately. Ask a PostgreSQL service about slow queries, and it queries pg_stat_statements. Ask a MySQL service the same question, and it queries performance_schema.

The translate endpoint also accepts an optional database_name parameter. By default, queries run against defaultdb (the default database created for every FoundryDB service). If you want to query a different database on the same service, pass it explicitly:

curl -u user:password -X POST \
  https://api.foundrydb.com/managed-services/{service-id}/ai-query/translate \
  -H "Content-Type: application/json" \
  -d '{"question": "How many rows are in each table?", "database_name": "analytics"}'

The Dashboard Experience

The AI Query Console is built into the FoundryDB dashboard as a tab on every PostgreSQL and MySQL service. The workflow is straightforward:

1. Type a question in the text field (or click one of the suggested examples).
2. Click Generate SQL (or press Cmd+Enter / Ctrl+Enter).
3. Review the generated SQL. Edit it if you want.
4. Click Run Query to execute.
5. View results in a paginated table with column headers, row counts, and execution time.

The console tracks a local query history (up to 20 entries) so you can revisit previous questions without retyping them. If you modify the generated SQL before executing, a "Modified" badge appears so you can tell at a glance whether the query is the original or your edited version.

Example Questions to Try

For PostgreSQL services:

• "Show the top 10 largest tables by size"
• "List active connections grouped by user"
• "Show slow queries from the last hour"
• "What indexes are unused?"
• "Show table row counts for all user tables"

For MySQL services:

• "Show the top 10 largest tables by size"
• "List active connections grouped by user"
• "Show the most frequently run queries"
• "What indexes exist on each table?"
• "Show table row counts for all tables"

API Reference

Both endpoints require authentication and a running service.

Endpoint	Method	Description
/managed-services/{serviceId}/ai-query/translate	POST	Translate natural language to SQL
/managed-services/{serviceId}/ai-query/execute	POST	Execute a read-only SQL query

Translate request body:

Field	Type	Required	Description
question	string	Yes	Natural language question (max 1,000 characters)
database_name	string	No	Target database name (defaults to service default)

Execute request body:

Field	Type	Required	Description
sql	string	Yes	SQL query to execute (must be read-only)
database_name	string	No	Target database name

Execute response:

Field	Type	Description
columns	string[]	Column names from the result set
rows	any[][]	Row data (each row is an array of values)
row_count	integer	Number of rows returned
execution_ms	integer	Query execution time in milliseconds
truncated	boolean	True if results were capped at 1,000 rows

Error Handling

The API returns RFC 7807 problem details for errors:

• 400: Empty question, question exceeding 1,000 characters, unsupported database type, service not in Running state, or blocked SQL.
• 404: Service not found or access denied.
• 501: AI Query feature not configured (missing Anthropic API key). Contact your administrator.

Get Started

The AI Query Console is available on every PostgreSQL and MySQL service in FoundryDB. Open your service in the dashboard, navigate to the AI Query tab, and ask your first question.

If you prefer the API, check out the full AI Query documentation for request and response schemas, or explore the feature with the FoundryDB CLI.

Don't have a FoundryDB account yet? Sign up and have a production-ready PostgreSQL or MySQL service running in under five minutes.