docs: improve database migrations guide (supabase#30914)

Author: sweatybridge

apps/docs/content/guides/deployment/database-migrations.mdx

@@ -3,28 +3,28 @@ id: 'database-migrations'
 title: 'Database Migrations'
 description: 'How to manage schema migrations for your Supabase project.'
 subtitle: 'How to manage schema migrations for your Supabase project.'
-video: 'https://www.youtube-nocookie.com/v/vyHyYpvjaks'
-tocVideo: 'vyHyYpvjaks'
+video: 'https://www.youtube-nocookie.com/v/Kx5nHBmIxyQ'
+tocVideo: 'Kx5nHBmIxyQ'
 ---
 
-Database schema changes are managed through "migrations". Database migrations are a common way of tracking changes to your database over time.
+Database migrations are SQL statements that create, update, or delete your existing database schemas. They are a common way of tracking changes to your database over time.
 
 ## Schema migrations
 
 For this guide, we'll create a table called `employees` and see how we can make changes to it.
 
+You will need to [install](/docs/guides/local-development#quickstart) the Supabase CLI and start the local development stack.
+
 <StepHikeCompact>
 
   <StepHikeCompact.Step step={1}>
     <StepHikeCompact.Details title="Create your first migration file">
-
       To get started, generate a [new migration](/docs/reference/cli/supabase-migration-new) to store the SQL needed to create our `employees` table.
-
     </StepHikeCompact.Details>
 
     <StepHikeCompact.Code>
 
-```bash
+```bash Terminal
 supabase migration new create_employees_table
 ```
 
@@ -37,18 +37,17 @@ supabase migration new create_employees_table
 
   <StepHikeCompact.Step step={2}>
     <StepHikeCompact.Details title="Add the SQL to your migration file">
-      This creates a new migration: supabase/migrations/\<timestamp\>
-        _create_employees_table.sql.
+      This creates a new migration file in supabase/migrations directory.
 
-        To that file, add the SQL to create this `employees` table
+      To that file, add the SQL to create this `employees` table.
     </StepHikeCompact.Details>
 
     <StepHikeCompact.Code>
 
-```sql
-create table employees (
+```sql supabase/migrations/<timestamp>_create_employees_table.sql
+create table if not exists employees (
   id bigint primary key generated always as identity,
-  name text,
+  name text not null,
   email text,
   created_at timestamptz default now()
 );
@@ -62,16 +61,16 @@ create table employees (
 <StepHikeCompact>
 
   <StepHikeCompact.Step step={3}>
-    <StepHikeCompact.Details title="Apply your migration">
-      Now that you have a migration file, you can run this migration and create the `employees` table.
+    <StepHikeCompact.Details title="Apply your first migration">
+      Run this migration to create the `employees` table.
 
-      Use the `reset` command here to reset the database to the current migrations
+      Now you can visit your new `employees` table in the local Dashboard.
     </StepHikeCompact.Details>
 
     <StepHikeCompact.Code>
 
-```bash
-supabase db reset
+```bash Terminal
+supabase migration up
 ```
 
     </StepHikeCompact.Code>
@@ -83,15 +82,13 @@ supabase db reset
 
   <StepHikeCompact.Step step={4}>
     <StepHikeCompact.Details title="Modify your employees table">
-      Now you can visit your new `employees` table in the Dashboard.
-
-      Next, modify your `employees` table by adding a column for department. Create a new migration file for that.
+      Next, modify your `employees` table by adding a column for `department`.
     </StepHikeCompact.Details>
 
     <StepHikeCompact.Code>
 
-```bash
-supabase migration new add_department_to_employees_table
+```bash Terminal
+supabase migration new add_department_column
 ```
 
     </StepHikeCompact.Code>
@@ -103,15 +100,12 @@ supabase migration new add_department_to_employees_table
 
   <StepHikeCompact.Step step={5}>
     <StepHikeCompact.Details title="Add a new column to your table">
-      This creates a new migration file: supabase/migrations/\<timestamp\>
-        _add_department_to_employees_table.sql.
-
-        To that file, add the SQL to create a new department column
+      To that new migration file, add the SQL to create a new `department` column.
     </StepHikeCompact.Details>
 
     <StepHikeCompact.Code>
 
-```sql
+```sql supabase/migrations/<timestamp>_add_department_column.sql
 alter table if exists public.employees
 add department text default 'Hooli';
 ```
@@ -121,22 +115,44 @@ add department text default 'Hooli';
   </StepHikeCompact.Step>
 </StepHikeCompact>
 
-### Add sample data
+<StepHikeCompact>
 
-Now that you are managing your database with migrations scripts, it would be great have some seed data to use every time you reset the database.
+  <StepHikeCompact.Step step={6}>
+    <StepHikeCompact.Details title="Apply your second migration">
+      Run this migration to update your existing `employees` table.
+    </StepHikeCompact.Details>
 
-For this, you can create a seed script in `supabase/seed.sql`.
+    <StepHikeCompact.Code>
+
+```bash Terminal
+supabase migration up
+```
+
+    </StepHikeCompact.Code>
+
+  </StepHikeCompact.Step>
+</StepHikeCompact>
+
+Finally, you should see the `department` column added to your `employees` table in the local Dashboard.
+
+View the [complete code](https://github.com/supabase/supabase/tree/master/examples/database/employees) for this example.
+
+### Seeding data
+
+Now that you are managing your database with migrations scripts, it would be great have some seed data to use every time you reset the database.
 
 <StepHikeCompact>
 
   <StepHikeCompact.Step step={1}>
     <StepHikeCompact.Details title="Populate your table">
-      Insert data into your `employees` table with your `supabase/seed.sql` file.
+      Create a seed script in supabase/seed.sql.
+
+      To that file, add the SQL to insert data into your `employees` table.
     </StepHikeCompact.Details>
 
     <StepHikeCompact.Code>
 
-```sql
+```sql supabase/seed.sql
 insert into public.employees
   (name)
 values
@@ -154,7 +170,7 @@ values
 
   <StepHikeCompact.Step step={2}>
     <StepHikeCompact.Details title="Reset your database">
-      Reset your database (apply current migrations), and populate with seed data
+      Reset your database to reapply migrations and populate with seed data.
     </StepHikeCompact.Details>
 
     <StepHikeCompact.Code>
@@ -198,60 +214,62 @@ The last step is deploying these changes to a live Supabase project.
 
 ## Deploy your project
 
-You've been developing your project locally, making changes to your tables via migrations. It's time to deploy your project to the Supabase Platform and start scaling up to millions of users! Head over to [Supabase](https://supabase.com/dashboard) and create a new project to deploy to.
+You've been developing your project locally, making changes to your tables via migrations. It's time to deploy your project to the Supabase Platform and start scaling up to millions of users!
 
-### Log in to the Supabase CLI
+Head over to [Supabase](https://supabase.com/dashboard) and create a new project to deploy to.
 
-<CH.Code>
+<StepHikeCompact>
+
+  <StepHikeCompact.Step step={1}>
+    <StepHikeCompact.Details title="Log in to the Supabase CLI">
+      [Login](/docs/reference/cli/usage#supabase-login) to the Supabase CLI using an auto-generated Personal Access Token.
+    </StepHikeCompact.Details>
+
+    <StepHikeCompact.Code>
 
 ```bash Terminal
 supabase login
 ```
 
-```bash npx
-npx supabase login
-```
-
-</CH.Code>
-
-### Link your project
-
-Associate your project with your remote project using [`supabase link`](/docs/reference/cli/usage#supabase-link).
-
-```bash
-supabase link --project-ref <project-id>
-# You can get <project-id> from your project's dashboard URL: https://supabase.com/dashboard/project/<project-id>
+    </StepHikeCompact.Code>
 
-supabase db pull
-# Capture any changes that you have made to your remote database before you went through the steps above
-# If you have not made any changes to the remote database, skip this step
-```
+  </StepHikeCompact.Step>
+</StepHikeCompact>
 
-`supabase/migrations` is now populated with a migration in `<timestamp>_remote_schema.sql`.
-This migration captures any changes required for your local database to match the schema of your remote Supabase project.
+<StepHikeCompact>
 
-Review the generated migration file and once happy, apply the changes to your local instance:
+  <StepHikeCompact.Step step={2}>
+    <StepHikeCompact.Details title="Link your project">
+      [Link](/docs/reference/cli/usage#supabase-link) to your remote project by selecting from the on-screen prompt.
+    </StepHikeCompact.Details>
 
-```bash
-# To apply the new migration to your local database:
-supabase migration up
+    <StepHikeCompact.Code>
 
-# To reset your local database completely:
-supabase db reset
+```bash Terminal
+supabase link
 ```
 
-<Admonition type="note">
+    </StepHikeCompact.Code>
 
-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!
+  </StepHikeCompact.Step>
+</StepHikeCompact>
 
-</Admonition>
+<StepHikeCompact>
 
-### Deploy database changes
+  <StepHikeCompact.Step step={3}>
+    <StepHikeCompact.Details title="Deploy database changes">
+      [Push](/docs/reference/cli/usage#supabase-db-push) your migrations to the remote database.
+    </StepHikeCompact.Details>
 
-Deploy any local database migrations using [`db push`](/docs/reference/cli/usage#supabase-db-push):
+    <StepHikeCompact.Code>
 
-```sh
+```bash Terminal
 supabase db push
 ```
 
-Visiting your live project on [Supabase](https://supabase.com/dashboard), you'll see a new `employees` table, complete with the `department` column you added in the second migration above.
+    </StepHikeCompact.Code>
+
+  </StepHikeCompact.Step>
+</StepHikeCompact>
+
+Visiting your live project on [Supabase](https://supabase.com/dashboard/project/_), you'll see a new `employees` table, complete with the `department` column you added in the second migration above.

examples/database/employees/supabase/.gitignore

@@ -0,0 +1,4 @@
+# Supabase
+.branches
+.temp
+.env

examples/database/employees/supabase/config.toml

@@ -0,0 +1,21 @@
+# For detailed configuration reference documentation, visit:
+# https://supabase.com/docs/guides/local-development/cli/config
+# A string used to distinguish different Supabase projects on the same host. Defaults to the
+# working directory name when running `supabase init`.
+project_id = "employees"
+
+[db]
+# Port to use for the local database URL.
+port = 54322
+# Port used by db diff command to initialize the shadow database.
+shadow_port = 54320
+# The database major version to use. This has to be the same as your remote database's. Run `SHOW
+# server_version;` on the remote database to check.
+major_version = 15
+
+[db.seed]
+# If enabled, seeds the database after migrations during a db reset.
+enabled = true
+# Specifies an ordered list of seed files to load during db reset.
+# Supports glob patterns relative to supabase directory: `./seeds/*.sql'
+sql_paths = ['./seed.sql']

examples/database/employees/supabase/migrations/20241205075911_create_employees_table.sql

@@ -0,0 +1,6 @@
+create table if not exists employees (
+  id bigint primary key generated always as identity,
+  name text not null,
+  email text,
+  created_at timestamptz default now()
+);

examples/database/employees/supabase/migrations/20241205080043_add_department_to_employees_table.sql

@@ -0,0 +1,2 @@
+alter table if exists public.employees
+add department text default 'Hooli';

examples/database/employees/supabase/seed.sql

@@ -0,0 +1,6 @@
+insert into public.employees
+  (name)
+values
+  ('Erlich Bachman'),
+  ('Richard Hendricks'),
+  ('Monica Hall');