mirror of
https://github.com/supabase/supabase.git
synced 2026-10-14 05:39:11 +03:00
e357ec8f9f
## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Docs update. ## What is the current behavior? Linear: [CLI-1618](https://linear.app/supabase/issue/CLI-1618/update-cli-workflow-docs-for-pg-delta-default-diffing) Four docs pages lag the shipped CLI behavior now that `pg-delta` is the default diff engine for projects created by a recent `supabase init`: - **CLI workflows** claims `db diff` compares `supabase/schemas/` against migrations. Under `pg-delta`, declarative files are never the `db diff` baseline (and `[db.migrations].schema_paths` no longer changes it) — the declarative flow goes through `supabase db schema declarative sync`. The cleanup guidance describes `migra`-era output. - **Declarative database schemas** teaches the old `db diff -f` + `schema_paths` flow throughout, and its known-caveats list is the `migra` issue list. - **Managing environments** still presents `--use-migra` as an "experimental flag" for a "more concise" diff — inverted now. - **Backup and restore (migrating within Supabase)** and the CLI workflows guide both steer users to `db diff`/`db pull` with `--schema auth,storage`. Under `pg-delta`, `--schema` layers an extra exclude policy on top of the Supabase profile: it can only narrow a diff, never re-include managed schemas, and managed-schema selections can even fail closed (e.g. `--schema auth` when a trigger function lives in `public`). Unfiltered diffs are the supported path. ## What is the new behavior? All claims verified against the CLI source at current `develop` — including supabase/cli#6300, which upgraded the engine to `@supabase/pg-delta` 1.0.0-alpha.46 — against the pinned pg-delta package source (profile rules, format defaults, coverage doc), and against a live dogfood run of the documented workflows on `develop` `38f31b4` (two OSS corpus projects, warm shadow cache). - **`cli-workflows.mdx`**: adds a "Which diff engine you're on" note (`pg-delta` for new `supabase init` projects, `migra` for existing ones until they opt in by adding `[experimental.pgdelta] enabled = true`; per-run fallbacks `--use-migra` on `db diff` / `--diff-engine migra` on `db pull`); corrects `db pull` and `db diff` mechanics (shadow built from migrations vs. live database; the baseline history record is offered, not unconditional); switches the declarative flow to `supabase db schema declarative sync`; reworks the cleanup section around pg-delta output (uppercase keywords at max width 180, `format_options`, per-unit migration files with numeric segment suffixes, the `-- pg-delta: transaction=false` directive on genuinely non-transactional files, engine-neutral grant/revoke review guidance, coverage warnings + `--strict-coverage`); documents what pg-delta captures in managed schemas (user triggers, RLS policies on `auth` tables and on `storage.objects`/`storage.buckets`/`realtime.messages`) versus what it doesn't; adds key-command rows for the declarative commands and troubleshooting entries (`db pull` non-zero exit when in sync, the `schema_paths` warning, `PGDELTA_DEBUG=1` bundles under `supabase/.temp/pgdelta/v2/debug/`). - **`declarative-database-schemas.mdx`**: swaps `db diff -f` for `db schema declarative sync -f` throughout; replaces lexicographic/`schema_paths` ordering guidance with automatic dependency ordering and the `generate` export layout (`_cluster/`, reserved `_custom/`); bootstraps from production via `db schema declarative generate --linked` (explicit target + `--overwrite` in scripts) and refreshes via `db pull --declarative`; rewrites known caveats for pg-delta (DML including storage buckets, untracked object kinds + the `_custom/` escape hatch, managed schemas, extension-managed objects, and the two gates when adopting an existing schema tree: `[experimental.webhooks]` for `pg_net` migrations and declaring the tree's extensions) keeping the `migra` workflow and issue list under a legacy section for projects that haven't enabled it. - **`managing-environments.mdx`**: frames the verbose grant sample as legacy-engine output, notes that generated migrations can include grant statements on any engine, describes `--use-migra` as a single-run fallback, and adds a `db diff --strict-coverage` CI step. - **`backup-restore.mdx`**: replaces `db diff --linked --schema auth,storage` with a plain `db diff --linked` on `pg-delta` (keeping the `--schema auth,storage` form for the legacy engine) and explains what the engine includes (user triggers on managed tables, user RLS policies on `auth`, `storage.objects`/`storage.buckets`/`realtime.messages`) and what must be recreated manually. - **New `diff-engines.mdx` page** (from #49889): the single home for how the engine is selected, a behavior matrix for `pg-delta` versus `migra`, the per-command fallback flags, a procedure for switching an existing project (the first `db pull` after enabling may write a catch-up migration), and how to go back with `enabled = false`. Registered in navigation. A shared `diff_engine_check` partial replaces the inline engine parentheticals across seven pages, and a `managed_schemas_diff_capture` partial carries the managed-schema capture rules. - **CLI reference (`cli_v1_commands.yaml`, `cli_v1_config.yaml`)**: `db pull`, `db schema declarative sync`/`generate` flags and descriptions, `experimental.pgdelta.*` and `db.migrations.schema_paths` config keys, and the `db diff` description updated to describe both engines. Note that `cli_v1_commands.yaml` is generated from the CLI repo; [supabase/cli#6557](https://github.com/supabase/cli/pull/6557) carries the matching `db pull` example and overlay text so the next publish keeps it. - **`examples/prompts/declarative-database-schema.md`**: rewritten for the `db schema declarative sync` flow, with the `[experimental.pgdelta]` prerequisite. ## Additional context The first draft was written against pg-delta 1.0.0-alpha.42. supabase/cli#6300 (engine upgrade to alpha.46) then changed two documented behaviors, both reflected here: generated SQL now defaults to uppercase pretty-printed keywords, and user RLS policies on `storage.objects`/`storage.buckets`/`realtime.messages` are included via the engine's `SUPABASE_USER_POLICY_SURFACES` allowlist. A follow-up dogfood run on `develop` `38f31b4` then falsified three more claims (pg-delta emits no grant noise, `_schema_changes`/`_after_enum_values` multi-file names, directive on every split file), all corrected in the last commit. **Update (Sep 14 to 17):** [#49889](https://github.com/supabase/supabase/pull/49889) and [#50220](https://github.com/supabase/supabase/pull/50220) were merged into this branch, so this PR now carries the full stack. #50220 corrected the `schema_paths` warning wording (the CLI warns only when the setting lists paths), added `auth` RLS policies to the managed-schema partial, and described the migra initial pull accurately (the `pg_dump` skips managed schemas and the migra diff pass that follows appends the trigger and policy changes). It also reframed `pg-delta` as the default for every project ahead of supabase/cli#6391. That plan changed: no breaking default flip before Select, so [#50332](https://github.com/supabase/supabase/pull/50332) restores the opt-in framing (`pg-delta` requires `[experimental.pgdelta] enabled = true`, which `supabase init` writes for new projects) and also resolves the four CodeRabbit findings from the latest review round. Two claims are pending confirmation from the owning teams: that branching runs every migration in a transaction and ignores the `-- pg-delta: transaction=false` directive, and the `--db-url` pooler-versus-direct connection advice, which currently disagrees with the CLI's own `db pull` docs. Stale spots found in the CLI repo's own docs while verifying (out of scope here, worth follow-ups): four `SIDE_EFFECTS.md` files still claim lowercase output, `docs/supabase/db/diff.md` still lists `migra`-era "known failure cases" that alpha.46 fully models, the `supabase init` template's commented `format_options` example shows `maxWidth: 80` against an actual default of 180, and the CLI upgrade recipe appends `--experimental` even when the config already enables pg-delta. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01SUuaVmXLRbV6tZjzhka3cp <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Clarified `pg-delta` and legacy `migra` behavior, configuration, and switching guidance. * Expanded declarative schema workflows, including synchronization, migration generation, baselines, deployment, and legacy-engine support. * Documented managed schemas, permissions, extensions, transaction handling, dependency ordering, and troubleshooting. * Added guidance for strict coverage checks, output directories, non-interactive workflows, and declarative pull modes. * Added a dedicated diff engines guide and updated CLI navigation, backup and restore, branching, deployment, and CI documentation. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Wen Bo Xie <wenbox323@gmail.com>
179 lines
8.2 KiB
Plaintext
179 lines
8.2 KiB
Plaintext
---
|
|
title: 'Troubleshooting'
|
|
description: 'Common issues and solutions for Supabase branching.'
|
|
subtitle: 'Common issues and solutions for Supabase branching'
|
|
---
|
|
|
|
This guide covers common issues you might encounter when using Supabase branching and how to resolve them.
|
|
|
|
## Monitoring deployments
|
|
|
|
To check deployment status and troubleshoot failures:
|
|
|
|
1. Go to your project dashboard
|
|
2. Navigate to "Manage Branches"
|
|
3. Click on your branch to view deployment logs
|
|
4. Check the "View logs" section for detailed error messages
|
|
|
|
For programmatic monitoring, you can use the [Management API](https://api.supabase.com/api/v1#tag/environments/post/v1/projects/{ref}/branches) to poll branch status.
|
|
|
|
For detailed troubleshooting guidance, see our [Troubleshooting guide](/docs/guides/deployment/branching/troubleshooting).
|
|
|
|
## Common issues
|
|
|
|
### Rolling back migrations
|
|
|
|
You might want to roll back changes you've made in an earlier migration change. For example, you may have pushed a migration file containing schema changes you no longer want.
|
|
|
|
To fix this, push the latest changes, then delete the preview branch in Supabase and reopen it.
|
|
|
|
The new preview branch is a fresh clone of your base project and is reseeded from the `./supabase/seed.sql` file by default. Any additional data changes made on the old preview branch are lost.
|
|
|
|
To rerun migrations that your base project has already applied, reset the branch from the Supabase dashboard instead. A reset reruns all migrations in sequential order and drops existing data on the branch.
|
|
|
|
### Deployment failures
|
|
|
|
A deployment might fail for various reasons, including invalid SQL statements and schema conflicts in migrations, errors within the `config.toml` config, or something else.
|
|
|
|
To check the error message, see the Supabase workflow run for your branch under the [View logs](/dashboard/project/_/branches) section.
|
|
|
|
### Schema drift between preview branches
|
|
|
|
If multiple preview branches exist, each preview branch might contain different schema changes. This is similar to Git branches, where each branch might contain different code changes.
|
|
|
|
When a preview branch is merged into the production branch, it creates a schema drift between the production branch and the preview branches that haven't been merged yet.
|
|
|
|
These conflicts can be resolved in the same way as normal Git Conflicts: merge or rebase from the production Git branch to the preview Git branch. Since migrations are applied sequentially, ensure that migration files are timestamped correctly after the rebase. Changes that build on top of earlier changes should always have later timestamps.
|
|
|
|
If you manage your schema with [declarative schema files](/docs/guides/local-development/declarative-database-schemas), resolve the drift in the schema files instead. Delete the migrations your branch generated, then run `supabase db schema declarative sync` to regenerate them. The regenerated migration gets a new timestamp, so it orders after existing migrations without renaming files by hand.
|
|
|
|
### Changing production branch
|
|
|
|
You cannot change which project branch serves as the production branch — the base project that all branches are created from will always remain the production branch. However, you can update which GitHub branch is linked to your production branch. To do this, go to the [Integrations page](/dashboard/project/_/settings/integrations) and change the production branch name.
|
|
|
|
## Migration issues
|
|
|
|
### Failed migrations
|
|
|
|
When migrations fail, check:
|
|
|
|
1. **SQL syntax**: Ensure your migration files contain valid SQL
|
|
2. **Dependencies**: Check if migrations depend on objects that don't exist
|
|
3. **Permissions**: Verify the migration doesn't require superuser privileges
|
|
|
|
To debug:
|
|
|
|
```bash
|
|
# Test migrations locally first
|
|
supabase db reset
|
|
|
|
# Check migration logs in the dashboard
|
|
# Navigate to Branches > Your Branch > View Logs
|
|
```
|
|
|
|
### Permission denied errors on a new branch
|
|
|
|
If the Data API returns `42501` permission denied errors on a branch for tables or functions that work on your base project, the branch is missing default privileges on the `public` schema. New branches are created without them, and only your migrations can grant them back.
|
|
|
|
Check whether your initial migration contains `alter default privileges ... grant` statements for the `public` schema. If it doesn't, see [Default privileges on branches](/docs/guides/deployment/branching/working-with-branches#default-privileges-on-branches) for how to add them, or [grant access explicitly](/docs/guides/api/securing-your-api#grant-access-explicitly) in a migration.
|
|
|
|
### Migration order problems
|
|
|
|
Migrations must run in the correct order. Common issues:
|
|
|
|
1. **Timestamp conflicts**: Ensure migration files have unique timestamps
|
|
2. **Dependency issues**: Later migrations depending on earlier ones
|
|
3. **Rebase problems**: Timestamps getting out of order after Git rebase
|
|
|
|
Fix by:
|
|
|
|
```bash
|
|
# Rename migration files to fix timestamp order
|
|
mv 20240101000000_old.sql 20240102000000_old.sql
|
|
|
|
# Reset local database to test
|
|
supabase db reset
|
|
```
|
|
|
|
Within a single migration generated on the [`pg-delta`](/docs/guides/local-development/diff-engines) engine (`supabase db diff` or `db schema declarative sync`), you don't need to reorder statements by hand, because the engine orders them by dependency. Migrations generated separately, such as on two branches that later merge, still need correct relative timestamps, so rename or regenerate them as shown above. A single sync can write split files that share a name (`_1`/`_2` suffixes) with timestamps one second apart. The CLI applies them in timestamp order, so renaming one file of a split pair in a way that changes that order breaks the sequence. Regenerate the migration instead. See [Cleaning up generated migrations](/docs/guides/local-development/cli-workflows#cleaning-up-generated-migrations).
|
|
|
|
## Connection issues
|
|
|
|
### Cannot connect to preview branch
|
|
|
|
If you can't connect to a preview branch:
|
|
|
|
1. **Check credentials**: Ensure you're using the correct branch-specific credentials
|
|
2. **Auto-pause**: The branch might be paused. It will resume on the first request
|
|
3. **Network restrictions**: Check if network restrictions are blocking access
|
|
|
|
### Connection timeouts
|
|
|
|
Preview branches auto-pause after inactivity. First connections after pause may timeout:
|
|
|
|
1. **Retry**: The branch will wake up after the first request
|
|
2. **Persistent branches**: Convert frequently-used branches to persistent
|
|
|
|
## Configuration problems
|
|
|
|
### Config.toml not applying
|
|
|
|
If configuration changes aren't applying:
|
|
|
|
1. **Syntax errors**: Validate your `config.toml` syntax
|
|
2. **Git sync**: Ensure changes are committed and pushed
|
|
3. **Branch refresh**: Try deleting and recreating the branch
|
|
|
|
### Secrets not available
|
|
|
|
If secrets aren't working in your branch:
|
|
|
|
1. **Branch-specific**: Remember secrets are set per branch
|
|
2. **Syntax**: Use correct syntax: `env(SECRET_NAME)`
|
|
3. **CLI version**: Ensure you're using the latest CLI version
|
|
|
|
## Performance issues
|
|
|
|
### Slow branch creation
|
|
|
|
Branch creation might be slow due to:
|
|
|
|
1. **Large migrations**: Many or complex migration files
|
|
2. **Seed data**: Large seed files take time to process
|
|
3. **Network latency**: Geographic distance from the branch region
|
|
|
|
### Query performance
|
|
|
|
Preview branches may have different performance characteristics:
|
|
|
|
1. **Cold starts**: First queries after auto-pause are slower
|
|
2. **Resource limits**: Preview branches have different resource allocations
|
|
3. **Indexing**: Ensure proper indexes exist in your migrations
|
|
|
|
## Data issues
|
|
|
|
### Seed data not loading
|
|
|
|
If seed data isn't loading:
|
|
|
|
1. **File location**: Ensure `seed.sql` is in `./supabase/` directory
|
|
2. **SQL errors**: Check for syntax errors in seed file
|
|
3. **Dependencies**: Seed data might reference non-existent tables
|
|
|
|
### Data persistence
|
|
|
|
Remember that preview branch data:
|
|
|
|
1. **Is temporary**: Data is lost when branch is deleted
|
|
2. **Isn't migrated**: Data doesn't move between branches
|
|
3. **Resets on recreation**: Deleting and recreating branch loses data
|
|
|
|
## Getting help
|
|
|
|
If you're still experiencing issues:
|
|
|
|
1. **Check logs**: Review branch logs in the dashboard
|
|
2. **Community**: Ask in [GitHub discussions](https://github.com/orgs/supabase/discussions/18937)
|
|
3. **Support**: Contact support for project-specific issues
|
|
4. **Documentation**: Review the latest documentation for updates
|