mirror of
https://github.com/supabase/supabase.git
synced 2026-07-04 22:15:46 +08:00
252 lines
7.2 KiB
Plaintext
252 lines
7.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'
|
||
|
||
Supabase provides a [CLI](https://github.com/supabase/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](https://github.com/git-guides/install-git)
|
||
- Docker (make sure this is running). [Docs](https://docs.docker.com/engine/install/)
|
||
- Supabase CLI. [Docs](/docs/reference/cli/installing-and-updating)
|
||
|
||
### Supabase CLI login
|
||
|
||
After installing the Supabase CLI you can [log in](/docs/reference/cli/supabase-login) using your Supabase account (sign up at [app.supabase.com](https://app.supabase.com)).
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
# 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](/docs/reference/cli/supabase-init) Supabase inside the folder that you created:
|
||
|
||
```bash
|
||
supabase init
|
||
```
|
||
|
||
This command will create a `supabase` folder which holds all the configuration for developing your project locally.
|
||
|
||
## Developing Locally
|
||
|
||
### Start Supabase
|
||
|
||
```bash
|
||
supabase start
|
||
```
|
||
|
||
The [start](/docs/reference/cli/supabase-start) command uses Docker to start the open source [services](/docs/#how-it-works) 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](/docs/reference/cli/supabase-stop) command at any time to stop all services.
|
||
|
||
### Accessing Services Directly
|
||
|
||
<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
|
||
```
|
||
|
||
All of the services are accessible through the API Gateway [Kong](https://github.com/Kong/kong)).
|
||
If you are accessing these services without the client libraries, you may need to pass the client keys as an `Authorization` header.
|
||
You can learn more about these JWT headers in our [Resources](/docs/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>
|
||
|
||
### 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:
|
||
|
||
```sql
|
||
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](/docs/reference/cli/supabase-db-commit) command:
|
||
|
||
```sh
|
||
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`).
|
||
|
||
```sql
|
||
-- 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:
|
||
|
||
```bash
|
||
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.
|
||
|
||
```sql
|
||
-- run on local database to make a change
|
||
alter table employees
|
||
add department text default 'Hooli';
|
||
```
|
||
|
||
To revert this change we can run:
|
||
|
||
```sh
|
||
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](https://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](/docs/guides/local-development).
|
||
|
||
```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
|
||
```
|
||
|
||
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`](/docs/reference/cli/supabase-db-push):
|
||
|
||
```sh
|
||
supabase db push
|
||
```
|
||
|
||
### Deploying Edge Functions
|
||
|
||
You can deploy any Edge Functions using [`functions deploy`](/docs/reference/cli/supabase-functions-deploy):
|
||
|
||
```sh
|
||
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
|
||
|
||
- Got a question? [Ask in our Discussions](https://github.com/supabase/supabase/discussions).
|
||
- CLI repository: [GitHub](https://github.com/supabase/cli).
|
||
- Sign in: [app.supabase.com](https://app.supabase.com)
|