flutter-supabase-engineering

Flutter Supabase Engineering

Treat Flutter as an untrusted client. Keep the database, Row Level Security, constraints, and server-side policy authoritative.

Start with evidence

Before changing code:

1. Inspect pubspec.yaml, pubspec.lock, Flutter/Dart constraints, and target platforms.
2. Identify the locked supabase_flutter, supabase, postgrest, realtime_client, storage_client, functions_client, and test-package versions.
3. Find every Supabase initialization and client construction; identify the single intended client owner and lifetime.
4. Inspect Auth bootstrap, persistence, deep-link handling, listeners, sign-out, and session-dependent startup behavior.
5. Inspect database migrations, grants, RLS policies, indexes, functions, constraints, and generated/typed models relevant to the task.
6. Inventory query count, selected columns, pagination, N+1 patterns, mutation idempotency, Realtime channels, Storage transfer paths, Edge Functions, retry layers, caching, and offline requirements.
7. Separate current repository behavior from version-sensitive guidance.

The bundled guide was validated on 2026-08-11 against supabase_flutter 2.17.1, supabase 2.16.0, storage_client 2.6.0, functions_client 2.7.1, and mock_supabase_http_client 0.0.3+2. Use the installed packages and their changelogs as the source of truth when versions differ.

Preserve these invariants

• Initialize supabase_flutter once before runApp and reuse its client.
• Do not create a new client, query, Future, stream, Auth listener, or Realtime channel from build().
• Treat the project URL and client publishable/anonymous key as client configuration, not authorization.
• Never ship a service-role key, secret key, database password, JWT signing secret, third-party secret, or privileged credential in Flutter.
• Enable and test RLS for client-accessible data; do not treat hidden UI or a client-supplied user/tenant ID as authorization.
• Keep authorization claims in trusted server-controlled data, not editable user metadata.
• Keep ordinary user-owned CRUD behind direct PostgREST plus RLS when that is the simplest secure boundary.
• Use database functions/RPC for atomic multi-row or transactional SQL work.
• Use Edge Functions for server-only secrets, external integrations, or custom privileged orchestration—not as a generic proxy for every query.
• Select only needed columns, filter on the server, paginate large results, avoid N+1 requests, and index real query and RLS predicates.
• Use .single() only when exactly one row is required; use .maybeSingle() when absence is valid.
• Make retried mutations idempotent at the database or protocol boundary; do not infer safety from a client boolean.
• Keep Realtime subscriptions narrow, persist stream instances, remove unused channels, and never treat Realtime as durable history.
• Reconcile initial query data and Realtime changes deliberately.
• Use private buckets for private data and enforce access with Storage RLS; object paths are organization, not authorization.
• Choose standard versus resumable upload based on object size and network reliability; avoid whole-file memory loads for large objects.
• Do not stack retries across client, repository, and state layers.
• Do not assume Supabase is offline-first; add an explicit local source of truth, sync, conflict, and deletion model only when the product requires it.
• Apply schema and policy migrations through the database workflow, never from the Flutter app.
• Never rely on mocks to prove RLS, grants, constraints, triggers, Auth, Realtime, or real PostgreSQL behavior.