Skip to content

Commit

Permalink
docs(tour): update with new commands
Browse files Browse the repository at this point in the history
  • Loading branch information
soedirgo committed Nov 25, 2021
1 parent ff0ae0c commit a88f517
Showing 1 changed file with 19 additions and 13 deletions.
32 changes: 19 additions & 13 deletions examples/tour/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ If you are new to the Supabase CLI, or migration tools in general, it may not be

This tour assumes you have the following installed in your environment:

- git
- Node.js
- Git
- Node.js (>=14)
- Docker (make sure the daemon is up and running)
- A Postgres client (can be psql, SQL IDEs, etc.)
- Supabase CLI (follow the instructions [here](https://github.com/supabase/cli) to install)
Expand All @@ -22,13 +22,19 @@ The first thing we need to do is to initialize the Supabase CLI on the current p
supabase init
```

This will create a `supabase` directory which is managed by the CLI. Then we need to link the current project with the deploy database. Use the connection string from your Supabase project here.
This will create a `supabase` directory which is managed by the CLI. Then we need to link the current project with the remote database. Use the connection string from your Supabase project here.

```sh
supabase link --url 'postgresql://postgres:<your_password>@db.<your_project_ref>.supabase.co:5432/postgres'
supabase db remote set 'postgresql://postgres:<your_password>@db.<your_project_ref>.supabase.co:5432/postgres'
```

Why do we need to do this? Because if we want to manage a database with a migration tool, we need a _baseline_ where both the migration tool and the database have consistent schemas. `supabase link` does this synchronization between the two.
After that, run:

```sh
supabase db remote commit
```

Why do we need to do this? Because you may have modified your remote database's schema (e.g. using the Table Editor) after the project is set up. In that case we want to record these changes as applied migrations (i.e. they are not run again on the remote database). This is useful if you want to start using the CLI after playing a bit with the Supabase project.

You'll notice that `supabase/migrations` is now populated with 2 migrations: `..._init.sql` and `..._link.sql`. `..._init.sql` is automatically generated by the CLI, and `..._link.sql` performs the change needed so that your migrations reflect the schema of your Supabase project.

Expand Down Expand Up @@ -56,7 +62,7 @@ CREATE TABLE boarders(
Now we have the `boarders` table in the local database, but how do we incorporate this into migrations? If you've used other migration tools, you might be used to writing the migrations manually, but here we just need to run:

```sh
supabase db dump --name add_boarders
supabase db commit add_boarders
```

This will create a new migration named `<timestamp>_add_boarders.sql` that represents any changes we've done to the local database since `supabase start`.
Expand All @@ -71,13 +77,13 @@ INSERT INTO boarders(id, name) VALUES (1, 'Arthur Dent'), (2, 'Ford Prefect');
Now run the following to rerun the migration scripts and the seed script:

```sql
supabase db restore
supabase db reset
```

Then run the following:

```sh
npm clean-install
npm install
npm run start
```

Expand All @@ -92,23 +98,23 @@ What if we ran some nasty SQL on the local database and want to wipe it all clea
ALTER TABLE boarders ADD occupation text DEFAULT 'Hitchhiker';
```

No need to rerun `supabase start` here, just run:
For that we run:

```sh
supabase db restore
supabase db reset
```

And the local database will be reset.

## 4. Deploying migrations

Finally, we need to deploy all these local changes to the deploy database, i.e. the Supabase project DB. Once you're happy with your schema changes, run:
Finally, we need to deploy all these local changes to the remote database, i.e. the Supabase project DB. Once you're happy with your schema changes, run:

```sh
supabase deploy
supabase db push
```

Now you can check the table editor, and you'll see the changes are now live! There's no data of course, since we only had seed data.
Now you can check the table editor, and you'll see the changes are now live!

---

Expand Down

0 comments on commit a88f517

Please sign in to comment.