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.

## Getting started

### Prerequisites

You will need to have these in your environment:

- Git
- Docker (make sure the daemon is up and running)
- Supabase CLI (instructions [here](https://github.com/supabase/cli))

### Initialize your project 

```bash
# create your project folder
mkdir your-project

# move into the new folder
cd your-project

# start a new git repository
git init
```

This command will create an empty folder for your project and start a new git repository.

### Initialize Supabase

```bash
supabase init
```

This command will create a `supabase` folder which holds all the configuration for developing your project locally.

### Remote project 

We can link any local project to a remote database. Use the connection string from your Supabase project here.

```bash
supabase db remote set 'postgresql://postgres:<your_password>@db.<your_project_ref>.supabase.co:5432/postgres'
```

After that, run:

```bash
supabase db remote commit
```

This command captures 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 all the changes required on your local database to match the schema of your remote Supabase project.

### Start Supabase

```bash
supabase start
```

The `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.

### 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>

### Stop Supabase

```bash
supabase stop
```

Stop Supabase services and let's build a real application next.

## Migrations

You can also use the CLI to manage your migrations. 


## 2. Making database changes

To modify your local database, simply run some SQL against the `DB URL` shown by `supabase start`. 

For this example, we'll create a table called `employees`, using the "Supabase Studio" link provided. 
Open the Studio, navigate to the "SQL Editor" section, and then run the following SQL command:

```sql
create table employees (
	id serial primary key,
	name text
);
```

Now we have the `employees` table in the local database, but how do we incorporate this into migrations? The CLI can automatically detect changes by running:

```sh
supabase db commit create_employees
```

This will create a new migration named `<timestamp>_create_employees.sql` that represents any changes we've made to the local database since `supabase start`.

Let's add some sample data into the table. To do this we can use the seed script in `supabase/seed.sql`. 

```sql
-- in supabase/seed.sql
insert into employees (id, name) 
values 
  (1, 'Erlich Backman'), 
  (2, 'Richard Hendricks'),
  (3, '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`. 

## 3. 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
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.

## 4. Deploying migrations

Finally, we need to deploy these local changes to the remote database (i.e. your remote Supabase project). 
We can do this by running: 

```sh
supabase db push
```

## 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.io](https://app.supabase.io)