From b6e6ad568ea2fa38eba0846d71475da01f93f84f Mon Sep 17 00:00:00 2001
From: Copple <10214025+kiwicopple@users.noreply.github.com>
Date: Tue, 22 Mar 2022 13:36:38 +0100
Subject: [PATCH] Cleans up some remaining items in the CLI tour

---
 web/docs/guides/local-development.mdx | 60 ++++++++++++++-------------
 1 file changed, 31 insertions(+), 29 deletions(-)

diff --git a/web/docs/guides/local-development.mdx b/web/docs/guides/local-development.mdx
index a64b1b7159f..c030ca4973a 100644
--- a/web/docs/guides/local-development.mdx
+++ b/web/docs/guides/local-development.mdx
@@ -55,12 +55,11 @@ After that, run:
 ```bash
 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.
+
+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 performs the change needed so that your migrations reflect the schema of your Supabase project.
+This migration captures all the changes required on your local database to match the schema of your remote Supabase project.
 
 ### Start Supabase
 
@@ -68,9 +67,10 @@ This migration performs the change needed so that your migrations reflect the sc
 supabase start
 ```
 
-This command uses Docker to start all the open source [services](/docs/#how-it-works) of Supabase. This command will take a while to run, there are a lot of services to build.
+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 this is running, you will see an output that contains your local Supabase credentials.
+Once all of the Supabase services are running, you'll see an output that contains your local Supabase credentials.
 
 ### Accessing Services Directly
 
@@ -135,57 +135,58 @@ Stop Supabase services and let's build a real application next.
 You can also use the CLI to manage your migrations. 
 
 
-## 2. Making schema changes
+## 2. Making database changes
 
-To change the schema for the local database, simply run some SQL against the `DB URL` shown by `supabase start`. For the tour, we'll run these changes using a Postgres client of your choice:
+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 boarders(
-	id int4 PRIMARY KEY,
+create table employees (
+	id serial primary key,
 	name text
 );
 ```
 
-Now we have the `boarders` table in the local database, but how do we incorporate this into migrations? The CLI can automatically detect changes by running:
+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 add_boarders
+supabase db commit create_employees
 ```
 
-This will create a new migration named `<timestamp>_add_boarders.sql` that represents any changes we've made to the local database since `supabase start`.
+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 boarders(id, name) VALUES (1, 'Arthur Dent'), (2, 'Ford Prefect');
+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:
 
-```sql
+```bash
 supabase db reset
 ```
 
-Then run the following:
+If you look again within Studio, you should now see the contents of `employees`. 
 
-```sh
-npm install
-npm run start
-```
+## 3. Resetting database changes
 
-You should now see the contents of `boarders`. 
-
-## 3. Resetting schema changes
-
-If you run some SQL on the local database which you want to revert, you can use the `reset` command.
+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 boarders ADD occupation text DEFAULT 'Hitchhiker';
+alter table employees 
+  add department text default 'Hooli';
 ```
 
-For that we run:
+To revert this change we can run:
 
 ```sh
 supabase db reset
@@ -195,7 +196,8 @@ And the local database will be reset.
 
 ## 4. Deploying migrations
 
-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:
+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
@@ -203,6 +205,6 @@ supabase db push
 
 ## Next steps
 
-- Got a question? [Ask here](https://github.com/supabase/supabase/discussions).
+- 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)