mirror of
https://github.com/supabase/supabase.git
synced 2026-07-02 06:44:35 +08:00
225 lines
6.2 KiB
Plaintext
225 lines
6.2 KiB
Plaintext
---
|
||
id: local-development
|
||
title: Local Development
|
||
description: How to use Supabase on your local development machine.
|
||
---
|
||
|
||
import Tabs from '@theme/Tabs'
|
||
import TabItem from '@theme/TabItem'
|
||
|
||
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](https://docs.docker.com/engine/install/)
|
||
- [Git](https://github.com/git-guides/install-git)
|
||
- [Supabase CLI](/docs/guides/cli)
|
||
|
||
## Log in to the Supabase CLI
|
||
|
||
```bash
|
||
supabase login
|
||
```
|
||
|
||
## Initialize your project
|
||
|
||
Create a new folder for your project and start a new git repository:
|
||
|
||
```bash
|
||
# 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](/reference/cli/usage#supabase-init) Supabase to set up the configuration for developing your project locally:
|
||
|
||
```bash
|
||
supabase init
|
||
```
|
||
|
||
Make sure Docker is running. The [start](/reference/cli/usage#supabase-start) command uses Docker to start the Supabase [services](/architecture).
|
||
This command may take a while to run if this is the first time using the CLI.
|
||
|
||
```bash
|
||
supabase start
|
||
```
|
||
|
||
Once all of the Supabase services are running, you'll see output containing your local Supabase credentials.
|
||
You can use the [stop](/reference/cli/usage#supabase-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](https://github.com/Kong/kong)).
|
||
|
||
<Tabs
|
||
defaultValue="postgres"
|
||
values={[
|
||
{label: 'Postgres', value: 'postgres'},
|
||
{label: 'API Gateway', value: 'kong'},
|
||
]}>
|
||
<TabItem value="postgres">
|
||
|
||
```sh
|
||
# Default URL:
|
||
postgresql://postgres:postgres@localhost:54322/postgres
|
||
```
|
||
|
||
The local Postgres instance can be accessed through [`psql`](https://www.postgresql.org/docs/current/app-psql.html)
|
||
or any other Postgres client, such as [pgadmin](https://www.pgadmin.org/).
|
||
|
||
For example:
|
||
|
||
```bash
|
||
psql 'postgresql://postgres:postgres@localhost:54322/postgres'
|
||
```
|
||
|
||
</TabItem>
|
||
<TabItem value="kong">
|
||
|
||
```sh
|
||
# Default URL:
|
||
http://localhost:54321
|
||
```
|
||
|
||
If you are accessing these services without the client libraries, you may need to pass the client keys as an `Authorization` header.
|
||
Learn more about JWT headers in our [Resources](/learn/auth-deep-dive/auth-deep-dive-jwts).
|
||
|
||
```sh
|
||
curl 'http://localhost:54321/rest/v1/' \
|
||
-H "apikey: <anon key>" \
|
||
-H "Authorization: Bearer <anon key>"
|
||
|
||
http://localhost:54321/rest/v1/ # REST (PostgREST)
|
||
http://localhost:54321/realtime/v1/ # Realtime
|
||
http://localhost:54321/storage/v1/ # Storage
|
||
http://localhost:54321/auth/v1/ # Auth (GoTrue)
|
||
```
|
||
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
:::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:
|
||
|
||
```sql
|
||
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`](/reference/cli/usage#supabase-status).
|
||
:::
|
||
|
||
Run the [`db diff`](/reference/cli/usage#supabase-db-diff) command to detect changes in the local database:
|
||
|
||
```sh
|
||
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`](/reference/cli/usage#supabase-start).
|
||
|
||
### Add sample data
|
||
|
||
Use the seed script in `supabase/seed.sql` (created with [`supabase init`](/reference/cli/usage#supabase-init)) to add sample data to the table.
|
||
|
||
```sql
|
||
-- in supabase/seed.sql
|
||
insert into public.employees (name)
|
||
values
|
||
('Erlich Backman'),
|
||
('Richard Hendricks'),
|
||
('Monica Hall');
|
||
```
|
||
|
||
Rerun the migration and seed scripts:
|
||
|
||
```bash
|
||
supabase db reset
|
||
```
|
||
|
||
You should now see the contents of `employees` in Studio.
|
||
|
||
### Reset database changes
|
||
|
||
Use the [`reset`](/reference/cli/usage#supabase-db-reset) command to revert any changes to the local database.
|
||
|
||
```sql
|
||
-- 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:
|
||
|
||
```sh
|
||
supabase db reset
|
||
```
|
||
|
||
## Deploy your project
|
||
|
||
Go to the [Supabase Dashboard](https://app.supabase.com) 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`](/reference/cli/usage#supabase-link).
|
||
|
||
```bash
|
||
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`](/reference/cli/usage#supabase-db-push):
|
||
|
||
```sh
|
||
supabase db push
|
||
```
|
||
|
||
### Deploy Edge Functions
|
||
|
||
Deploy any Edge Functions using [`functions deploy`](/reference/cli/usage#supabase-functions-deploy):
|
||
|
||
```sh
|
||
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.
|