tutur3u/platform/tuturuuu-database

Tuturuuu Database

Core Workflow

Read references/database-checklist.md before changing schema, RLS, storage, or generated DB types. Read references/database-api-patterns.md when the work needs the longer database/API pattern catalog that was split out of root AGENTS.md.

Keep migrations additive when possible. Do not run production push commands from an agent checkout. The gated production migration workflow applies eligible migrations after authorized sync, staging success, and the production deployment marker; verify its exact-SHA outcome. Use runtime/API fallbacks when rollout order can vary across environments.

Use normalizeWorkspaceId(wsId) in API routes that accept workspace aliases such as personal. Keep workspace normalization consistent across selector, preview, and final save routes in the same flow.

If the user asks for commits, combine this skill with $tuturuuu-commit. Keep a schema migration and the code that consumes it together when they are one rollout contract; split docs-only or tooling-only follow-through only when it can be reverted independently.

Access And Types

• Prefer importing shared DB aliases from @tuturuuu/types/db.
• Add reusable row shapes to packages/types/src/db.ts instead of duplicating local Pick<Database...> aliases.
• For type-only Supabase usage, import TypedSupabaseClient from @tuturuuu/supabase/types.
• Do not hand-edit generated Supabase type files.
• Avoid generic ReturnType<typeof createAdminClient> aliases when concrete database inference matters.

API And RLS Rules

• Verify workspace membership with the request-scoped client before admin-backed child-resource lookups or mutations.
• After membership is proven, keep protected child-resource validation and writes on a consistent admin-backed, workspace-scoped path when RLS would otherwise block the operation.
• Stamp actor-owned columns explicitly when writing with service-role/admin clients.
• Handle membership lookup errors as 500; return 403 only when the lookup succeeds and no membership row exists.
• For auth.uid()-guarded RPCs, use the authenticated request-scoped client after permission checks instead of a service-role client.

Verification

• Apply local migrations before typegen when schema changes need generated types.
• Run bun sb:typegen after schema changes once the local database reflects the migration.
• Run focused tests for affected API routes, helpers, or pgTAP coverage where available.
• Run bun check:changed before pushing; require bun validate to pass in CI for

the exact commit when TypeScript or root config changed (never run it locally).

• Production migrations run through .github/workflows/supabase-production.yaml

after authorized promotion; do not run bun sb:push or bun sb:linkpush manually. A skipped or failed workflow is a release blocker, not a reason to bypass the gate.