Row-Level Security
Row-Level Security (RLS) restricts the rows returned by a query based on the user's assigned permissions. When enabled, every query executed by the plugin is automatically filtered by the policies you define — users only see data they are authorised to access, regardless of how they phrase their question.
Navigate to Actions → Plugins → SQL Database Reader → Security in the agent sidebar.
When to Use RLS
Enable RLS when:
- Different users should see different subsets of the same data, for example sales reps seeing only their region's orders.
- Sensitive records such as salaries, personal data, or financial details must be restricted by role.
- A multi-tenant database shares tables across accounts and rows must be isolated per customer.
If all authenticated users can see all data, leave RLS disabled.
Enabling RLS
Toggle Require Policies to on. Once enabled, every query will have the matching policy filters applied automatically before execution.
If a user's permissions do not match any configured policy, the query returns no rows.
Permission Policies
A permission policy is a named set of rules that applies to users who carry a specific permission. Create one policy for each distinct access level in your system.
Example policies:
| Permission | Intended scope |
|---|---|
sales | Only sees orders and customers in their assigned region |
manager | Sees all orders but not cost or margin columns |
finance | Sees all revenue and cost data without restriction |
admin | No restrictions — sees everything |
Table Scope Policies
Within a permission policy, a table scope policy defines which rows are visible in a specific table for users with that permission.
Column Conditions
Simple equality filters applied to one or more columns. All conditions within a table scope policy are combined with AND.
Example: Restrict the orders table to active orders in the user's region.
| Column | Value |
|---|---|
status | active |
region | {MESSENGER_ACCOUNT_CODE()} |
At query time this produces:
WHERE status = 'active' AND region = 'APAC'
SQL Expressions
For complex filtering, write a raw SQL expression. This expression is appended to the query's WHERE clause with AND and may reference any column in the table or use subqueries.
Example:
sales_region = (SELECT region FROM sales_reps WHERE user_id = '{USER_ID()}')
Column conditions and a SQL expression can be combined on the same table — all are applied together.
User Context Placeholders
Use these placeholders inside column condition values and SQL expressions. They are replaced at query execution time with the authenticated user's actual session values.
| Placeholder | Replaced with |
|---|---|
{USER_ID()} | The authenticated user's ID |
{USER_EMAIL()} | The authenticated user's email address |
{AGENT_ID()} | The ID of the agent handling the conversation |
{MESSENGER_ACCOUNT_CODE()} | The messenger account code, e.g. a WhatsApp account identifier |
{MESSENGER_PRODUCT()} | The messenger product type, e.g. whatsapp or instagram |
Example: Multi-Region Sales Access
Scenario: Sales reps see only orders from their assigned region. Managers see all orders.
Policy: sales
Table: orders
| Column condition | Value |
|---|---|
region | {MESSENGER_ACCOUNT_CODE()} |
Policy: manager
No table scope policies — users with this permission see all rows with no WHERE clause added.
When a user with sales permission asks "Show me today's orders", the generated SQL includes:
WHERE orders.region = 'APAC' -- substituted from MESSENGER_ACCOUNT_CODE()
When a user with manager permission asks the same question, no WHERE clause restriction is added.
Testing RLS
Use the query testing panel to simulate different permission sets. Enter permission names in the User Permissions field and observe how the translated SQL changes. Combine this with the User Context fields to simulate placeholder substitution at the same time.
Related Pages
- Testing Queries — simulate RLS with different user permissions before going live.
- Configure Tables and Columns — select which columns are visible before applying policies.
- SQL Database Reader Overview