supabase/web/docs/guides/local-development.mdx

---
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 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/guides/cli)

### 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) and [db remote set](/docs/reference/cli/supabase-db-remote-set)


```bash

supabase link 
# Use "supabase link --project-ref your-project-ref" to link your project in one step.

supabase db remote set 'postgresql://postgres:<your_password>@db.<your_project_ref>.supabase.co:5432/postgres'
# Use the connection string from your Supabase project here.

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)