Skip to content

A full-featured CRM built with React, shadcn/ui, and Supabase.

Review

fzaninotto08e651f69cc0
diff --git a/AGENTS.md b/AGENTS.md
index 8f84cf6e..8cea9ad8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -30,7 +30,7 @@ make build # Build production bundle (runs tsc + vite build)
### Database Management
-The database schema is defined declaratively in `supabase/schemas/` (source of truth). Never edit `supabase/migrations/` directly. Function definitions in `02_functions.sql` must use the exact `pg_dump` format (run `npx supabase db dump --local --schema public`) to avoid phantom diffs.
+The database schema is defined declaratively in `supabase/schemas/` (source of truth). Migrations in `supabase/migrations/` are auto-generated and should generally not be edited directly — but sometimes manual adjustment is needed (e.g., replacing a DROP+CREATE with an ALTER TABLE RENAME for column renames). Function definitions in `02_functions.sql` must use the exact `pg_dump` format (run `npx supabase db dump --local --schema public`) to avoid phantom diffs.
```bash
npx supabase db diff --local -f <name> # Generate migration from schema changes
diff --git a/doc/src/content/docs/developers/migrations.mdx b/doc/src/content/docs/developers/migrations.mdx
index 9684907d..b05bb353 100644
--- a/doc/src/content/docs/developers/migrations.mdx
+++ b/doc/src/content/docs/developers/migrations.mdx
@@ -22,7 +22,7 @@ The `supabase/schemas/` directory contains the **source of truth** for the datab
Files are numbered to control load order (tables must exist before functions that reference them).
:::caution
-Never edit migration files in `supabase/migrations/` directly. They are auto-generated from the schema files and should be treated as build artifacts.
+Migration files in `supabase/migrations/` are auto-generated from the schema files. In most cases, you should not edit them directly. However, there are exceptions: for example, `db diff` may generate a DROP + CREATE for a column rename instead of an ALTER TABLE RENAME. In such cases, manually edit the migration to use the correct statement, while keeping it coherent with the schema files.
:::
## Working With a Local Database
@@ -41,13 +41,15 @@ npx supabase db diff --local -f <migration_name>
This compares the schema files against the local database and generates a migration file in `supabase/migrations/`.
-3. **Apply the migration** locally:
+3. **Review the generated migration** in `supabase/migrations/`. In most cases it will be correct, but sometimes you may need to adjust it. For example, if you renamed a column, `db diff` may generate a DROP + CREATE instead of an `ALTER TABLE ... RENAME COLUMN`. Edit the migration file to use the correct statement, while keeping it coherent with the schema file.
+
+4. **Apply the migration** locally:
```sh
npx supabase migration up --local
```
-4. **Verify** the diff is clean (no remaining differences):
+5. **Verify** the diff is clean (no remaining differences):
```sh
npx supabase db diff --local