Skip to content

Commit 83e2080

Browse files
sweatybridgecharislam
sweatybridge
and
charislam
authored
docs: move database migrations to its own page (supabase#30717)
* docs: move database migrations to its own page * Apply suggestions from code review Co-authored-by: Charis <[email protected]> * chore: fix prettier * chore: minor dedupe and typos --------- Co-authored-by: Charis <[email protected]>
1 parent 4d92911 commit 83e2080

File tree

2 files changed

+258
-0
lines changed

2 files changed

+258
-0
lines changed

‎apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2132,6 +2132,7 @@ export const deployment: NavMenuConstant = {
21322132
name: 'Environments',
21332133
items: [
21342134
{ name: 'Managing environments', url: '/guides/deployment/managing-environments' },
2135+
{ name: 'Database migrations', url: '/guides/deployment/database-migrations' },
21352136
{ name: 'Branching', url: '/guides/deployment/branching' },
21362137
],
21372138
},

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

Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
---
2+
id: 'database-migrations'
3+
title: 'Database Migrations'
4+
description: 'How to manage schema migrations for your Supabase project.'
5+
subtitle: 'How to manage schema migrations for your Supabase project.'
6+
video: 'https://www.youtube-nocookie.com/v/vyHyYpvjaks'
7+
tocVideo: 'vyHyYpvjaks'
8+
---
9+
10+
Database schema changes are managed through "migrations". Database migrations are a common way of tracking changes to your database over time.
11+
12+
## Schema migrations
13+
14+
For this guide, we'll create a table called `employees` and see how we can make changes to it.
15+
16+
<StepHikeCompact>
17+
18+
<StepHikeCompact.Step step={1}>
19+
<StepHikeCompact.Details title="Create your first migration file">
20+
21+
To get started, generate a [new migration](/docs/reference/cli/supabase-migration-new) to store the SQL needed to create our `employees` table.
22+
23+
</StepHikeCompact.Details>
24+
25+
<StepHikeCompact.Code>
26+
27+
```bash
28+
supabase migration new create_employees_table
29+
```
30+
31+
</StepHikeCompact.Code>
32+
33+
</StepHikeCompact.Step>
34+
</StepHikeCompact>
35+
36+
<StepHikeCompact>
37+
38+
<StepHikeCompact.Step step={2}>
39+
<StepHikeCompact.Details title="Add the SQL to your migration file">
40+
This creates a new migration: supabase/migrations/\<timestamp\>
41+
_create_employees_table.sql.
42+
43+
To that file, add the SQL to create this `employees` table
44+
</StepHikeCompact.Details>
45+
46+
<StepHikeCompact.Code>
47+
48+
```sql
49+
create table employees (
50+
id bigint primary key generated always as identity,
51+
name text,
52+
email text,
53+
created_at timestamptz default now()
54+
);
55+
```
56+
57+
</StepHikeCompact.Code>
58+
59+
</StepHikeCompact.Step>
60+
</StepHikeCompact>
61+
62+
<StepHikeCompact>
63+
64+
<StepHikeCompact.Step step={3}>
65+
<StepHikeCompact.Details title="Apply your migration">
66+
Now that you have a migration file, you can run this migration and create the `employees` table.
67+
68+
Use the `reset` command here to reset the database to the current migrations
69+
</StepHikeCompact.Details>
70+
71+
<StepHikeCompact.Code>
72+
73+
```bash
74+
supabase db reset
75+
```
76+
77+
</StepHikeCompact.Code>
78+
79+
</StepHikeCompact.Step>
80+
</StepHikeCompact>
81+
82+
<StepHikeCompact>
83+
84+
<StepHikeCompact.Step step={4}>
85+
<StepHikeCompact.Details title="Modify your employees table">
86+
Now you can visit your new `employees` table in the Dashboard.
87+
88+
Next, modify your `employees` table by adding a column for department. Create a new migration file for that.
89+
</StepHikeCompact.Details>
90+
91+
<StepHikeCompact.Code>
92+
93+
```bash
94+
supabase migration new add_department_to_employees_table
95+
```
96+
97+
</StepHikeCompact.Code>
98+
99+
</StepHikeCompact.Step>
100+
</StepHikeCompact>
101+
102+
<StepHikeCompact>
103+
104+
<StepHikeCompact.Step step={5}>
105+
<StepHikeCompact.Details title="Add a new column to your table">
106+
This creates a new migration file: supabase/migrations/\<timestamp\>
107+
_add_department_to_employees_table.sql.
108+
109+
To that file, add the SQL to create a new department column
110+
</StepHikeCompact.Details>
111+
112+
<StepHikeCompact.Code>
113+
114+
```sql
115+
alter table if exists public.employees
116+
add department text default 'Hooli';
117+
```
118+
119+
</StepHikeCompact.Code>
120+
121+
</StepHikeCompact.Step>
122+
</StepHikeCompact>
123+
124+
### Add sample data
125+
126+
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.
127+
128+
For this, you can create a seed script in `supabase/seed.sql`.
129+
130+
<StepHikeCompact>
131+
132+
<StepHikeCompact.Step step={1}>
133+
<StepHikeCompact.Details title="Populate your table">
134+
Insert data into your `employees` table with your `supabase/seed.sql` file.
135+
</StepHikeCompact.Details>
136+
137+
<StepHikeCompact.Code>
138+
139+
```sql
140+
insert into public.employees
141+
(name)
142+
values
143+
('Erlich Bachman'),
144+
('Richard Hendricks'),
145+
('Monica Hall');
146+
```
147+
148+
</StepHikeCompact.Code>
149+
150+
</StepHikeCompact.Step>
151+
</StepHikeCompact>
152+
153+
<StepHikeCompact>
154+
155+
<StepHikeCompact.Step step={2}>
156+
<StepHikeCompact.Details title="Reset your database">
157+
Reset your database (apply current migrations), and populate with seed data
158+
</StepHikeCompact.Details>
159+
160+
<StepHikeCompact.Code>
161+
162+
```bash
163+
supabase db reset
164+
```
165+
166+
</StepHikeCompact.Code>
167+
168+
</StepHikeCompact.Step>
169+
</StepHikeCompact>
170+
171+
You should now see the `employees` table, along with your seed data in the Dashboard! All of your database changes are captured in code, and you can reset to a known state at any time, complete with seed data.
172+
173+
### Diffing changes
174+
175+
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.
176+
177+
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:
178+
179+
```
180+
Diffing schemas: public
181+
Finished supabase db diff on branch main.
182+
183+
create table "public"."cities" (
184+
"id" bigint primary key generated always as identity,
185+
"name" text,
186+
"population" bigint
187+
);
188+
189+
```
190+
191+
Alternately, you can view your table definitions directly from the Table Editor:
192+
193+
![SQL Definition](/docs/img/guides/cli/sql-definitions.png)
194+
195+
You can then copy this SQL into a new migration file, and run `supabase db reset` to apply the changes.
196+
197+
The last step is deploying these changes to a live Supabase project.
198+
199+
## Deploy your project
200+
201+
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.
202+
203+
### Log in to the Supabase CLI
204+
205+
<CH.Code>
206+
207+
```bash Terminal
208+
supabase login
209+
```
210+
211+
```bash npx
212+
npx supabase login
213+
```
214+
215+
</CH.Code>
216+
217+
### Link your project
218+
219+
Associate your project with your remote project using [`supabase link`](/docs/reference/cli/usage#supabase-link).
220+
221+
```bash
222+
supabase link --project-ref <project-id>
223+
# You can get <project-id> from your project's dashboard URL: https://supabase.com/dashboard/project/<project-id>
224+
225+
supabase db pull
226+
# Capture any changes that you have made to your remote database before you went through the steps above
227+
# If you have not made any changes to the remote database, skip this step
228+
```
229+
230+
`supabase/migrations` is now populated with a migration in `<timestamp>_remote_schema.sql`.
231+
This migration captures any changes required for your local database to match the schema of your remote Supabase project.
232+
233+
Review the generated migration file and once happy, apply the changes to your local instance:
234+
235+
```bash
236+
# To apply the new migration to your local database:
237+
supabase migration up
238+
239+
# To reset your local database completely:
240+
supabase db reset
241+
```
242+
243+
<Admonition type="note">
244+
245+
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!
246+
247+
</Admonition>
248+
249+
### Deploy database changes
250+
251+
Deploy any local database migrations using [`db push`](/docs/reference/cli/usage#supabase-db-push):
252+
253+
```sh
254+
supabase db push
255+
```
256+
257+
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.

0 commit comments

Comments
 (0)