|
| 1 | +--- |
| 2 | +sidebar_position: 6 |
| 3 | +title: "Database Migrations" |
| 4 | +sidebar_label: "6. Migrations" |
| 5 | +description: "Learn how to track and manage changes to your database schema using version control for data." |
| 6 | +--- |
| 7 | + |
| 8 | +Have you ever added a new column to a table on your laptop, but then your teammate's code crashed because *their* database didn't have that column? |
| 9 | + |
| 10 | +In the old days, you had to send a `.sql` file to your friend and say, "Hey, run this command." **Database Migrations** solve this problem by automating the process. |
| 11 | + |
| 12 | +## 🧐 What is a Migration? |
| 13 | + |
| 14 | +A **Migration** is a small script (usually in JavaScript, Python, or SQL) that describes a specific change to your database structure. |
| 15 | + |
| 16 | +* **Migration Files** are kept in your GitHub repository. |
| 17 | +* When a teammate pulls your code, they run one command, and their database is instantly updated to match yours. |
| 18 | + |
| 19 | +## How Migrations Work: UP and DOWN |
| 20 | + |
| 21 | +Every migration file has two main functions: |
| 22 | + |
| 23 | +1. **UP:** What should happen when we apply the migration? (e.g., Create a table). |
| 24 | +2. **DOWN:** How do we "Undo" this change if we made a mistake? (e.g., Drop the table). |
| 25 | + |
| 26 | +<Tabs> |
| 27 | + <TabItem value="js" label="💻 Migration Example (JavaScript)" default> |
| 28 | + |
| 29 | + ```javascript |
| 30 | + // Adding a 'phone_number' column to the Users table |
| 31 | + export async function up(knex) { |
| 32 | + return knex.schema.table('users', (table) => { |
| 33 | + table.string('phone_number').nullable(); |
| 34 | + }); |
| 35 | + } |
| 36 | + |
| 37 | + // Undoing the change |
| 38 | + export async function down(knex) { |
| 39 | + return knex.schema.table('users', (table) => { |
| 40 | + table.dropColumn('phone_number'); |
| 41 | + }); |
| 42 | + } |
| 43 | + |
| 44 | +``` |
| 45 | + |
| 46 | +</TabItem> |
| 47 | +<TabItem value="sql" label="🔍 Migration Example (Raw SQL)"> |
| 48 | + |
| 49 | +```sql |
| 50 | +-- UP: Apply the change |
| 51 | +ALTER TABLE Users ADD COLUMN phone_number VARCHAR(15); |
| 52 | + |
| 53 | +-- DOWN: Undo the change |
| 54 | +ALTER TABLE Users DROP COLUMN phone_number; |
| 55 | + |
| 56 | +``` |
| 57 | + |
| 58 | +</TabItem> |
| 59 | +</Tabs> |
| 60 | + |
| 61 | +--- |
| 62 | + |
| 63 | +## The Migration Workflow |
| 64 | + |
| 65 | +At **CodeHarborHub**, we follow this industrial workflow to keep our data in sync: |
| 66 | + |
| 67 | +1. **Create:** You generate a new migration file (e.g., `20260313_add_bio_to_users.js`). |
| 68 | +2. **Write:** You define the `up` and `down` logic. |
| 69 | +3. **Run:** You execute the migration command (e.g., `npx knex migrate:latest`). |
| 70 | +4. **Commit:** You push the migration file to **GitHub**. |
| 71 | +5. **Sync:** Your teammates pull the code and run the same command. **Boom! Everyone is on the same page.** |
| 72 | + |
| 73 | +```mermaid |
| 74 | +sequenceDiagram |
| 75 | + participant DevA as Developer A |
| 76 | + participant GH as GitHub (Code) |
| 77 | + participant DevB as Developer B |
| 78 | + |
| 79 | + DevA->>DevA: Creates Migration Script |
| 80 | + DevA->>DevA: Runs 'Migrate' (Local DB updated) |
| 81 | + DevA->>GH: Pushes Script to Repo |
| 82 | + GH->>DevB: Pulls Code |
| 83 | + DevB->>DevB: Runs 'Migrate' (Local DB updated) |
| 84 | + Note over DevA,DevB: Both Databases are now identical! |
| 85 | +
|
| 86 | +``` |
| 87 | + |
| 88 | +--- |
| 89 | + |
| 90 | +## Why You Should NEVER Edit Tables Manually |
| 91 | + |
| 92 | +If you go into your database tool (like pgAdmin or MySQL Workbench) and manually add a column: |
| 93 | + |
| 94 | +* **Production will crash:** When you deploy your code, the live server won't have that column. |
| 95 | +* **Loss of History:** You won't know *when* or *why* that change was made. |
| 96 | +* **Team Friction:** Your teammates will constantly get "Table not found" errors. |
| 97 | + |
| 98 | +## Summary Checklist |
| 99 | + |
| 100 | +* [x] I understand that Migrations are "Version Control" for my database. |
| 101 | +* [x] I know that `up` applies changes and `down` reverts them. |
| 102 | +* [x] I understand that migration files should be committed to GitHub. |
| 103 | +* [x] I promise to never manually edit my database schema in production. |
| 104 | + |
| 105 | +:::tip Career Secret |
| 106 | +In a job interview, if you mention that you use **Migrations** to manage your schema instead of manual SQL scripts, you immediately look like a 10x more experienced developer. It shows you know how to work in a **real team**. |
| 107 | +::: |
0 commit comments