Supabase Project
Covers Supabase client usage, migrations, row security, and generated database types.
Scenario
You maintain a Next.js application using Supabase for:
- PostgreSQL;
- authentication;
- Row Level Security;
- application data.
Some operations use the normal user-scoped Supabase client.
Privileged server-side workflows may use a service-role client.
The team wants coding agents to preserve the security boundary between those two contexts.
Repository Structure
web-app/
├── src/
│ ├── app/
│ ├── features/
│ └── lib/
│ └── supabase/
│ ├── browser.ts
│ ├── server.ts
│ └── admin.ts
├── supabase/
│ └── migrations/
├── tests/
└── AGENTS.md
AGENTS.md
# Project Instructions
## Supabase Clients
- Use the existing browser and server Supabase client helpers.
- Use the admin/service-role client only in trusted server-side code that explicitly requires elevated privileges.
- Never expose the service-role key to browser code.
## Row Level Security
- Treat RLS as part of the application's authorization model.
- Add or update policies when new user-accessible tables or operations require them.
- Do not disable RLS merely to make an application query succeed.
- Test important access rules for both allowed and denied cases.
## Database Changes
- Create schema and policy changes through migrations.
- Do not rely on manual dashboard changes that are absent from repository migrations.
- Preserve existing migration history.
## Data Access
- Prefer user-scoped access when the operation should respect the current user's permissions.
- Use elevated access only when the server workflow intentionally needs to bypass normal user policies.
## Validation
For schema or policy changes:
- apply migrations to the development/test environment;
- test allowed access;
- test denied access;
- run relevant application tests.
What This Does
This establishes an important distinction:
User-scoped Supabase client
↓
RLS applies
↓
User authorization
Service-role client
↓
Elevated database access
↓
Trusted server workflows only
An agent should not solve an RLS failure by simply switching every query to the service-role client.
That would bypass the authorization boundary rather than fix it.
What This Does NOT Do
The file does not say:
- Never use the service role.
There are legitimate server-side workflows that require elevated privileges.
Examples may include:
administrative jobs
trusted background processing
system maintenance
server-side provisioning
The important requirement is that elevated access is intentional and remains server-side.
The file also does not treat frontend checks as a replacement for database authorization.
Why These Instructions Matter
Suppose users should only read their own profile.
A policy might enforce ownership at the database layer.
If an application query fails because of RLS, a dangerous shortcut is:
replace user client
↓
use service-role client
↓
query succeeds
The feature now works, but the authorization model has been bypassed.
The correct question is:
Should this user be allowed to perform this operation?
If yes, the policy or query may need correction.
If no, the failure is expected.
Another risk is schema drift.
A developer may create a policy manually in the Supabase dashboard but forget to add it to migrations.
A fresh environment can then behave differently from production.
Key Decisions
RLS is security, not an inconvenience
Treat policy failures as authorization signals that need investigation.
Elevated clients need a narrow scope
Service-role credentials have powerful access.
Keep them in trusted server code.
Test denial as well as success
Authorization tests should answer both:
Can the correct user access this?
and:
Is the wrong user prevented from accessing this?
Keep database configuration reproducible
Schema and policy changes should live in migrations rather than exist only in a hosted dashboard.
When to Use This Pattern
Use this pattern when:
- Supabase Auth and PostgreSQL are used together;
- RLS protects user data;
- both user-scoped and privileged server access exist;
- database changes are migration-driven;
- authorization mistakes could expose data.
For Supabase applications, RLS guidance is often one of the most important repository-specific instructions.