Skip to main content

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:

Log in to the Supabase CLI​

supabase login

Initialize your project​

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

# create your project folder
mkdir your-project

# move into the new folder
cd your-project

# start a new git repository
git init

Start Supabase services​

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

supabase 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.

supabase 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

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'
note

To access the database from an edge function in your local Supabase setup, replace localhost with host.docker.internal.

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
);
note

You can execute any SQL using the DB URL shown by supabase status.

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 Backman'),
  ('Richard Hendricks'),
  ('Monica Hall');

Rerun the migration and seed scripts:

supabase 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.

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!

Associate your project with your remote project using supabase link.

supabase link --project-ref <project-id>
# You can get <project-id> from your project’s dashboard URL: https://app.supabase.com/project/<project-id>

supabase db remote commit
# 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 Storage interface is coming soon.
  • 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.