supabase-postgres-best-practices/packages/evals/scenarios/team-rls-security-definer.md

Scenario: team-rls-security-definer

Summary

The agent must create a SQL migration for a team-based project management app where users belong to organizations via a membership table. The migration must define tables for organizations, memberships, and projects, then secure them with RLS policies that use a security definer helper function in a private schema to efficiently resolve team membership without per-row joins.

Real-World Justification

Why this is a common and important workflow:

1. Multi-tenant team access is the most-asked RLS question on Supabase -- The official Supabase GitHub has multiple high-engagement discussions about how to write RLS policies that check team/org membership without causing performance issues or security holes.

   • Source: https://github.com/supabase/supabase/discussions/4509
   • Source: https://github.com/supabase/supabase/discussions/811

2. security_definer in public schema is a documented security anti-pattern -- Developers frequently place security_definer functions in the public schema, inadvertently exposing them via the PostgREST API. The Supabase docs and community discussions explicitly warn against this.

   • Source: https://github.com/supabase/supabase/discussions/3269
   • Source: https://supabase.com/docs/guides/database/postgres/row-level-security

3. RLS policy performance with joins is a top pain point -- Naive policies that join against a memberships table execute per-row, causing severe performance degradation. The recommended pattern is a security_definer function that caches results via subselect.

   • Source: https://github.com/orgs/supabase/discussions/1148
   • Source: https://makerkit.dev/blog/tutorials/supabase-rls-best-practices

Skill References Exercised

Which reference files the agent should consult and what each teaches:

Reference File	What It Teaches	What the Agent Should Apply
references/db-rls-mandatory.md	RLS must be enabled on all public tables	Enable RLS on organizations, memberships, and projects
references/db-rls-policy-types.md	PERMISSIVE vs RESTRICTIVE policies	Use PERMISSIVE policies for team OR owner access patterns
references/db-rls-common-mistakes.md	Missing TO clause, user_metadata pitfalls	Always use TO authenticated on all policies
references/db-rls-performance.md	Wrap auth.uid() in SELECT, use security_definer for joins	Use (select auth.uid()) and a private-schema helper function
references/db-security-functions.md	security_definer in private schema with search_path = ''	Create helper function in private schema, revoke default permissions
references/db-schema-auth-fk.md	FK to auth.users with ON DELETE CASCADE	Reference auth.users with cascade on memberships
references/db-schema-timestamps.md	Use timestamptz not timestamp	All time columns use timestamptz
references/db-perf-indexes.md	Index columns used in RLS policies	Index user_id and org_id columns used in policy lookups
references/db-migrations-idempotent.md	IF NOT EXISTS for safe reruns	Idempotent DDL throughout the migration

Workspace Setup

What the workspace starts with before the agent runs:

• Pre-initialized Supabase project (supabase/config.toml exists)
• Empty supabase/migrations/ directory
• The agent creates migration files within this structure

Agent Task (PROMPT.md draft)

The prompt to give the agent. Written as a developer would ask it:

I'm building a project management app where users can belong to multiple organizations. Each organization has projects that all members can view and edit.

Create a SQL migration with:

1. An organizations table (name, slug)
2. A memberships table linking users to organizations with a role column (owner, admin, member)
3. A projects table (name, description, status) belonging to an organization

Set up Row Level Security so:

• Users can only see organizations they belong to
• Users can only see and manage projects in their organizations
• Only org owners can delete projects

The migration should handle the case where a user is deleted from auth.

Evaluation Criteria

What vitest should assert on the agent's output. Each assertion tests a specific quality signal:

#	Test Name	What It Checks	Quality Dimension
1	migration file exists	A .sql file exists in supabase/migrations/	structure
2	creates organizations table	SQL contains CREATE TABLE for organizations	correctness
3	creates memberships table	SQL contains CREATE TABLE for memberships	correctness
4	creates projects table	SQL contains CREATE TABLE for projects	correctness
5	enables RLS on all tables	ALTER TABLE ... ENABLE ROW LEVEL SECURITY for all three tables	security
6	FK to auth.users with ON DELETE CASCADE	memberships references auth.users with cascade	correctness
7	org_id FK on projects	projects references organizations	correctness
8	private schema created	CREATE SCHEMA ... private present	security
9	security_definer helper function	A function in the private schema with SECURITY DEFINER and SET search_path = ''	security
10	policies use (select auth.uid())	Subselect form in all policies referencing auth.uid()	performance
11	policies use TO authenticated	All policies scoped to authenticated role	security
12	index on membership lookup columns	CREATE INDEX on user_id and/or org_id in memberships	performance
13	uses timestamptz	No plain timestamp for time columns	correctness
14	idempotent DDL	Uses IF NOT EXISTS or DROP ... IF EXISTS patterns	idempotency
15	delete policy restricted to owner role	A delete policy on projects checks for owner/admin role	security
16	overall quality score	At least 10/14 best-practice signals present	overall

Reasoning

Step-by-step reasoning for why this scenario is well-designed:

1. Baseline differentiator: An agent without the skill would likely put the security_definer function in the public schema, omit SET search_path = '', use bare auth.uid() instead of the subselect form, write inline joins in policies instead of using a helper function, and possibly forget TO authenticated on some policies. These are all patterns that require specific knowledge of Supabase conventions.

2. Skill value: The skill explicitly teaches: (a) private schema for security_definer functions, (b) SET search_path = '' to prevent injection, (c) (select auth.uid()) for per-statement caching, (d) using security_definer functions to avoid per-row joins in policies, (e) TO authenticated on every policy. This is a scenario where reading 5+ reference files materially improves the output.

3. Testability: Every assertion checks for specific SQL patterns via regex. The private schema, security_definer, search_path, subselect auth.uid(), TO authenticated, indexes, and timestamptz are all reliably detectable in SQL text without runtime execution.

4. Realism: Multi-tenant team-based access control is one of the most common Supabase use cases. The GitHub discussions linked above have hundreds of comments from developers working on exactly this pattern. Project management apps (Notion, Linear, Asana clones) are a canonical example.

Difficulty

Rating: MEDIUM

• Without skill: ~35-50% of assertions expected to pass
• With skill: ~85-95% of assertions expected to pass