mirror of
https://github.com/supabase/supabase.git
synced 2026-10-05 09:25:06 +03:00
docs: document that branches are secure by default (#50193)
## 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? The branching docs don't mention that new branches are created without default privileges on the `public` schema. Linear: BRA-189 ## What is the new behavior? - Working with branches: new "Default privileges on branches" section covering the keep-enabled path (initial migration grants) and the revoke path (new migration). - Troubleshooting: new entry for `42501` permission denied errors on a new branch. ## Additional context None. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Added troubleshooting guidance for permission-denied errors affecting tables or functions on new branches. - Explained how migrations can restore intended default privileges on the `public` schema. - Added workflows for retaining or revoking default privileges, including dashboard configuration, migration-history repair, and access-management steps. - Added examples for granting or revoking access to sequences, functions, and tables. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Han QiaoandClaude authored and GitHub committed
1 parent
c6a1c2052c
commit
85573164f4
2 files changed
+105
No files matched your search
@@ -69,6 +69,12 @@ supabase db reset
|
||||
# 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:
|
||||
|
||||
@@ -183,6 +183,105 @@ Migrations are run in sequential order. Each migration builds upon the previous
|
||||
|
||||
The preview branch inherits the migration history of your base project, so it only applies migrations that haven't been run yet. This can create an issue when rolling back migrations.
|
||||
|
||||
### Default privileges on branches
|
||||
|
||||
New branches are secure by default. They are created without [default privileges](/docs/guides/api/securing-your-api#default-privileges) on the `public` schema, regardless of the setting on your base project. New tables, functions, and sequences on a branch require explicit grants before `anon`, `authenticated`, or `service_role` can reach them through the Data API.
|
||||
|
||||
Your migrations control whether a branch re-enables these privileges. If your base project has default privileges enabled and your migration history was initialized by Supabase Branching or the Supabase CLI, the initial migration already contains the `alter default privileges` statements that grant access on `public`. Running it on a new branch restores the same access your base project has, so no changes are needed.
|
||||
|
||||
Two cases require manual intervention:
|
||||
|
||||
- You manage migrations outside Supabase and want to [keep default privileges enabled](#keep-default-privileges-enabled) on branches.
|
||||
- You use Supabase managed migrations and want to [revoke default privileges](#revoke-default-privileges) on your base project and branches.
|
||||
|
||||
#### Keep default privileges enabled
|
||||
|
||||
If your migration history was not initialized by Supabase Branching or the Supabase CLI, your initial migration doesn't grant default privileges, so new branches start without them. To restore the same access your base project has:
|
||||
|
||||
<StepHikeCompact>
|
||||
<StepHikeCompact.Step step={1}>
|
||||
<StepHikeCompact.Details title="Turn on default privileges on your base project" fullWidth>
|
||||
|
||||
Open the [Data API settings](/dashboard/project/_/integrations/data_api/settings) in the Supabase Dashboard and turn on **Default privileges for new entities**.
|
||||
|
||||
</StepHikeCompact.Details>
|
||||
|
||||
</StepHikeCompact.Step>
|
||||
|
||||
<StepHikeCompact.Step step={2}>
|
||||
<StepHikeCompact.Details title="Add grants to your initial migration" fullWidth>
|
||||
|
||||
Insert the following statements at the start of your initial migration file. Subsequent migrations then inherit these privileges, so the final database state is unchanged.
|
||||
|
||||
```sql
|
||||
alter default privileges for role postgres in schema public grant usage, select, update on sequences to anon, authenticated, service_role;
|
||||
alter default privileges for role postgres in schema public grant execute on functions to anon, authenticated, service_role;
|
||||
alter default privileges for role postgres in schema public grant select, insert, update, delete on tables to anon, authenticated, service_role;
|
||||
```
|
||||
|
||||
</StepHikeCompact.Details>
|
||||
|
||||
</StepHikeCompact.Step>
|
||||
|
||||
<StepHikeCompact.Step step={3}>
|
||||
<StepHikeCompact.Details title="Repair the migration history of your base project" fullWidth>
|
||||
|
||||
Mark the updated migration as applied so it isn't rerun on your base project. See [Diagnosing and fixing sync errors](/docs/guides/deployment/database-migrations#diagnosing-and-fixing-sync-errors).
|
||||
|
||||
```bash
|
||||
supabase migration repair --status applied <migration-timestamp>
|
||||
```
|
||||
|
||||
</StepHikeCompact.Details>
|
||||
|
||||
</StepHikeCompact.Step>
|
||||
</StepHikeCompact>
|
||||
|
||||
#### Revoke default privileges
|
||||
|
||||
For improved security, we recommend not exposing the `public` schema automatically on your base project either. If your initial migration was generated by Supabase Branching or the Supabase CLI, it re-grants default privileges when it runs on a branch. To revoke them on your base project and branches:
|
||||
|
||||
<StepHikeCompact>
|
||||
<StepHikeCompact.Step step={1}>
|
||||
<StepHikeCompact.Details title="Turn off default privileges on your base project" fullWidth>
|
||||
|
||||
Open the [Data API settings](/dashboard/project/_/integrations/data_api/settings) in the Supabase Dashboard and turn off **Default privileges for new entities**.
|
||||
|
||||
</StepHikeCompact.Details>
|
||||
|
||||
</StepHikeCompact.Step>
|
||||
|
||||
<StepHikeCompact.Step step={2}>
|
||||
<StepHikeCompact.Details title="Add a new migration that revokes the grants" fullWidth>
|
||||
|
||||
Create a new migration file with the Supabase CLI. Don't edit the initial migration, because that affects subsequent migrations in your history.
|
||||
|
||||
```bash
|
||||
supabase migration new revoke_default_privileges
|
||||
```
|
||||
|
||||
Add the following statements to the generated file:
|
||||
|
||||
```sql
|
||||
alter default privileges for role postgres in schema public revoke select, insert, update, delete on tables from anon, authenticated, service_role;
|
||||
alter default privileges for role postgres in schema public revoke execute on functions from anon, authenticated, service_role, public;
|
||||
alter default privileges for role postgres in schema public revoke usage, select, update on sequences from anon, authenticated, service_role;
|
||||
```
|
||||
|
||||
</StepHikeCompact.Details>
|
||||
|
||||
</StepHikeCompact.Step>
|
||||
|
||||
<StepHikeCompact.Step step={3}>
|
||||
<StepHikeCompact.Details title="Commit and push" fullWidth>
|
||||
|
||||
Commit the new migration file and push it to your Git repository. The migration runs on your base project when merged and on every new branch, so both start without default privileges.
|
||||
|
||||
</StepHikeCompact.Details>
|
||||
|
||||
</StepHikeCompact.Step>
|
||||
</StepHikeCompact>
|
||||
|
||||
### Using ORM or custom seed scripts
|
||||
|
||||
If you want to use your own ORM for managing migrations and seed scripts, you will need to run them in GitHub Actions after the preview branch is ready. The branch credentials can be fetched using the following example GHA workflow.
|
||||
|
||||
Reference in new issue
Block a user