DocsTesting and Enforcement
Preview how policies transform SQL queries before enabling enforcement, and control when transformations are applied to a data source.
The Security tab on each data source provides tools to validate your policy, preview query transformations, and control whether the policy is actively enforced. Use these tools to verify your rules before they affect real queries.
Real-Time Validation
As you edit the Policy YAML in the editor, Kaelio validates the document continuously. A brief spinner appears while validation runs, then one of two indicators:
- Green checkmark -- The YAML is valid and the policy structure is correct. You can save or test the policy.
- Red X with error details -- The YAML has a syntax error or an invalid field. The error message describes what went wrong. You cannot save until all errors are resolved.
Validation runs automatically after you stop typing (with a short delay), so there is no need to trigger it manually. If the editor shows a red X, read the error message and correct the YAML before proceeding.
Validation checks both YAML syntax and policy schema correctness -- missing required fields, invalid types, and unrecognized keys are all caught before you save.
Testing with SQL Preview
The SQL Preview tool lets you simulate how your policy transforms a query for a specific user, without enabling enforcement or running anything against your database.
Open the test dialog
Navigate to the data source's Security tab and click the Test button. This opens the "Test SQL Policy" dialog.
Enter a SQL query and user properties
The dialog has two fields:
- Original SQL Query -- Type or paste the SQL you want to test. A default example (
SELECT * FROM users WHERE id = 1) is provided. - User Properties -- Enter simple YAML key-value pairs representing the user's security properties. For example:
tenant_id: "acme"
department: "sales"These properties are used to evaluate conditions and fill template variables like {tenant_id} in row filters.
Run the transformation
Click Transform SQL to apply the policy against your query with the given user properties. The results appear below the form.
Reading the Results
After clicking Transform SQL, the dialog displays several sections:
Transformed SQL
A read-only code editor showing the final SQL query after the policy has been applied. This is exactly what would be sent to the database if enforcement were enabled.
Restrictions Applied
A list of badges describing each transformation that was applied. Each badge shows a type, the affected table, and a details summary. The restriction types are:
| Badge | Meaning |
|---|---|
table_blocked | The query was rejected because it references a blocked table |
table_condition_denied | A conditional table rule denied access based on the user's properties |
column_filtered | One or more columns were removed from the SELECT clause |
row_filter_applied | A WHERE clause was injected to restrict visible rows |
row_filter_denied | The row filter could not be applied (e.g., a required template variable is missing) |
Error Message
If the query would be completely blocked (for example, it references a table the user cannot access), an error message appears with a red background explaining why.
Execution Time
The time the transformation took to process. This gives you an indication of policy evaluation performance.
Example Test Scenarios
Here are a few common scenarios to try when verifying a new policy.
Table blocking
Enter a query that references a table your policy blocks, such as SELECT * FROM audit_logs. The result should show a table_blocked badge and an error message indicating access is denied.
Column filtering
Enter a query that selects restricted columns explicitly:
SELECT id, password_hash FROM usersThe transformed SQL should show the password_hash column removed, and a column_filtered badge with details like "Removed restricted columns: password_hash".
Row filters
Enter a broad query against a table with a row filter rule:
SELECT * FROM ordersWith user properties set to tenant_id: "acme", the transformed SQL should include a WHERE tenant_id = 'acme' clause, and a row_filter_applied badge should appear.
To test how different users experience the policy, change the user properties between runs. See User Security Properties for how to configure these properties on actual user accounts.
Enabling Enforcement
Testing previews transformations but does not affect real queries. To activate the policy on a data source:
Toggle enforcement on
On the Security tab, switch the Enforce Policy toggle to the on position. The toggle is located in the header area of the policy editor.
Save the policy
Click Save to persist both the policy YAML and the enforcement state. The Save button is disabled if there are validation errors or no unsaved changes.
Verify queries are transformed
Once saved, all queries to this data source are transformed according to the policy. This includes queries written by users directly and queries generated by AI.
To disable enforcement without deleting the policy, toggle Enforce Policy off and save. Your policy YAML remains intact and can be re-enabled at any time.
Important Notes
- You must save the policy for any changes to take effect. Editing the YAML or toggling enforcement without saving does not change the active policy.
- Enforcement applies to all users querying the data source, including AI-generated queries. There are no exemptions.
- The Enforce Policy toggle is per data source. Enabling enforcement on one data source does not affect others.
Related
- Policy YAML Reference -- full schema for writing policies
- Table Access Rules -- control which tables users can query
- Column Filtering Rules -- hide sensitive columns from results
- User Security Properties -- configure per-user properties for conditions and template variables