How to Set Up a Local Supabase Instance to Mirror Your Existing Project

Setting up a local instance for your Supabase backend is very important because, without it, you’d be experimenting on your live database and that might mess things up for your application, especially if it’s live. You can use the Supabase CLI to setup up a local instance of your already existing Supabase project, or even create a new one.

Some benefits of setting up a local instance of your Supabase backend are:

• Helps you keep production and development environments separate.

• Allows for completely offline development.

• You don’t really need an online Supabase project, which means, unlimited test projects!

Setting Up Supabase CLI

If you don’t have Supabase CLI setup on your machine and in your project, refer to this post:

Using Supabase CLI: How to Configure Local Supabase for Next.js Development

Although the title says it’s for Next.js, the instructions are pretty generic and will work for almost all types of projects.

Linking & Syncing Local Instance With The Online One

After you’re done with the Supabase CLI setup, follow these instructions to link and sync your Supabase backend with a local instance:

1. Login to Supabase using the following command:

    supabase login
   

2. Link the local project to the one online using the link command and the project id:

    supabase link --project-ref YOUR_PROJECT_REF_ID
   

3. Next, run the following command:

    supabase db pull
   

   This pulls all the tables, functions, policies, etc., from the online version and generates a migration script under the /supabase/migrations folder.

   Sometimes, unexpected errors may pop up, so will a list of commands along with them, like below:

    supabase migration repair --status reverted 20250609121341
    supabase migration repair --status reverted 20250609121411
    supabase migration repair --status reverted 20250609121421
    supabase migration repair --status reverted 20250609121430
    supabase migration repair --status reverted 20250609121549
   

   Just run them in order and run the supabase db pull command again to generate the migration file.

4. Finally, run the following command to complete setting up your local Supbase backend setup.

    supabase db reset
   

   1. No, this won’t delete any data on your original database.

   2. This won’t bring a copy of data from your original database.

   3. This will setup all the tables, functions, policies, etc., as they were in your original database.

And that’s it! Your Supabase backend now has a local version that you can play with, without worrying about messing up with anything.

Bonus

It kinda sucks how AI tools like Cursor, Windsurf, etc., never ask you setup a local instance using Supabase and jump straight to doing things with Supabase online. That is so messed up in many ways. You’d be testing your app and modifying things on a production environment. That is the equivalent of making changes to your app while people are using your app.

That being said, if you’re a vibe-coder, or a developer who didn’t know that you could do something like this, next time you prompt AI to build an app for you, if you’re sure that you’ll be using Supabase for your database/backend, include this line: “Use Supabase CLI.“

Happy Coding and Vibe-Coding!