🖼️ See the drawing + lab 🏠 Course home 🌿 Branch on GitHub ✏️ View source

🖼️ आकृती आणि labThe drawing + lab पूर्ण पानावर उघडा ↗Open full page ↗

🏗️ धडा 08 — Migrations: शाळा चालू असतानाच खोलीचे नूतनीकरण

📍 तुम्ही इथे आहात: 18 पैकी धडा 08 · मागे: lesson-07-concurrency · पुढे: lesson-09-backups-recovery

📦 या ब्रँचमध्ये काय आहे

धडे 01–07, आणि शाळा बंद न करता खोलीचा आकार कसा बदलतो: versioned migration scripts, logbook (schema_migrations), आणि zero-downtime बदलासाठी expand → migrate → contract पद्धत. खऱ्या files:

db/migrate.py — नूतनीकरण करणारी टीम, 30 ओळी
db/migrations/ — 001_init, 002_add_house, 003_index_grades_subject

🧒 5 वर्षांच्या मुलाला समजावल्यासारखे

शाळेला students नोंदवहीत एक नवा column हवा आहे: house (red, blue…). खोली चालू आहे; clerks आत्ता त्यात लिहीत आहेत. तुम्ही आठवडाभर शाळा बंद करू शकत नाही.

म्हणून नूतनीकरण क्रमांक असलेल्या work orders 🏗️ म्हणून केले जाते, git मध्ये ठेवलेले, क्रमाने, प्रत्येकी एकदाच लागू केलेले, आणि एका logbook मध्ये नोंदवलेले — schema_migrations — म्हणजे खोलीची कोणतीही प्रत सांगू शकते "माझ्यावर work orders 001 ते 003 झाल्या आहेत." टीम दोनदा चालवा, दुसऱ्यांदा ती काहीच करत नाही.

आणि rename कधीच एका पायरीत होत नाही. clerks लिहीत असतानाच class चे नाव section करायचे असेल तर:

Expand — class च्या शेजारी section जोडा (जुना code त्याकडे दुर्लक्ष करतो).
Migrate — दोन्हीत लिहिणारा code ship करा; जुन्या rows backfill करा.
section वाचणारा code ship करा.
Contract — class काढून टाका.

प्रत्येक पायरीत शाळा चालू राहते; प्रत्येक पायरीची प्रतीवर रंगीत तालीम करता येते.

🗺️ आकृती

flowchart LR
    g["📜 db/migrations/<br/>001_init.sql · 002_add_house.sql · 003_index…sql"]
    m["🏗️ migrate.py<br/>apply pending, in order, once"]
    log["🧾 schema_migrations<br/>name · applied_at"]
    room["🗄️ school.db<br/>now has students.house"]
    g -->|"1"| m -->|"2 each in a transaction"| room
    m -->|"3 record"| log
    ec["expand → migrate → contract:<br/>add new · write both · backfill · read new · drop old"]
    room -.->|"4 for renames"| ec

❓ काय

Migration: schema (किंवा data) version N वरून N+1 वर बदलणारी script. क्रमांक किंवा timestamp असलेली; तिची गरज असलेल्या code सोबत commit केलेली.
Logbook: लागू झालेल्या migrations चा table. tool फक्त जे कमी आहे तेच लागू करते. Tools: Flyway, Liquibase, Alembic, Prisma Migrate, Rails — सगळे हीच पद्धत.
Reversible: शक्य असेल तेव्हा down पायरी लिहा; शक्य नसेल तेव्हा (column काढणे), प्रतीवर रंगीत तालीम करा आणि backup ठेवा (धडा 09).
Expand/contract: आधी जोडणारे बदल (default सह नवा column, नवा table), नष्ट करणारे शेवटी, आणि मध्ये code deploy. live table वर column कधीच एका पायरीत RENAME करू नका.
मोठ्या tables वरचे Backfills थांबे घेत batches मध्ये चालतात — एकच प्रचंड UPDATE सर्वांसाठी नोंदवही lock करतो (धडा 07).
SQLite टीप: ALTER TABLE मर्यादित आहे (add column, rename); Postgres default सह column लगेच जोडू शकतो, पण काही बदल संपूर्ण table पुन्हा लिहितात — मोठ्या बदलाआधी तुमच्या database च्या notes वाचा.

🤔 का

कारण "कोणीतरी शुक्रवारी production वर हाताने ALTER TABLE चालवले" हाच तो मार्ग आहे ज्याने schemas अज्ञात होतात आणि rollbacks फक्त आठवणीत राहतात. git मधील migrations खोलीचा आकार review करता येणारा, पुन्हा करता येणारा आणि तालीम करता येणारा बनवतात — आणि rename outage बनू नये याचा expand/contract हा एकमेव मार्ग आहे.

🔧 कसे (या repo मध्ये)

db/migrate.py logbook बनवते, db/migrations/*.sql ची यादी करते, लागू न झालेली प्रत्येक file एका transaction मध्ये लागू करते आणि तिची नोंद करते. 002_add_house ही expand पायरी आहे; 003 नव्या प्रश्नाला लागणारा index जोडते.

🧪 करून पाहा

python3 db/demo.py >/dev/null           # a fresh room (schema.sql already includes 001's tables)
python3 db/migrate.py status            # ⏳ all three pending
python3 db/migrate.py                   # applied 001, 002, 003
python3 db/migrate.py                   # nothing to do — idempotent
python3 -c "import sqlite3; c=sqlite3.connect('db/school.db'); print(c.execute('SELECT name, house FROM students LIMIT 2').fetchall()); print(c.execute('SELECT name FROM schema_migrations').fetchall())"
# your migration: expand → contract for a rename, in two files
printf -- '-- expand: new column next to the old one\nALTER TABLE homework ADD COLUMN heading TEXT;\nUPDATE homework SET heading = title;\n' > db/migrations/004_homework_heading_expand.sql
python3 db/migrate.py && python3 -c "import sqlite3; print(sqlite3.connect('db/school.db').execute('SELECT title, heading FROM homework').fetchall())"
# (005 — the contract step that drops `title` — only after every reader uses `heading`; write it, don't run it yet)

✅ तपासा — तुम्हाला काय दिसायला हवे

status आधी तीन ⏳ दाखवतो, मग तीन ✅; दुसरा run फक्त up to date छापतो; प्रत्येक विद्यार्थिनीला house = 'red' आहे; तुमची 004 एकदाच लागू होते आणि heading हे title चे प्रतिबिंब असते. logbook मध्ये चार नावे दिसतात.

🏁 तुम्ही आत्ताच काय सिद्ध केले

खोलीने पुन्हा न बांधता चार वेळा आकार बदलला, प्रत्येक बदलाची नोंद झाली, एकही दोनदा लागू झाला नाही — आणि तुम्ही कधीच कोणत्याही clerk ला न अडवणाऱ्या rename चा expand अर्धा भाग लिहिला.

⚠️ नेहमीच्या चुका

आधीच लागू झालेली migration edit करणे — नवी लिहा; इतिहास फक्त पुढे जोडला जातो
live table वर एका पायरीत rename किंवा drop करणे
मोठ्या table वर एकच प्रचंड UPDATE म्हणून backfill
आजच्या data च्या आकारावर अवलंबून असलेल्या, पण तो न तपासणाऱ्या migrations
नष्ट करणाऱ्या पायरीआधी प्रतीवर रंगीत तालीम न करणे (धडा 09 ही सुरक्षा जाळी आहे)

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: zero-downtime deploys ही Kubernetes ची शिस्त होण्याआधी schema ची शिस्त आहे. रोज ship करणारी प्रत्येक team CI मध्ये migrations चालवते, default म्हणून expand/contract वापरते, आणि हाताने चालवलेला ALTER म्हणजे incident मानते.

⏭️ पुढे

नूतनीकरण चुकू शकते; शुक्रवारच्या दुपारीही. Backups आणि recovery — RPO, RTO, आणि तुम्ही खरोखर करता ती restore ची रंगीत तालीम.

git checkout lesson-09-backups-recovery

🏗️ Lesson 08 — Migrations: renovating the room while school is open

📍 You are here: Lesson 08 of 18 · Previous: lesson-07-concurrency · Next: lesson-09-backups-recovery

📦 What's in this branch

Lessons 01–07, plus how the shape of the room changes without closing the school: versioned migration scripts, the logbook (schema_migrations), and the expand → migrate → contract pattern for zero-downtime change. Real files:

db/migrate.py — the renovation crew, 30 lines
db/migrations/ — 001_init, 002_add_house, 003_index_grades_subject

🧒 Explain like I'm 5

The school wants a new column in the students register: house (red, blue…). The room is open; clerks are writing in it right now. You cannot close the school for a week.

So renovations are done as numbered work orders 🏗️, kept in git, applied in order, once each, and recorded in a logbook — schema_migrations — so any copy of the room can say "I have had work orders 001 to 003." Run the crew twice and it does nothing the second time.

And a rename is never one step. To rename class to section while clerks keep writing:

Expand — add section next to class (old code ignores it).
Migrate — ship code that writes both; backfill the old rows.
Ship code that reads section.
Contract — drop class.

Every step keeps school open; every step can be rehearsed on a copy.

🗺️ Diagram

flowchart LR
    g["📜 db/migrations/<br/>001_init.sql · 002_add_house.sql · 003_index…sql"]
    m["🏗️ migrate.py<br/>apply pending, in order, once"]
    log["🧾 schema_migrations<br/>name · applied_at"]
    room["🗄️ school.db<br/>now has students.house"]
    g -->|"1"| m -->|"2 each in a transaction"| room
    m -->|"3 record"| log
    ec["expand → migrate → contract:<br/>add new · write both · backfill · read new · drop old"]
    room -.->|"4 for renames"| ec

❓ What

Migration: a script that changes schema (or data) from version N to N+1. Numbered or timestamped; committed with the code that needs it.
Logbook: a table of applied migrations. The tool applies only what is missing. Tools: Flyway, Liquibase, Alembic, Prisma Migrate, Rails — all this pattern.
Reversible: write the down step when you can; when you cannot (dropping a column), rehearse on a copy and have a backup (lesson 09).
Expand/contract: additive first (new column with a default, new table), destructive last, code deployed in between. Never RENAME a column in one step on a live table.
Backfills on big tables run in batches with pauses — one giant UPDATE locks the register for everyone (lesson 07).
SQLite note: ALTER TABLE is limited (add column, rename); Postgres can add a column with a default instantly, but some changes rewrite the table — read your database's notes before a big one.

🤔 Why

Because "someone ran ALTER TABLE on production by hand on a Friday" is how schemas become unknowable and rollbacks become memory. Migrations in git make the shape of the room reviewable, repeatable and rehearsable — and expand/contract is the only way a rename does not become an outage.

🔧 How (in this repo)

db/migrate.py creates the logbook, lists db/migrations/*.sql, applies each unapplied file inside a transaction and records it. 002_add_house is an expand step; 003 adds an index a new question needed.

🧪 Try it

python3 db/demo.py >/dev/null           # a fresh room (schema.sql already includes 001's tables)
python3 db/migrate.py status            # ⏳ all three pending
python3 db/migrate.py                   # applied 001, 002, 003
python3 db/migrate.py                   # nothing to do — idempotent
python3 -c "import sqlite3; c=sqlite3.connect('db/school.db'); print(c.execute('SELECT name, house FROM students LIMIT 2').fetchall()); print(c.execute('SELECT name FROM schema_migrations').fetchall())"
# your migration: expand → contract for a rename, in two files
printf -- '-- expand: new column next to the old one\nALTER TABLE homework ADD COLUMN heading TEXT;\nUPDATE homework SET heading = title;\n' > db/migrations/004_homework_heading_expand.sql
python3 db/migrate.py && python3 -c "import sqlite3; print(sqlite3.connect('db/school.db').execute('SELECT title, heading FROM homework').fetchall())"
# (005 — the contract step that drops `title` — only after every reader uses `heading`; write it, don't run it yet)

✅ Verify — what you should see

status shows three ⏳, then three ✅; the second run prints only up to date; every student has house = 'red'; your 004 applies once and heading mirrors title. The logbook lists four names.

🏁 What you just proved

The room changed shape four times without being rebuilt, each change recorded, none applied twice — and you wrote the expand half of a rename that never blocks a clerk.

⚠️ Common mistakes

editing an already-applied migration — write a new one; history is append-only
renaming or dropping in one step on a live table
a backfill as one giant UPDATE on a big table
migrations that depend on today's data shape without checking it
no rehearsal on a copy before a destructive step (lesson 09 is the safety net)

🏭 Why this matters in production: zero-downtime deploys are a schema discipline before they are a Kubernetes one. Every team that ships daily runs migrations in CI, expand/contract by default, and treats a hand-run ALTER as an incident.

⏭️ Next

Renovations can go wrong; so can Friday afternoons. Backups and recovery — RPO, RTO, and the restore drill you actually run.

git checkout lesson-09-backups-recovery

← Previousconcurrency Next →backups recovery

This page is the lesson's README from the lesson-08-migrations branch, shown here so the whole School stays on one site. Code files open on GitHub at the same branch.