# Supabase Postgres Best Practices

> Optional service-domain guidance for Postgres and Supabase data layers used by Lynx.js apps. Use when writing, reviewing, or optimizing queries, schema designs, indexes, RLS policies, connection behavior, or database configuration; do not use as UI implementation guidance.

- Skill: `ryne2010/supabase-postgres-best-practices` (Agent Skill, multi-file: 38 files)
- Install (CLI): `npx skillmds@latest add ryne2010/supabase-postgres-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ryne2010/supabase-postgres-best-practices/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: ryne2010 (https://skillmd.com/u/ryne2010)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ryne2010/supabase-postgres-best-practices

---


# Supabase Postgres Best Practices

Use this skill for database and backend/service-layer decisions in Lynx apps. Keep UI composition in `lynx-app-builder` and `lynx-ui-guidance`.


## Lynx host/client safety

When Supabase or Postgres powers a Lynx app surface, keep database and auth boundaries explicit:

- Never put Supabase service-role keys, database passwords, JWT signing secrets, or privileged admin credentials in a Lynx bundle.
- If a Lynx client uses a Supabase anon key, require Row-Level Security policies and verify that the anon role can access only intended rows/actions.
- Keep schema changes, migrations, privileged writes, cron jobs, and server-side aggregation on trusted backend or database surfaces.
- Treat network/offline behavior as host-dependent; record the target host service/network assumptions before promising sync, caching, or background behavior.
- Place generated clients and environment loading according to the consuming app's conventions, and avoid leaking private environment variables into bundled code.
- Route UI composition back to `lynx-app-builder`, official/global ReactLynx guidance, and `lynx-ui-guidance`; this skill owns data, policy, query, and performance guidance only.
- Cite current Supabase/Postgres docs for security, auth, and RLS claims.

## When to Apply

Reference these guidelines when:
- Writing SQL queries or designing schemas
- Implementing indexes or query optimization
- Reviewing database performance issues
- Configuring connection pooling or scaling
- Optimizing for Postgres-specific features
- Working with Row-Level Security (RLS)

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Query Performance | CRITICAL | `query-` |
| 2 | Connection Management | CRITICAL | `conn-` |
| 3 | Security & RLS | CRITICAL | `security-` |
| 4 | Schema Design | HIGH | `schema-` |
| 5 | Concurrency & Locking | MEDIUM-HIGH | `lock-` |
| 6 | Data Access Patterns | MEDIUM | `data-` |
| 7 | Monitoring & Diagnostics | LOW-MEDIUM | `monitor-` |
| 8 | Advanced Features | LOW | `advanced-` |

## How to Use

Read individual rule files for detailed explanations and SQL examples:

```
references/query-missing-indexes.md
references/schema-partial-indexes.md
references/_sections.md
```

Each rule file contains:
- Brief explanation of why it matters
- Incorrect SQL example with explanation
- Correct SQL example with explanation
- Optional EXPLAIN output or metrics
- Additional context and references
- Supabase-specific notes when applicable

## References

- https://www.postgresql.org/docs/current/
- https://supabase.com/docs
- https://wiki.postgresql.org/wiki/Performance_Optimization
- https://supabase.com/docs/guides/database/overview
- https://supabase.com/docs/guides/auth/row-level-security