diff --git a/apps/docs/content/guides/deployment/database-migrations.mdx b/apps/docs/content/guides/deployment/database-migrations.mdx
index 3ad7b9f478..11059b17bd 100644
--- a/apps/docs/content/guides/deployment/database-migrations.mdx
+++ b/apps/docs/content/guides/deployment/database-migrations.mdx
@@ -135,7 +135,11 @@ supabase migration up
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.
+
+
+View the [complete code](https://github.com/supabase/supabase/tree/master/examples/database/employees) for this example on GitHub.
+
+
### Seeding data
@@ -175,7 +179,7 @@ values
-```bash
+```bash Terminal
supabase db reset
```
@@ -190,25 +194,67 @@ You should now see the `employees` table, along with your seed data in the Dashb
This workflow is great if you know SQL and are comfortable creating tables and columns. If not, you can still use the Dashboard to create tables and columns, and then use the CLI to diff your changes and create migrations.
-Create a new table called `cities`, with columns `id`, `name` and `population`. To see the corresponding SQL for this, you can use the `supabase db diff --schema public` command. This will show you the SQL that will be run to create the table and columns. The output of `supabase db diff` will look something like this:
+
+
+
+ Create a new table called `cities`, with columns `id`, `name` and `population`.
+
+ Then generate a [schema diff](/docs/reference/cli/supabase-db-diff).
+
+
+
+
+```bash Terminal
+supabase db diff -f create_cities_table
```
-Diffing schemas: public
-Finished supabase db diff on branch main.
+
+
+
+
+
+
+
+
+
+ A new migration file is created for you.
+
+ Alternately, you can copy the table definitions directly from the Table Editor.
+
+
+
+
+```sql supabase/migrations/_create_cities_table.sql
create table "public"."cities" (
"id" bigint primary key generated always as identity,
"name" text,
"population" bigint
);
-
```
-Alternately, you can view your table definitions directly from the Table Editor:
+
-
+
+
-You can then copy this SQL into a new migration file, and run `supabase db reset` to apply the changes.
+
+
+
+
+ Test your new migration file by resetting your local database.
+
+
+
+
+```bash Terminal
+supabase db reset
+```
+
+
+
+
+
The last step is deploying these changes to a live Supabase project.
@@ -222,7 +268,7 @@ Head over to [Supabase](https://supabase.com/dashboard) and create a new project
- [Login](/docs/reference/cli/usage#supabase-login) to the Supabase CLI using an auto-generated Personal Access Token.
+ [Login](/docs/reference/cli/supabase-login) to the Supabase CLI using an auto-generated Personal Access Token.
@@ -240,7 +286,7 @@ supabase login
- [Link](/docs/reference/cli/usage#supabase-link) to your remote project by selecting from the on-screen prompt.
+ [Link](/docs/reference/cli/supabase-link) to your remote project by selecting from the on-screen prompt.
@@ -258,7 +304,7 @@ supabase link
- [Push](/docs/reference/cli/usage#supabase-db-push) your migrations to the remote database.
+ [Push](/docs/reference/cli/supabase-db-push) your migrations to the remote database.
diff --git a/examples/database/employees/README.md b/examples/database/employees/README.md
new file mode 100644
index 0000000000..4692b41da2
--- /dev/null
+++ b/examples/database/employees/README.md
@@ -0,0 +1,17 @@
+# Database Migrations
+
+This example uses Supabase CLI as a migration tool to manage your database schema changes.
+
+## Local development
+
+```bash
+npx supabase db start
+```
+
+## Push to remote project
+
+```bash
+npx supabase login
+npx supabase link
+npx supabase db push
+```