From 58d0b83d7d7e747870878fa412cdcbcc3e29f5cd Mon Sep 17 00:00:00 2001
From: Terry Sutton <saltcod@gmail.com>
Date: Wed, 15 Mar 2023 16:13:09 +0800
Subject: [PATCH] Update local development guide

---
 .../pages/guides/cli/local-development.mdx    | 103 +++++++++++-------
 1 file changed, 66 insertions(+), 37 deletions(-)

diff --git a/apps/docs/pages/guides/cli/local-development.mdx b/apps/docs/pages/guides/cli/local-development.mdx
index 0514e6b108a..72850146edc 100644
--- a/apps/docs/pages/guides/cli/local-development.mdx
+++ b/apps/docs/pages/guides/cli/local-development.mdx
@@ -7,7 +7,23 @@ export const meta = {
   video: 'https://www.youtube.com/v/vyHyYpvjaks',
 }
 
-Learn how to use the Supabase CLI to develop your project locally and deploy to the Supabase Platform.
+Once you've moved beyond the initial "clicking around" stage and are ready to start building your project, we suggest following a workflow that involves working locally and deploying your changes to a linked project on the [Supabase Platform](https://app.supabase.io/).
+
+Doing things directly on the platform via the [Dashboard](https://app.supabase.io/) is fine when you're getting started, but it's a good idea to move to a proper local workflow before you get too far. We'll get into all of the details, but the gist is that you'll work locally, generate migrations as you change your tables, and apply those migrations to a linked project on the [Platform](https://app.supabase.io/).
+
+## Why develop locally?
+
+The Dashboard provides a wide range of features for setting up your project: creating tables, adding columns, changing existing columns, creating views, and more. Given all of the Dashboard's capabilities, you might question the need to work locally. Here's a few advantages to working this way:
+
+1. **Faster Development**: Developing your project locally allows you to work without any network latency or internet disruptions.
+
+2. **Easier Collaboration**: Developing your project locally can make it easier to collaborate with others on the same project.
+
+3. **Cost-Effective**: While Supabase provides a generous free tier and gives you two free projects to get started, you may be working on many projects at once. Developing locally means that you can spin up unlimited projects locally and only link them with live projects when you're ready to launch.
+
+4. **Configuration in code**: If you directly change your tables via the Dashboard, none of that is captured in code. If you follow these local development practices, you'll store all of your table schemas in code.
+
+5. **Work offline**: Need to work from a train? A plain? An automobile? No problem. Developing your project locally allows you to work offline.
 
 <div className="video-container">
   <iframe
@@ -49,7 +65,7 @@ mkdir your-project
 # move into the new folder
 cd your-project
 
-# start a new git repository
+# start a new git repository — important, don't skip this step
 git init
 ```
 
@@ -68,12 +84,26 @@ This command may take a while to run if this is the first time using the CLI.
 supabase start
 ```
 
-Once all of the Supabase services are running, you'll see output containing your local Supabase credentials.
-You can use the [stop](/docs/reference/cli/usage#supabase-stop) command at any time to stop all services.
+Once all of the Supabase services are running, you'll see output containing your local Supabase credentials. It should look like this, with urls and keys that you'll use in your local project:
 
-## Access services
+```
 
-You can access services directly with any Postgres client or through the API Gateway ([Kong](https://github.com/Kong/kong)).
+Started supabase local development setup.
+
+         API URL: http://localhost:54321
+          DB URL: postgresql://postgres:postgres@localhost:54322/postgres
+      Studio URL: http://localhost:54323
+    Inbucket URL: http://localhost:54324
+        anon key: eyJh......
+service_role key: eyJh......
+
+```
+
+You can use the [supabase stop](/docs/reference/cli/usage#supabase-stop) command at any time to stop all services.
+
+## Access your project's services
+
+You can access these services directly with any Postgres client or through the API Gateway ([Kong](https://github.com/Kong/kong)).
 
 <Tabs
   scrollable
@@ -149,7 +179,15 @@ Database changes are managed through "migrations." Database migrations are a com
 
 ### Make database changes
 
-For this guide, create a table called `employees`. In Supabase Studio, navigate to the **SQL Editor** page and run the following SQL command:
+For this guide, we'll create a table called `employees` and see how we can make changes to it.
+
+To get started, generate a [new migration](https://supabase.com/docs/reference/cli/supabase-migration-new) to store the SQL needed to create our `employees` table:
+
+```bash
+supabase migration new create_employees_table
+```
+
+This creates a new migration named `supabase/migrations/<timestamp>_create_employees_table.sql`. To that file, add the SQL to create this `employees` table:
 
 ```sql
 create table
@@ -159,28 +197,35 @@ create table
   );
 ```
 
-<Admonition type="note">
+Now that we have a migration file, we can run this migration and create our `employees` table. We use the `reset` command here to reset the database to the current migrations:
 
-You can execute any SQL using the `DB URL` shown by [`supabase status`](/docs/reference/cli/usage#supabase-status).
-
-</Admonition>
-
-Run the [`db diff`](/docs/reference/cli/usage#supabase-db-diff) command to detect changes in the local database:
-
-```sh
-supabase db diff create_employees -f create_employees
+```bash
+supabase db reset
 ```
 
-This creates a new migration named `supabase/migrations/<timestamp>_create_employees.sql`, representing any changes made to the local database since [`supabase start`](/docs/reference/cli/usage#supabase-start).
+Now you can visit your new `employees` table in the Dashboard.
+
+Next, let's modify our `employees` table by adding a column for department. Let's create a new migration file for that:
+
+```bash
+supabase migration new add_department_to_employees_table
+```
+
+This creates a new migration named `supabase/migrations/<timestamp>_add_department_to_employees_table.sql`. To that file, add the SQL to create a new department column:
+
+```sql
+alter table
+  if exists public.employees add department text default 'Hooli';
+```
 
 ### Add sample data
 
 Use the seed script in `supabase/seed.sql` (created with [`supabase init`](/docs/reference/cli/usage#supabase-init)) to add sample data to the table.
 
 ```sql
--- in supabase/seed.sql
-insert into public.employees
-  (name)
+ -- in supabase/seed.sql
+insert into
+  public.employees (name)
 values
   ('Erlich Bachman'),
   ('Richard Hendricks'),
@@ -193,23 +238,7 @@ Rerun the migration and seed scripts:
 supabase db reset
 ```
 
-You should now see the contents of `employees` in Studio.
-
-### Reset database changes
-
-Use the [`reset`](/docs/reference/cli/usage#supabase-db-reset) command to revert any changes to the local database.
-
-```sql
--- run on local database to make a change
-alter table employees
-add department text default 'Hooli';
-```
-
-Run the following command to reset the local database:
-
-```sh
-supabase db reset
-```
+You should now see the contents of `employees` in Studio. All of your database changes are captured in code, and you can reset to a known state at any time, complete with seed data.
 
 ## Deploy your project