From 67e12df620ae67f4ad159c1f5668fd5a82b08710 Mon Sep 17 00:00:00 2001 From: Han Qiao Date: Thu, 5 Dec 2024 23:43:43 +0800 Subject: [PATCH] docs: improve database migrations guide (#30914) --- .../guides/deployment/database-migrations.mdx | 164 ++++++++++-------- .../database/employees/supabase/.gitignore | 4 + .../database/employees/supabase/config.toml | 21 +++ .../20241205075911_create_employees_table.sql | 6 + ...0043_add_department_to_employees_table.sql | 2 + examples/database/employees/supabase/seed.sql | 6 + 6 files changed, 130 insertions(+), 73 deletions(-) create mode 100644 examples/database/employees/supabase/.gitignore create mode 100644 examples/database/employees/supabase/config.toml create mode 100644 examples/database/employees/supabase/migrations/20241205075911_create_employees_table.sql create mode 100644 examples/database/employees/supabase/migrations/20241205080043_add_department_to_employees_table.sql create mode 100644 examples/database/employees/supabase/seed.sql diff --git a/apps/docs/content/guides/deployment/database-migrations.mdx b/apps/docs/content/guides/deployment/database-migrations.mdx index 0f9ba80f34d..3ad7b9f4784 100644 --- a/apps/docs/content/guides/deployment/database-migrations.mdx +++ b/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. + - To get started, generate a [new migration](/docs/reference/cli/supabase-migration-new) to store the SQL needed to create our `employees` table. - -```bash +```bash Terminal supabase migration new create_employees_table ``` @@ -37,18 +37,17 @@ supabase migration new create_employees_table - This creates a new migration: supabase/migrations/\ - _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. -```sql -create table employees ( +```sql supabase/migrations/_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 ( - - Now that you have a migration file, you can run this migration and create the `employees` table. + + 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. -```bash -supabase db reset +```bash Terminal +supabase migration up ``` @@ -83,15 +82,13 @@ supabase db reset - 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`. -```bash -supabase migration new add_department_to_employees_table +```bash Terminal +supabase migration new add_department_column ``` @@ -103,15 +100,12 @@ supabase migration new add_department_to_employees_table - This creates a new migration file: supabase/migrations/\ - _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. -```sql +```sql supabase/migrations/_add_department_column.sql alter table if exists public.employees add department text default 'Hooli'; ``` @@ -121,22 +115,44 @@ add department text default 'Hooli'; -### Add sample data + + + + + Run this migration to update your existing `employees` table. + + + + +```bash Terminal +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. + +### 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. -For this, you can create a seed script in `supabase/seed.sql`. - - 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. -```sql +```sql supabase/seed.sql insert into public.employees (name) values @@ -154,7 +170,7 @@ values - Reset your database (apply current migrations), and populate with seed data + Reset your database to reapply migrations and populate with seed data. @@ -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. - + + + + + [Login](/docs/reference/cli/usage#supabase-login) to the Supabase CLI using an auto-generated Personal Access Token. + + + ```bash Terminal supabase login ``` -```bash npx -npx supabase login + + + + + + + + + + [Link](/docs/reference/cli/usage#supabase-link) to your remote project by selecting from the on-screen prompt. + + + + +```bash Terminal +supabase link ``` - + -### Link your project + + -Associate your project with your remote project using [`supabase link`](/docs/reference/cli/usage#supabase-link). + -```bash -supabase link --project-ref -# You can get from your project's dashboard URL: https://supabase.com/dashboard/project/ + + + [Push](/docs/reference/cli/usage#supabase-db-push) your migrations to the remote database. + -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 -``` + -`supabase/migrations` is now populated with a migration in `_remote_schema.sql`. -This migration captures any changes required for your local database to match the schema of your remote Supabase project. - -Review the generated migration file and once happy, apply the changes to your local instance: - -```bash -# To apply the new migration to your local database: -supabase migration up - -# To reset your local database completely: -supabase db reset -``` - - - -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! - - - -### Deploy database changes - -Deploy any local database migrations using [`db push`](/docs/reference/cli/usage#supabase-db-push): - -```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. + + + + + +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. diff --git a/examples/database/employees/supabase/.gitignore b/examples/database/employees/supabase/.gitignore new file mode 100644 index 00000000000..a3ad88055b7 --- /dev/null +++ b/examples/database/employees/supabase/.gitignore @@ -0,0 +1,4 @@ +# Supabase +.branches +.temp +.env diff --git a/examples/database/employees/supabase/config.toml b/examples/database/employees/supabase/config.toml new file mode 100644 index 00000000000..fcfdee7a914 --- /dev/null +++ b/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'] diff --git a/examples/database/employees/supabase/migrations/20241205075911_create_employees_table.sql b/examples/database/employees/supabase/migrations/20241205075911_create_employees_table.sql new file mode 100644 index 00000000000..f4d6e955935 --- /dev/null +++ b/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() +); diff --git a/examples/database/employees/supabase/migrations/20241205080043_add_department_to_employees_table.sql b/examples/database/employees/supabase/migrations/20241205080043_add_department_to_employees_table.sql new file mode 100644 index 00000000000..f03c8f28ea4 --- /dev/null +++ b/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'; diff --git a/examples/database/employees/supabase/seed.sql b/examples/database/employees/supabase/seed.sql new file mode 100644 index 00000000000..2780e73204d --- /dev/null +++ b/examples/database/employees/supabase/seed.sql @@ -0,0 +1,6 @@ +insert into public.employees + (name) +values + ('Erlich Bachman'), + ('Richard Hendricks'), + ('Monica Hall');