Testing Queries
The query testing panel lets you validate how the plugin generates and executes SQL before exposing the agent to end users. You can translate a natural language prompt to SQL, simulate row-level security, substitute user context placeholders, and execute queries with a controlled row limit.
Navigate to Actions → Plugins → SQL Database Reader → Test in the agent sidebar.
The testing panel requires the plugin configuration to be saved first. Make sure you have completed the schema configuration and function settings.
Translating a Question to SQL
Enter a natural language question in the Prompt field and click Translate. The plugin uses the AI model to convert the question into a SQL query based on your current schema and data dictionary.
Example prompts:
Show me the top 10 customers by total revenue this monthHow many orders currently have a status of pending?List all products where stock is below 20 units
The panel returns the generated SQL and the processing time in milliseconds. Review the SQL to verify:
- The correct tables and columns are referenced.
- JOIN conditions are correct, especially if virtual foreign keys are involved.
- Filter conditions match the intent of the question.
If the generated SQL is incorrect, go back and improve your table and column descriptions in the schema configuration.
Simulating Row-Level Security
If your configuration has row-level security enabled, you can simulate how different users would see results by entering permissions in the User Permissions field.
Enter one or more permission names that represent the user's roles, for example sales or manager. The plugin applies the matching policies and shows you the WHERE clause that will be injected into the query.
Example: If the policy for sales restricts the orders table to rows where region = 'APAC', the translated SQL will include:
WHERE orders.region = 'APAC'
Use this to confirm that policies restrict data correctly before deployment.
Simulating User Context
Placeholders like {USER_ID()} and {USER_EMAIL()} are substituted at query execution time with real values from the authenticated session. In the testing panel, you can provide mock values to simulate this substitution.
| Placeholder | Field | Example value |
|---|---|---|
{USER_ID()} | User ID | user-42 |
{USER_EMAIL()} | User email | arjuna@example.com |
{AGENT_ID()} | Agent ID | agent-crm |
{MESSENGER_ACCOUNT_CODE()} | Messenger account code | wa-001 |
{MESSENGER_PRODUCT()} | Messenger product type | whatsapp |
Executing a Query
After translating, click Execute to run the SQL against the live database. Set the Row Limit between 1 and 10 to avoid returning large result sets during testing.
The panel returns:
- The executed query after any RLS and placeholder substitution
- The result rows as a formatted table
- Row count and execution time
Execution in the testing panel is capped at 10 rows. In production, the per-provider row cap of 10,000 rows applies.
Interpreting Errors
| Error | What it means |
|---|---|
| Translation failed | The AI could not generate valid SQL. Improve schema descriptions or clarify the prompt. |
| Table or column not found | A name in the generated SQL does not exist in the database. Check the schema configuration. |
| Query timeout | The query exceeded 30 seconds. Add filters or ensure database indexes exist for the queried columns. |
| Permission denied | The database user lacks read access to the queried table. |
Related Pages
- Configure Tables and Columns — improve descriptions to get better SQL generation.
- Virtual Foreign Keys — verify JOIN generation after defining FK relationships.
- Row-Level Security — test how policies affect generated queries.
- SQL Database Reader Overview