Skip to main content

Local Development

Supabase provides a CLI so that you can develop your application locally, with the ability to deploy your application to the Supabase platform.

Prerequisites​

Dependencies​

Before we begin, make sure you have these installed on your local machine:

  • Git. Docs
  • Docker (make sure this is running). Docs
  • Supabase CLI. Docs

Supabase CLI login​

After installing the Supabase CLI you can log in using your Supabase account (sign up at app.supabase.com).

supabase login

This is a one-time operation. After you have logged in the CLI will have permissions to manage your Supabase projects.

Getting started​

Initialize your project​

Let's create a new folder on your local machine:

# create your project folder
mkdir your-project

# move into the new folder
cd your-project

# start a new git repository
git init

These commands will create an empty folder for your project and start a new git repository.

Initialize Supabase​

Let's initialize Supabase inside the folder that you created:

supabase init

This command will create a supabase folder which holds all the configuration for developing your project locally.

Developing Locally​

Start Supabase​

supabase start

The start command uses Docker to start the open source services of Supabase. This command may take a while to run if this is the first time using the CLI.

Once all of the Supabase services are running, you'll see an output that contains your local Supabase credentials.

You can use the stop command at any time to stop all services.

Accessing Services Directly​

# Default URL:
postgresql://postgres:postgres@localhost:54322/postgres

The local Postgres instance can be accessed through psql or any other Postgres client, such as pgadmin.

For example:

psql 'postgresql://postgres:postgres@localhost:54322/postgres'

Database Migrations​

Database changes are managed through "migrations". Database migrations are a common way of tracking changes to your database over time.

Making database changes​

For this guide, let's create a table called employees, using the "Supabase Studio" link provided.

note

If you're familiar with databases, you can also execute any SQL using the DB URL shown by supabase start.

Open the Studio, navigate to the "SQL Editor" section, and run the following SQL command:

create table employees (
    id integer primary key generated always as identity,
    name text
);

Now we have the employees table in the local database, but how do we incorporate this into migrations? The CLI automatically detects changes by running the commit command:

supabase db commit create_employees

This creates a new migration named supabase/migrations/<timestamp>_create_employees.sql, representing any changes we've made to the local database since supabase start.

Adding sample data​

Let's add some sample data into the table. We can use the seed script in supabase/seed.sql (which gets created when you run supabase init). 

-- in supabase/seed.sql
insert into public.employees (name)
values 
  ('Erlich Backman'),
  ('Richard Hendricks'),
  ('Monica Hall');

Now run the following to rerun the migration scripts and the seed script:

supabase db reset

If you look again within Studio, you should now see the contents of employees.

Resetting database changes​

If you run any SQL on the local database that you want to revert, you can use the reset command.

-- run on local database to make a change
alter table employees 
  add department text default 'Hooli';

To revert this change we can run:

supabase db reset

And the local database will be reset.

Deploying​

Now that you've developed an application locally, head over to app.supabase.com and create a project where we can deploy the changes.

Linking your project​

note

There are a few commands required to link your project. We are in the process of consolidating these commands into a single command. Bear with us!

Let's associate your project with your remote project using supabase link and db remote set


supabase link 
# Use "supabase link --project-ref your-project-ref" to link your project in one step.

supabase db remote set 'postgresql://postgres:<your_password>@db.<your_project_ref>.supabase.co:5432/postgres'
# Use the connection string from your Supabase project here.

supabase db remote commit
# capture any changes that you have made to your database before setting up the CLI

You'll notice that supabase/migrations is now populated with a migration in ..._remote_commit.sql. This migration captures any changes required for your local database to match the schema of your remote Supabase project.

Deploying Database changes​

You can deploy any local database migrations using db push:

supabase db push

Deploying Edge Functions​

You can deploy any Edge Functions using functions deploy:

supabase functions deploy <function_name>

Limitations​

The local development environment is not as feature-complete as the Platform. Here are some of the differences:

  • The Storage interface is coming soon.
  • The Functions interface is coming soon.
  • Logs are not supported through the interface (however you can accesss them via the docker containers).
  • You cannot update your project settings via the Dashboard - this can be done using the CLI instead.

Next steps​