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#
1supabase login
note
If you installed the Supabase CLI via NPM you may have to use npx supabase 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
The local Postgres instance can be accessed through psql
or any other Postgres client, such as pgadmin.
For example:
1psql '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 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#
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
.
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.