debug-rls

Name: debug-rls
Author: butterbase-ai

533stars40forks

How to install debug-rls?

butterbase-ai/butterbase-skills/debug-rls

$npx -y skills add butterbase-ai/butterbase-skills --skill debug-rls

Installs into the current project.

Summary

Use when users report access denied errors, see wrong data, RLS policies are not working, or when troubleshooting Row-Level Security issues in Butterbase

Files · 1

View on GitHub

SKILL.md

1	# debug-rls
2
3	Systematic methodology for debugging Row-Level Security issues in Butterbase. Uses role simulation (`as_role`/`as_user` parameters) to verify policy behavior without needing real user sessions.
4
5	---
6
7	## 1. Overview
8
9	Row-Level Security (RLS) in Butterbase controls which rows each database role can see or modify. When RLS is misconfigured, users may see no data, too much data, or get unexpected errors on insert. This skill walks through a repeatable four-step process to identify and fix the root cause.
10
11	Key principle: MCP tools default to the service key (`bb_sk_...`), which bypasses all RLS. Always use `as_role`/`as_user` to simulate the role your frontend actually uses.
12
13	---
14
15	## 2. Quick Diagnosis
16
17	Match the symptom your user reports to the most likely cause before diving into the full protocol.
18
19	\| Symptom \| Likely cause \|
20	\|---------\|-------------\|
21	\| User sees no rows \| RLS enabled but no policy for `butterbase_user` role \|
22	\| User sees ALL rows \| RLS not enabled on the table, or request uses service key (`bb_sk_`) \|
23	\| Insert fails with `AUTH_RLS_POLICY_VIOLATION` \| No INSERT policy, or `user_column` not auto-populated \|
24	\| User sees other users' data \| Policy USING expression is wrong, or user isolation not set up \|
25	\| Anonymous user gets 403 \| No policy for `butterbase_anon` role \|
26	\| Works in MCP tools but not from frontend \| MCP uses service key (bypasses RLS); frontend uses end-user JWT \|
27
28	---
29
30	## 3. The Three Roles
31
32	Butterbase automatically assigns a database role based on the auth header of each request. You never create these roles — they are built in.
33
34	\| Auth header \| Database role \| Behavior \|
35	\|-------------\|--------------\|----------\|
36	\| None \| `butterbase_anon` \| Default deny. Only sees rows allowed by explicit anon policies. \|
37	\| Valid end-user JWT \| `butterbase_user` \| `current_user_id()` returns their UUID. Sees rows matching their policies. \|
38	\| API key (`bb_sk_...`) \| `butterbase_service` \| Bypasses ALL RLS. Sees everything. Used by MCP tools and admin operations. \|
39
40	Important: When you call `select_rows` or `insert_row` without `as_role`, you are always running as `butterbase_service`. This means the result tells you nothing about what a real user would see. Use `as_role` to simulate the correct role.
41
42	---
43
44	## 4. Four-Step Debugging Protocol
45
46	Work through these steps in order. Each step narrows down the cause.
47
48	---
49
50	### Step 1: Check if RLS is enabled
51
52	Call `manage_rls` with `action: "list"` for the `app_id`:
53
54	```
55	manage_rls(app_id: "app_abc123", action: "list")
56	```
57
58	Returns `{ policies: [...], tables_with_rls: [...] }`. The `tables_with_rls` array shows which tables have RLS turned on but no policies yet (effective default deny).
59
60	- Look for the table in the response.
61	- If the table has no policies, RLS might not be enabled at all — or it was enabled but no policies were added, which causes a default deny for all non-service roles.
62	- If the table does appear, move to Step 2 to inspect what the policies actually do.
63
64	> A table with RLS enabled but zero policies is inaccessible to `butterbase_anon` and `butterbase_user`. The `butterbase_service` role is unaffected.
65
66	---
67
68	### Step 2: Inspect existing policies
69
70	Read each policy's fields carefully:
71
72	\| Field \| What it means \|
73	\|-------\|--------------\|
74	\| `policyname` \| Human-readable name for the policy \|
75	\| `cmd` \| Which SQL command it applies to: `SELECT`, `INSERT`, `UPDATE`, `DELETE`, or `ALL` \|
76	\| `qual` \| The `USING` expression — filters which rows are visible or affected \|
77	\| `with_check` \| The `WITH CHECK` expression — validates new/updated row data on write \|
78	\| `roles` \| Which database role(s) this policy applies to \|
79
80	Common issues to look for:
81
82	- Policy exists for `butterbase_user` but not `butterbase_anon` (anonymous users blocked)
83	- Policy exists for `SELECT` but not `INSERT` (reads work, writes fail)
84	- `USING` expression references the wrong column (e.g., `owner_id` instead of `user_id`)
85	- Policy covers `ALL` commands but the `WITH CHECK` expression is missing (inserts may fail silently)
86
87	---
88
89	### Step 3: Test as different roles
90
91	Use the `as_role` and `as_user` parameters on `select_rows` and `insert_row` to simulate each role. This is the most direct way to reproduce what a real user experiences.
92
93	```
94	# Test SELECT as an authenticated user
95	select_rows(
96	app_id: "app_abc123",
97	table: "posts",
98	as_role: "user",
99	as_user: "user-uuid-here"
100	)
101
102	# Test SELECT as anonymous
103	select_rows(
104	app_id: "app_abc123",
105	table: "posts",
106	as_role: "anon"
107	)
108
109	# Test INSERT as an authenticated user
110	insert_row(
111	app_id: "app_abc123",
112	table: "posts",
113	data: { title: "Hello" },
114	as_role: "user",
115	as_user: "user-uuid-here"
116	)
117	```
118
119	Compare results between roles:
120
121	\| Scenario \| Expected result \|
122	\|----------\|----------------\|
123	\| No

People who liked this also viewed

6 picks

Type

azure-diagnosticsDebug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deploySkillsJul 2026472k1.3k
systematic-debuggingUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesSkillsJul 2026197k259k
safe-debugRigor Debug / Rigor Audit skill for deep learning research work. Use when the user pastes a traceback, terminal error, CUDA OOM, checkpoint load failure, shape mismatch, NaN loss symptom, or training SkillsMay 2026161k507
explore-runRigor Improve / Rigor Explore run leaf skill for bounded exploratory evidence in deep learning research repositories. Use when the researcher explicitly authorizes exploratory runs such as small-subseSkillsMay 2026161k507
minimal-run-and-auditRigor Run skill for README-first deep learning repo reproduction. Use when the task is specifically to capture or normalize evidence from the selected smoke test or documented inference or evaluation SkillsMay 2026161k507
insforge-debugUse when diagnosing problems in an InsForge project — reactive failures (SDK error object, HTTP 4xx/5xx, gateway timeout 502/503/504, edge function failure or timeout, login/OAuth/auth errors, RLS denSkillsJul 202618k31

debug-rls

533stars40forks

View on GitHub

How to install debug-rls?

butterbase-ai/butterbase-skills/debug-rls

$npx -y skills add butterbase-ai/butterbase-skills --skill debug-rls

Installs into the current project.

Summary

Use when users report access denied errors, see wrong data, RLS policies are not working, or when troubleshooting Row-Level Security issues in Butterbase

Files · 1

View on GitHub

SKILL.md

1	# debug-rls
2
3	Systematic methodology for debugging Row-Level Security issues in Butterbase. Uses role simulation (`as_role`/`as_user` parameters) to verify policy behavior without needing real user sessions.
4
5	---
6
7	## 1. Overview
8
9	Row-Level Security (RLS) in Butterbase controls which rows each database role can see or modify. When RLS is misconfigured, users may see no data, too much data, or get unexpected errors on insert. This skill walks through a repeatable four-step process to identify and fix the root cause.
10
11	Key principle: MCP tools default to the service key (`bb_sk_...`), which bypasses all RLS. Always use `as_role`/`as_user` to simulate the role your frontend actually uses.
12
13	---
14
15	## 2. Quick Diagnosis
16
17	Match the symptom your user reports to the most likely cause before diving into the full protocol.
18
19	\| Symptom \| Likely cause \|
20	\|---------\|-------------\|
21	\| User sees no rows \| RLS enabled but no policy for `butterbase_user` role \|
22	\| User sees ALL rows \| RLS not enabled on the table, or request uses service key (`bb_sk_`) \|
23	\| Insert fails with `AUTH_RLS_POLICY_VIOLATION` \| No INSERT policy, or `user_column` not auto-populated \|
24	\| User sees other users' data \| Policy USING expression is wrong, or user isolation not set up \|
25	\| Anonymous user gets 403 \| No policy for `butterbase_anon` role \|
26	\| Works in MCP tools but not from frontend \| MCP uses service key (bypasses RLS); frontend uses end-user JWT \|
27
28	---
29
30	## 3. The Three Roles
31
32	Butterbase automatically assigns a database role based on the auth header of each request. You never create these roles — they are built in.
33
34	\| Auth header \| Database role \| Behavior \|
35	\|-------------\|--------------\|----------\|
36	\| None \| `butterbase_anon` \| Default deny. Only sees rows allowed by explicit anon policies. \|
37	\| Valid end-user JWT \| `butterbase_user` \| `current_user_id()` returns their UUID. Sees rows matching their policies. \|
38	\| API key (`bb_sk_...`) \| `butterbase_service` \| Bypasses ALL RLS. Sees everything. Used by MCP tools and admin operations. \|
39
40	Important: When you call `select_rows` or `insert_row` without `as_role`, you are always running as `butterbase_service`. This means the result tells you nothing about what a real user would see. Use `as_role` to simulate the correct role.
41
42	---
43
44	## 4. Four-Step Debugging Protocol
45
46	Work through these steps in order. Each step narrows down the cause.
47
48	---
49
50	### Step 1: Check if RLS is enabled
51
52	Call `manage_rls` with `action: "list"` for the `app_id`:
53
54	```
55	manage_rls(app_id: "app_abc123", action: "list")
56	```
57
58	Returns `{ policies: [...], tables_with_rls: [...] }`. The `tables_with_rls` array shows which tables have RLS turned on but no policies yet (effective default deny).
59
60	- Look for the table in the response.
61	- If the table has no policies, RLS might not be enabled at all — or it was enabled but no policies were added, which causes a default deny for all non-service roles.
62	- If the table does appear, move to Step 2 to inspect what the policies actually do.
63
64	> A table with RLS enabled but zero policies is inaccessible to `butterbase_anon` and `butterbase_user`. The `butterbase_service` role is unaffected.
65
66	---
67
68	### Step 2: Inspect existing policies
69
70	Read each policy's fields carefully:
71
72	\| Field \| What it means \|
73	\|-------\|--------------\|
74	\| `policyname` \| Human-readable name for the policy \|
75	\| `cmd` \| Which SQL command it applies to: `SELECT`, `INSERT`, `UPDATE`, `DELETE`, or `ALL` \|
76	\| `qual` \| The `USING` expression — filters which rows are visible or affected \|
77	\| `with_check` \| The `WITH CHECK` expression — validates new/updated row data on write \|
78	\| `roles` \| Which database role(s) this policy applies to \|
79
80	Common issues to look for:
81
82	- Policy exists for `butterbase_user` but not `butterbase_anon` (anonymous users blocked)
83	- Policy exists for `SELECT` but not `INSERT` (reads work, writes fail)
84	- `USING` expression references the wrong column (e.g., `owner_id` instead of `user_id`)
85	- Policy covers `ALL` commands but the `WITH CHECK` expression is missing (inserts may fail silently)
86
87	---
88
89	### Step 3: Test as different roles
90
91	Use the `as_role` and `as_user` parameters on `select_rows` and `insert_row` to simulate each role. This is the most direct way to reproduce what a real user experiences.
92
93	```
94	# Test SELECT as an authenticated user
95	select_rows(
96	app_id: "app_abc123",
97	table: "posts",
98	as_role: "user",
99	as_user: "user-uuid-here"
100	)
101
102	# Test SELECT as anonymous
103	select_rows(
104	app_id: "app_abc123",
105	table: "posts",
106	as_role: "anon"
107	)
108
109	# Test INSERT as an authenticated user
110	insert_row(
111	app_id: "app_abc123",
112	table: "posts",
113	data: { title: "Hello" },
114	as_role: "user",
115	as_user: "user-uuid-here"
116	)
117	```
118
119	Compare results between roles:
120
121	\| Scenario \| Expected result \|
122	\|----------\|----------------\|
123	\| No

People who liked this also viewed

6 picks

Type