Supabase
Branching - Early access | Feedback discussion #18937
Replies: 244 comments 566 replies
-
What is Supabase Branching? |
Beta Was this translation helpful? Give feedback.
-
|
In the most concise sense, you can use branching to safely and easily experiment with changes to your Supabase projects. |
Beta Was this translation helpful? Give feedback.
-
|
Is branching expected to be available only from |
Beta Was this translation helpful? Give feedback.
-
|
@KajSzy We've currently closed the Early Access programme for Branching. If you have already upgraded expecting access, if you could send in a support request and we'll look into it 😄. I think some of our docs have not been updated to make it clear that it's in private early access, and we've now closed accepting any more requests. I'll update the docs today to be more clear. |
Beta Was this translation helpful? Give feedback.
-
|
Hope you're all doing great! I've been working with supabase on a project for 2 months and noticed something I wanted to share with you that would cause issues for supabase branching. As our projects grow, our seed file (you know, the trusty I've been sidestepping this by ditching the massive seed file and scripting my local database seeding instead. It's a lot like how migrations work: each file is timestamped and has a quick description, and they run in a set order. This means I have separate files for different seeding needs, like permission tables and location table inserts broken down into 1K-insert chunks – it’s pretty neat. Currently, Supabase runs whatever is in I reckon this could be something worth considering for your roadmap for seeding a branch. Thanks for all the hard work you've been putting into Supabase, and I'm excited to see how branching evolves! |
Beta Was this translation helpful? Give feedback.
-
|
Neat idea. I also mentioned this to @sweatybridge who is one of the developers managing our migration/seed runner. I suppose it would have to be timestamped for it to work correctly. Do we know of any other tools doing this? We can't be the first ones to think of this? 😊 |
Beta Was this translation helpful? Give feedback.
-
|
To be honest I took the idea directly from my experience of working with the ORM Sequelize. Here is a relevant documentation that mention both migrations and seed files: https://sequelize.org/docs/v6/other-topics/migrations/ One thing to note is that their migrations have an up (which is covered by seed.sql) and a down that is not covered by supabase. The down function is if you are to roll back a migration including any data manipulation that was required to complete the migration. It's very useful when you can't predict how a project will evolve once it's in front of users. Sequelize also handle transactions in their migrations, which makes migrating production databases a lot less intimidating. |
Beta Was this translation helpful? Give feedback.
-
|
There is a similar discussion to this here as well now 🙌 |
Beta Was this translation helpful? Give feedback.
-
|
Hasura uses timestamped seed files. https://hasura.io/docs/2.0/migrations-metadata-seeds/manage-seeds/ |
Beta Was this translation helpful? Give feedback.
-
|
Hello, could someone help me. Send me a message |
Beta Was this translation helpful? Give feedback.
-
|
if new branch is created, new Supabase url for client is reserved on new branch?? I maen if I use following url on main branch Can I use a different url for a new branch like staging? For example, |
Beta Was this translation helpful? Give feedback.
-
|
How it works today is a bit like that but it's the id string in the middle that changes. main branch (production) const supabase = createClient('https://spztrrugbkgdayfejlvi.supabase.co/', 'public-anon-key')the feature branch your working on will then have a completely different id in the url const supabase = createClient('https://qrelykancvxikefwrefd.supabase.co/', 'public-anon-key')I could understand if this might not be useful in some circumstances, as it makes it harder to build urls based on git branch name in maybe your client or server app. The problem extends to API keys though as well, since every branch in Supabase has it's own unique set of API keys, db password and so on. What do you think @chaos128 ? |
Beta Was this translation helpful? Give feedback.
-
|
It would be okay but I think it would be a little bit inconvenient. It would be better if domain and key are not changed but only pathname is changed based on branch names like I said on question. main branch staging branch feature/test branch |
Beta Was this translation helpful? Give feedback.
-
|
That's interesting. Can see that being a lot more useful and easier to use. Also the keys not changing between Preview Branches is interesting as well - we were mostly concerned with Production and Preview being isolated and concentrated efforts on that and hadn't really investigated on making it easy to switch between Preview branches with predictable URLs and consistent keys. Great suggestion. |
Beta Was this translation helpful? Give feedback.
-
|
@chaos128 how are you using Supabase Branching? |
Beta Was this translation helpful? Give feedback.
-
|
Chiming in here because I would also love to see predictable URLs and consistent keys. We have a Next.js app on Vercel, using Prisma. Our current workflow, without Supabase branching: Our branch That means preview/feature branches create Vercel preview deployments, but have to stay unmigrated (except for staging itself), since we don't want to mess up the staging db before merging to If we turned on Supabase branching on our staging db, I'm picturing that it could work for preview deployments if the app and, separately, the GH action, can both get or construct the branch db's URL/creds (actually we use the full pooler URL) from env variables that are available. And then we'd have the GH action migrate the designated branch db upon branch creation. So a completely new set of URL/creds seems hard to deal with in this scenario, whereas some combination of base URL (already set in Vercel and GH) plus the branch name (already easily available in Vercel and GH) would be very doable. I see someone else who posted has a similar setup with some steps to make it theoretically work in the GH action.. but it seems to rely on CLI commands, and I'm not sure if that would work for getting the Vercel preview app to also point to the branch db. (Update: I also just realized Vercel support is in development which would solve the Vercel half.) |
Beta Was this translation helpful? Give feedback.
-
|
Can branching be used as a "dev" environment? |
Beta Was this translation helpful? Give feedback.
-
|
Yep. What's your use case? Can you tell us more? |
Beta Was this translation helpful? Give feedback.
-
|
According to the docs: "The database is only seeded once, when the preview branch is created. To rerun seeding, delete the preview branch and recreate it." But when I deleted and recreated the branch (
|
Beta Was this translation helpful? Give feedback.
-
|
EDIT: |
Beta Was this translation helpful? Give feedback.
-
|
That's probably a bug. We are using github webhooks and I think it only adds the PR metadata to the Preview Branch when a PR is opened (there's a webhook event for it) - but that makes it impossible for a new Preview Branch to then be associated with a PR later; like when you've made a new Preview Branch. I think we could fix that. Everything should work as normal though, it's only the UI here that's been impacted. |
Beta Was this translation helpful? Give feedback.
-
|
So far pretty good with supabase branching. Should I disable my existing github actions that migrate the production database when merging to the production branch? Is it expected that the migrations should be applied via this new Supabase branching integration? |
Beta Was this translation helpful? Give feedback.
-
|
It's worth stressing first that Branching is not suitable for production based apps right now. With that in mind, and if you want to continue; yes, you should be able to merge your feature git branch into your 'production' git branch and it will run the new migration files against the Production Supabase branch. There is currently no way to turn this off, so it's probably advised to disable your github actions. |
Beta Was this translation helpful? Give feedback.
-
|
@MildTomato are there known issues we should watch out for w.r.t. production? Or is it just that more time is needed to bash the bugs out that in theory could harm a prod instance? |
Beta Was this translation helpful? Give feedback.
-
|
When you say it's not suitable for production based apps, do you mean using branches at all, or running prod off of a branch? |
Beta Was this translation helpful? Give feedback.
-
|
@MildTomato does supabase branching support monorepos? Our |
Beta Was this translation helpful? Give feedback.
-
|
Yeah would love to see this sort of mono-repo support! Very excited for you all to start using branching on internally too! |
Beta Was this translation helpful? Give feedback.
-
|
I would also require the mono-repo support for my project with a custom path to my migrations folder. Big fan of this branching feature and how it is progressing! |
Beta Was this translation helpful? Give feedback.
-
|
The code for it is already written and we're going to test everything in upcoming week :) |
Beta Was this translation helpful? Give feedback.
-
|
Monorepo support has been added and is already live if you have an access to branching 🎉 |
Beta Was this translation helpful? Give feedback.
-
|
monorepo support:
|
Beta Was this translation helpful? Give feedback.
-
|
any advice on how to handle issues like this that require setting up things in the database (eg. webhooks)? 
|
Beta Was this translation helpful? Give feedback.
-
|
Any updates here? This is preventing us from using branching |
Beta Was this translation helpful? Give feedback.
-
Beta Was this translation helpful? Give feedback.
-
|
For what it's worth, I have been running into so many issues with branching that the best solution for us was to manage the full lifecycle using a custom github action leveraging the management API. |
Beta Was this translation helpful? Give feedback.
-
|
@blechatellier that may be what we have to end up doing—would be a shame |
Beta Was this translation helpful? Give feedback.
-
|
To be fair, hard for them to come up with something that will work for everyone - it's been the best decision and took a couple of days to get it to work. |
Beta Was this translation helpful? Give feedback.
-
|
Hello! Loving the concept so far. After spending some time working around issues (seeding not being run and functions not being deployed), I realised you have a CLI for managing branches (which looks great btw!), and I think it could be highlighted more, as I was under the impression that only the "managed" workflows were supported (i.e only Github + Vercel), but atleast for me the feature set is complete enough that I could run this anywhere (and if i missed that that was possible, many others probably have too) |
Beta Was this translation helpful? Give feedback.
-
|
@sweatybridge any updates on Webhooks? |
Beta Was this translation helpful? Give feedback.
-
|
Yup, we've finally shipped a secure way to use secrets from webhooks supabase/cli#1190 (comment) |
Beta Was this translation helpful? Give feedback.
-
|
I'm facing the same issue as @sleakchat; when I pull my production database schema as a migration using |
Beta Was this translation helpful? Give feedback.
-
|
@baballev we should have documented it better, but you need to enable webhooks via config.toml |
Beta Was this translation helpful? Give feedback.
-
|
Wow great, thanks @sweatybridge this does the trick indeed! :) |
Beta Was this translation helpful? Give feedback.
-
|
We are in dire need of selecting non root directories as the Supabase root. We are using a monorepo with TurboRepo. |
Beta Was this translation helpful? Give feedback.
-
|
It's coming. Bear with us some more time, we're getting there :) |
Beta Was this translation helpful? Give feedback.
-
|
That's great news! We just finished building our own internal psuedo-branching by creating a new project on every PR. It was quite difficult to implement correctly since there was a silent failure when connecting via IPv4. Do you have any rough estimation on timelines? |
Beta Was this translation helpful? Give feedback.
-
|
We're hoping to release this month, but I don't want to be held accountable for any specific date just yet. |
Beta Was this translation helpful? Give feedback.
-
|
Monorepo support has been added and is already live if you have an access to branching 🎉 |
Beta Was this translation helpful? Give feedback.
-
|
Currently, we're testing each branch by setting up a local supabase instance in GH Actions for every run. But that setup takes a significant amount of time compared to the actual test run. The flow that we have in mind is:
Are there any blockers that we should be aware of? Moreover, once this is set up and the Vercel app is used, I'm assuming the preview instances will use the new branched supabase. We also don't want any changes in the preview branches going back into main (which I assume will not happen as we are not using supabase migrations in the preview branches). Can you please confirm this? |
Beta Was this translation helpful? Give feedback.
-
Yes that is correct. The Supabase GitHub integration only look for files in Overall your approach sounds sane to me. We will need to make some changes for step 2 and 3 so that you can fetch a preview branch by its git branch name. Otherwise the current workaround is to parse the output from You might also need to handle retries in step 4 until the status of your branch database is ACTIVE_HEALTHY. I think step 7 is not required if you use the Supabase GitHub integration. Because we delete the branch on PR close. |
Beta Was this translation helpful? Give feedback.
-
|
Hello, I'm doing this approach in a Github Action that always wait until the database is ACTIVE_HEALTHY before continuing. I have retry logic in my github action and it typically is able to connect after a few tries in approximately 10 seconds. Sometimes the Github action fails after like 5 mins, but I then I re-run it and it works. I have had better success by not using Here, I get error message: But sometimes, Github can never seem to connect to the created database so I delete it and try again. |
Beta Was this translation helpful? Give feedback.
-
|
Feedback/idea: It'd be nice (or even crucial) for the preview branch to copy most local and/or production branch settings. Examples:
|
Beta Was this translation helpful? Give feedback.
-
|
I just tested edge function secrets and it turns out you can use the following in [edge_runtime.secrets]
STRIPE_API_KEY = "env(STRIPE_API_KEY)"Locally, the environment variables are populated via I haven't found any official documentation on this behavior, except for some commented-out lines in the example config.toml. Use this approach with caution unless we get confirmation from the supabase maintainers that this is the correct way to do it. |
Beta Was this translation helpful? Give feedback.
-
|
I found what seems to be a bug on the permanent Branching deployment, related to what has been discussed here, @sweatybridge. Encrypted env vars do not get updated to the correct value in the .env.{preview|production}, neither in Vault and Edge Function secrets. The reproduction steps are:
Result:
Unless I'm doing something wrong (I followed all guides and examples), this is quite a critical thing and breaks my backend on every pull request. What do you think? |
Beta Was this translation helpful? Give feedback.
-
|
Hi @GorkaMM, we have identified the bug on our side. It is currently causing dotenvx encrypted secrets to be ignored where it should be used as the source of truth. I will update again when the fix is released (likely next monday). |
Beta Was this translation helpful? Give feedback.
-
|
Thank you @sweatybridge! Reported here: supabase/cli#3742 Is there any workaround in the meantime? I need to launch this weekend. |
Beta Was this translation helpful? Give feedback.
-
|
FYI, this was a bug in Supabase and it was fixed already. |
Beta Was this translation helpful? Give feedback.
-
|
For some reason I'm not seeing migrations running or seed data populated for a preview branch (feature or development). When I create a PR, it's spinning up the branch, just no tables or seed data. |
Beta Was this translation helpful? Give feedback.
-
Done, you can use it today.
There is basic seeding capability already with |
Beta Was this translation helpful? Give feedback.
-
+1(00) on this point! |
Beta Was this translation helpful? Give feedback.
-
|
They say the best way now is to create a separate Supabase project for the staging branch. |
Beta Was this translation helpful? Give feedback.
-
|
Q: We have few ideas how to go around it, but just to get a feel for it in public, wdyt is your preference in regards to long-lived branches?
|
Beta Was this translation helpful? Give feedback.
-
|
Adding a data point: we are using a separate project for Staging + Preview branches, while keeping our original project for Production only (same as @RobSchilderr's post above). This seems to work pretty well for persisting Staging so far, though it's not 1:1 with the Vercel style of branching. |
Beta Was this translation helpful? Give feedback.
-
|
We handle our migrations via Prisma migrate. Are there any plans to support the |
Beta Was this translation helpful? Give feedback.
-
|
Currently you'd have to move file to |
Beta Was this translation helpful? Give feedback.
-
|
Would just moving the folder work? The migration files/formats are directly compatible with supabase? |
Beta Was this translation helpful? Give feedback.
-
|
Yes, the migration file is always just a smallest sql snippet that will result in the desired schema shape at the end of execution. find . -type d -depth 1 | xargs -I{} cp {}/migration.sql migrations/{}.sql; |
Beta Was this translation helpful? Give feedback.
-
|
Got it. A cleaner way built in to supabase would be nice! Especially since there's a pretty large audience (I'm assuming) of supabase TS users using prisma. |
Beta Was this translation helpful? Give feedback.
-
|
Here's a bash script for those that want to copy Prisma migrations to a #!/bin/bash
# Define paths
PRISMA_MIGRATIONS_DIR="./prisma/migrations" # Replace with your Prisma migrations directory
SUPABASE_MIGRATIONS_DIR="./supabase/migrations" # Replace with your desired Supabase migrations directory
# Create the Supabase migrations directory if it doesn't exist
mkdir -p "$SUPABASE_MIGRATIONS_DIR"
# Function to convert Prisma migration files to Supabase format
convert_prisma_to_supabase() {
for prisma_migration_dir in "$PRISMA_MIGRATIONS_DIR"/*/; do
if [[ -d "$prisma_migration_dir" ]]; then
migration_file="$prisma_migration_dir/migration.sql"
if [[ -f "$migration_file" ]]; then
migration_name=$(basename "$prisma_migration_dir")
supabase_migration_file="$SUPABASE_MIGRATIONS_DIR/$migration_name.sql"
cp "$migration_file" "$supabase_migration_file"
echo "Converted $migration_file to $supabase_migration_file"
fi
fi
done
}
# Run the conversion function
convert_prisma_to_supabase
echo "Migration conversion completed."
|
Beta Was this translation helpful? Give feedback.
-
|
Hey Folks I want to Setup a Supa Base Branching for the Automation Testing so the scenario is Below So how i can do it can anyone help me out in this Thanks in Advance. |
Beta Was this translation helpful? Give feedback.
-
|
@MildTomato Hi, |
Beta Was this translation helpful? Give feedback.
-
|
I have the same problem @pavelpoley. To solve it, I did the following. |
Beta Was this translation helpful? Give feedback.
-
|
Not sure I get it, what you did in the screenshot? |
Beta Was this translation helpful? Give feedback.
-
|
Ok |
Beta Was this translation helpful? Give feedback.
-
|
Hey folks, I've read through most of the comments here, but couldn't quite find something that matched my use case. So here it comes. Context My expectation
Reality Now, I find this a bit weird because running migrations against an empty DB doesn't really tell me much. And even worse, now I should go in and manually update my seed to update the latest migrated state... Meh. My intention was to have a seed of prod data, so that I can reliably test migrations even when not everyone has that data locally (people have their own data setup for testing stuff - only CI must have that prod-like data). So, the way this currently works adds a lot of burden on my end, when it seems like this could be easily mitigated by changing when migrations are run. Even more so, I'm having trouble seeing what exactly the benefit of these branches is when I can't easily get realistic data into them. |
Beta Was this translation helpful? Give feedback.
-
|
I agree; one solution would be to add seeds in order along with migrations so that you just have to write seed data inserts for the structure that exists at the moment you wrote it, and then future migrations may update that data as they would update a production database. This has two advantages:
Since seeds and migrations are just SQL statements... I'm not sure what all would need to be done to enact this kind of change, except that seeds are files that need to NOT be run in production. I'm suggesting we would want to have migrations and seeds in the same folder (so we can easily see the order in which they'll be applied without having to parse datestamp strings without mushy human eyes), so perhaps there could be some convention like |
Beta Was this translation helpful? Give feedback.
-
|
Really a seed file????? |
Beta Was this translation helpful? Give feedback.
-
|
Can we have a diff compare tool? Especially when we use 2 proejcts for staging and prod |
Beta Was this translation helpful? Give feedback.
-
|
Hey. Additional Roles are not copied and are leading to an error when creating a new branch. |
Beta Was this translation helpful? Give feedback.
-
|
Hey. I see the option to copy data from PITR when creating new branch is not on the UI anymore. Why is that? Is that feature not available anymore or you moved it somewhere else? |
Beta Was this translation helpful? Give feedback.
-
|
How do I use branching whilst using Drizzle (and the migrations from Drizzle)? |
Beta Was this translation helpful? Give feedback.
-
|
Hey everyone, I have a use case with branching where I noticed something I’d like to clarify or suggest as an improvement. When I reverted a PR that had been previously merged into the My expectation was that, since the integration tracks migrations as part of the Git branch sync, reverting a PR should also revert the applied migrations, essentially rolling back the schema changes that were introduced by that PR. Is this currently expected behavior (i.e., migrations aren’t automatically reverted), or is there a way to make the integration detect this case and trigger a reverse migration automatically? Would love to hear how others handle rollback scenarios with branching + migrations. |
Beta Was this translation helpful? Give feedback.
-
|
So if you git checkout SHA into an earlier branch and your migration changes back in your local or even remote branch, sure maybe you'll have those old migrations back in your branch but if you go to push those changes and your current databases is at a newer version with new tables, are the old migration still going to accurately migrate? (sorry for all the edits. I haven't slept for a bit. 😅) |
Beta Was this translation helpful? Give feedback.
-
Everytime a run a migration on a branch the Auth URL Configuration resets to localhost, I think this should be treated as a bug and fixed
|
Beta Was this translation helpful? Give feedback.
-
|
This only occurs when you have the wrong production branch set up in your supabase settings as well as your GitHub branch, so be sure that both are set up the same and when you merge into that branch or in, let's say with Vercel, if you have Preview set up for All undesignated branches aside from your production branch, it will spin up a preview with each one and once you merge it into your main, it will run those migrations automatically as long as it did not fail |
Beta Was this translation helpful? Give feedback.
-
|
Disconnecting the main branch from GitHub is causing a lot of headache in the "Branching via Dashboard" beta feature |
Beta Was this translation helpful? Give feedback.
-
|
Before you disconnect anything, you should probably do a backup or a local dump as there's always a chance for these immigrations that have access to your database, specifically your reproduction to act in unwarranted ways. This will allow you to avoid the repercussions that come with such things. |
Beta Was this translation helpful? Give feedback.
-
|
I appreciate your comment. I am not concerned about my database per se, but rather trying to highlight a potential issue for the Supabase development team. Thank you. |
Beta Was this translation helpful? Give feedback.
-
|
ok
…________________________________
From: Benjamin Ciccarelli ***@***.***>
Sent: 13 November 2025 00:38
To: supabase/supabase ***@***.***>
Cc: Sakshi ***@***.***>; Manual ***@***.***>
Subject: Re: [supabase/supabase] Branching - Early access | Feedback discussion (Discussion #18937)
Disconnecting the main branch from GitHub is causing a lot of headache in the "Branching via Dashboard" beta feature, I'm not able to make a preview branch without migrations failing because the migration history is broken for main.
—
Reply to this email directly, view it on GitHub<#18937 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/A4XLCTIP3T6DRREHLVVEF3334OASLAVCNFSM6AAAAAA7KFV5GSVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTIOJVGEYTCMY>.
You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>
|
Beta Was this translation helpful? Give feedback.
-
|
how to increase the limit of active branches? It seems I can't get past 10. |
Beta Was this translation helpful? Give feedback.
-
|
Issue from Problem When creating a preview branch via CLI or API, the branch status returns as "ready" before database connections and other services are fully operational. This causes CI/CD pipeline failures when workflows attempt to use the branch immediately after the ready status is returned. Steps to Reproduce Create a new preview branch using supabase branches create or GitHub integration Actual Behavior API returns "ready" status Impact This breaks the API contract and forces workarounds like: Polling for ACTIVE_HEALTHY database status separately Environment Supabase CLI version: 2.51.0 Issue #39604 |
Beta Was this translation helpful? Give feedback.
and others
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
This discussion is for tracking feedback and possible issues for Supabase Branching.
This will help us plan a roadmap for the feature going forward.
Vote for hosting provider integrations here and Git providers here.
Beta Was this translation helpful? Give feedback.
All reactions