Local Development

Learn how to use the Supabase CLI to develop your project locally and deploy to the Supabase Platform.

Prerequisites#

Make sure you have these installed on your local machine:

• Docker
• Git
• Supabase CLI

Log in to the Supabase CLI#

1supabase login

Initialize your project#

Create a new folder for your project and start a new git repository:

1# create your project folder
2mkdir your-project
3
4# move into the new folder
5cd your-project
6
7# start a new git repository
8git init

Start Supabase services#

Initialize Supabase to set up the configuration for developing your project locally:

1supabase init

Make sure Docker is running. The start command uses Docker to start the Supabase services. This command may take a while to run if this is the first time using the CLI.

1supabase start

Once all of the Supabase services are running, you'll see output containing your local Supabase credentials. You can use the stop command at any time to stop all services.

Access services#

You can access services directly with any Postgres client or through the API Gateway (Kong).

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

1psql '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.

Make database changes#

For this guide, create a table called employees. In Supabase Studio, navigate to the SQL Editor page and run the following SQL command:

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

Run the db diff command to detect changes in the local database:

supabase db diff create_employees -f create_employees

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

Add sample data#

Use the seed script in supabase/seed.sql (created with supabase init) to add sample data to the table.

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

Rerun the migration and seed scripts:

1supabase db reset

You should now see the contents of employees in Studio.

Reset database changes#

Use the reset command to revert any changes to the local database.

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

Run the following command to reset the local database:

supabase db reset

Deploy your project#

Go to the Supabase Dashboard and create a project to deploy the changes.

Link your project#

Associate your project with your remote project using supabase link.

1supabase link --project-ref <project-id>
2# You can get <project-id> from your project’s dashboard URL: https://app.supabase.com/project/<project-id>
3
4supabase db remote commit
5# Capture any changes that you have made to your database before setting up the CLI

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.

Deploy database changes#

Deploy any local database migrations using db push:

supabase db push

Deploy Edge Functions#

Deploy any Edge Functions using functions deploy:

supabase functions deploy <function_name>

Limitations#

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

• The Functions interface is coming soon.
• Logs are not supported through the interface (however you can access them through the Docker containers).
• You cannot update your project settings in the Dashboard—this must be done using the CLI.