Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Version: 1.0.0
Last Updated: 2026-05-13
Audience: Developers and AI agents applying schema changes through Lovable + Supabase.

​
Why this exists

Lovable can apply schema changes directly to hosted DEV. Those changes do not automatically create local migration files, so drift can accumulate unless we capture it promptly. This workflow keeps hosted DEV, supabase/migrations/, and optional declarative files aligned.

​
Required workflow after Lovable schema edits

  1. Run drift capture:
npm run db:pull-from-dev -- --name <descriptive_slug>
  1. Review the generated migration in supabase/migrations/:
    • verify no unintended DROP or destructive DDL
    • confirm RLS/policy changes follow constitution requirements
    • confirm lane expectations from docs/development/supabase/MIGRATION_LANES.md
  2. Validate locally: 
npx supabase start
npx supabase db reset
npm run validate-migration -- --latest
npm run test:rls
  1. If declarative schema is bootstrapped, refresh it:
npm run db:schemas:export
npm run db:schemas:lint
  1. Commit migration (and declarative updates when present) in the same PR.

​
Guardrails

  • supabase/migrations/*.sql is the only deployment/promotions source of truth.
  • Never promote Lovable-only hosted changes without an accompanying migration file.
  • Do not include tenant/demo data in migrations.
  • If db:pull-from-dev returns no diff, do not create a no-op migration.
  • For partitioned-table changes, use the two-phase safety pattern from ADR-020:
    • phase 1 = shadow partition tables + sync triggers (no cutover),
    • phase 2 = explicit backfill/parity checks/cutover in an approved window.

​
Troubleshooting

  • Missing required env var: SUPABASE_DEV_PROJECT_ID
    Set SUPABASE_DEV_PROJECT_ID (normally zkgxozahyczcnzpwhbbf).
  • Missing required env var: SUPABASE_ACCESS_TOKEN
    Export a Supabase personal access token with project link permissions.
  • Catalog/doc refresh missing DB credentials
    Set SUPABASE_DEV_DB_PASSWORD (or SUPABASE_DEV_DB_URL) before running hosted catalog export scripts.