flow-supabase-project

Files (3)

• SKILL.md
• nested-rls-pattern.md · references/
• migration.sql.template · templates/

SKILL.md (first lines)

# Goal

Apply this project's local Supabase conventions: npm script aliases,
the generated types path, and the `handle_updated_at` trigger rule.
Defer generic Supabase guidance (RLS strategy, security, performance,
extensions, Auth/Realtime/Storage) to `supabase:supabase`.

# When to Use

- Adding a column, table, or constraint and need to regenerate
  `src/lib/database/types.ts`.
- Writing a new migration in `supabase/migrations/` and need the
  project's migration template or `handle_updated_at` trigger.
- Resetting the local DB via `npm run db:reset:local`.
- Diagnosing the `auth.sessions` seed failure after a Supabase CLI
  upgrade.

# When NOT to Use

- Generic Supabase questions (RLS strategy, security audits, Postgres
  extensions, Auth, Edge Functions, Realtime, Storage, Vectors, Cron,
  Queues) — defer to `supabase:supabase`.
- Non-Postgres database layers (Prisma, Drizzle, TypeORM, Mongoose,
  MySQL, SQLite).
- Frontend UI changes — defer to `tailwind-shadcn` or `svelte`.

# Project paths

- Migrations directory: `supabase/migrations/`
- Generated types: `src/lib/database/types.ts` (regenerated by
  `npm run db:types`).
- Domain consumers of DB types: `src/lib/domain/`.
- Migration template: `.claude/skills/flow-supabase-project/templates/migration.sql.template`.
- Nested-RLS pattern (child tables without `user_id`):
  `references/nested-rls-pattern.md`.

# npm script aliases

| Command                           | Purpose                                                            |
| --------------------------------- | ------------------------------------------------------------------ |
| `npm run db:start`                | Start local Supabase (loads `.env`)                                |
| `npm run db:stop`                 | Stop local Supabase                                                |
| `npm run db:restart`              | Stop + start local Supabase                                        |
| `npm run db:types`                | Regenerate TypeScript types from local DB                          |
| `npm run db:migration:new <desc>` | Create timestamped migration file                                  |
| `npm run db:migration:up:local`   | Apply pending migrations locally                                   |
| `npm run db:reset:local`          | **Destructive** — reset local DB and reapply all migrations + seed |
| `npm run db:status`               | List migration status                                              |
| `npm run db:diff`                 | Auto-generate migration SQL from schema changes made in Studio     |
| `npm run db:studio`               | Open Supabase Studio in browser                                    |

Use these aliases instead of raw `supabase` CLI calls — they load
`.env` and pin the types output path.

# `handle_updated_at` trigger rule

All tables with an `updated_at` column **must** have an auto-update
trigger using the shared `handle_updated_at()` function (defined in
an early shared-functions migration):

```sql
CREATE TRIGGER update_<table_name>_updated_at
    BEFORE UPDATE ON <table_name>
    FOR EACH ROW
    EXECUTE FUNCTION public.handle_updated_at();
```

Defer to `supabase:supabase` for generic RLS, indexing, and
performance guidance.

# Workflow

1. `npm run db:migration:new <desc>` — generate the timestamped file.
2. Use `templates/migration.sql.template` as the starting skeleton.
   Alternative: `npm run db:diff` after editing in Studio.
3. Apply: `npm run db:migration:up:local`. Status: `npm run db:status`.
4. Regenerate types: `npm run db:types`. Confirm new types appear in
   `src/lib/database/types.ts`.
5. Update consumers under `src/lib/domain/` if the schema change
   affects them.

# Troubleshooting

**`auth.sessions` seed fails after Supabase CLI upgrade:**

The `auth.sessions` schema may change between CLI versions (e.g., the
`scopes` column). Remove `INSERT INTO auth.sessions` statements from
`supabase/seed.sql`, or run `supabase db reset --local --no-seed` if
session data isn't needed.

# Verification

- Migration applies cleanly via `npm run db:migration:up:local` (or
  `npm run db:reset:local` with user approval).
- `npm run db:types` regenerates `src/lib/database/types.ts` without
  errors.
- `npm run check` and `npm run lint` pass with no type errors in
  `src/lib/domain/`.
- `updated_at` triggers are present for all tables with an
  `updated_at` column.

# Constraints

- NEVER run `npm run db:reset:local` without explicit user approval —
  it destroys all local data.
- NEVER modify `src/lib/database/types.ts` manually — it is
  regenerated by `npm run db:types`.
- NEVER omit `handle_updated_at` triggers on tables with an
  `updated_at` column.
- Use the npm script aliases above instead of raw `supabase` CLI
  calls.

From gavingolden/flow, MIT.

More from gavingolden/flow