# فصل ۰۸ — اسکیما عوض می‌شود

<div dir="rtl">

# فصل ۰۸ — اسکیما عوض می‌شود

## در این فصل چه یاد می‌گیری

هفت فصل اسکیما ساختیم. این فصل دربارهٔ روزی است که **کسی می‌آید و می‌گوید یک چیز باید عوض شود** — و آن روز حتماً می‌آید.

با یک آزمایشِ ساده شروع می‌کنیم: **یک خواننده که همین حالا در حالِ کار است و ستونی را می‌خواند، و ما وسطِ کارش اسمِ آن ستون را عوض می‌کنیم.** پیامی که می‌گیرد `no such column` است، و از آن لحظه هر بار که اجرا شود همان را می‌گیرد.

بعد همان تغییر را دو مرحله‌ای انجام می‌دهیم، طوری که **هر دو خواننده — قدیمی و جدید — یک لحظه هم نشکنند**، و هر مرحله را با شمارش ثابت می‌کنیم.

![دو ریلِ موازی که یک واگن از یکی به دیگری منتقل می‌شود در حالی که هر دو ریل هنوز کامل‌اند](/lesson-assets/t4-s08-migrations/prompt/01-image-two-rails.png)

آخر این فصل می‌توانی:

- بگویی چرا مهاجرتِ فقط-افزودنی تنها نوعِ امنِ مهاجرت است
- با `ALTER TABLE ADD COLUMN` ستون اضافه کنی و سه محدودیتش را بشناسی
- یک تغییرِ شکننده را به دو مرحلهٔ نشکن تبدیل کنی
- جدولی را که `ALTER` کافی‌اش نیست، امن بازسازی کنی
- نسخهٔ اسکیما را نگه داری و مهاجرت را قابلِ اجرای دوباره کنی

## قبل از شروع

**از فصلِ ۶:** `NOT NULL` و `CHECK` و `DEFAULT`. **از فصلِ ۳:** `PRAGMA foreign_keys` و اینکه بعضی `PRAGMA`ها وسطِ تراکنش بی‌صدا نادیده گرفته می‌شوند — در بخشِ ۵ دوباره لازمش داریم.

**تعریف، در یک جمله:** مهاجرت یک تغییرِ اسکیماست که **نوشته شده، شماره خورده، و دقیقاً یک بار اجرا می‌شود.** هر سهٔ این‌ها لازم‌اند؛ تغییری که کسی دستی در کنسول زده مهاجرت نیست.

> 📓 **نوت‌بوک:** [نوت‌بوک این فصل را در Colab باز کن](/notebooks/avand/term-4-modelling/session-08-migrations.ipynb) — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

</div>

| جدول | تعدادِ سطر | زمانِ ساخت |
|---|---|---|
| `catalog_raw` | ۱٬۲۰۰ | کمتر از یک ثانیه |
| `members_raw` | ۳۰۰ | آنی |
| `loan_events` | ۲۶٬۱۱۹ | حدودِ یک ثانیه |

<div dir="rtl">

## ۱. خواننده‌ای که وسطِ کار می‌شکند

جدولِ اعضا را می‌سازیم و دو تکه کدِ کاملاً معمولی کنارش می‌گذاریم: یکی گزارشی که سه سال پیش نوشته شده، و یکی گزارشی که امروز می‌نویسیم.

</div>

```python
con.executescript("""
    DROP TABLE IF EXISTS members_v1;
    CREATE TABLE members_v1 (
        id    INTEGER PRIMARY KEY,
        name  TEXT NOT NULL,
        phone TEXT
    );
    INSERT INTO members_v1 (id, name, phone) SELECT id, name, phone FROM members_raw;
""")
con.commit()


def old_report():
    """کدی که سه سال پیش نوشته شده و هیچ‌کس حاضر نیست دستش بزند."""
    return len(q("SELECT id, name, phone FROM members_v1"))


def new_report():
    """گزارشی که امروز می‌نویسیم و اسم تازه را می‌خواهد."""
    return len(q("SELECT id, name, contact_phone FROM members_v1"))


print("خوانندهٔ قدیمی، قبل از هر تغییری:", old_report(), "سطر")
print()
con.execute("ALTER TABLE members_v1 RENAME COLUMN phone TO contact_phone")
con.commit()
print("و حالا، بعد از یک تغییرِ نام:")
try:
    old_report()
except Exception as error:
    print(" ", type(error).__module__ + "." + type(error).__name__, "|", error)
print("خوانندهٔ جدید:", new_report(), "سطر")

con.execute("ALTER TABLE members_v1 RENAME COLUMN contact_phone TO phone")
con.commit()
```

```text
خوانندهٔ قدیمی، قبل از هر تغییری: 300 سطر

و حالا، بعد از یک تغییرِ نام:
  pandas.errors.DatabaseError | Execution failed on sql 'SELECT id, name, phone FROM members_v1': no such column: phone
خوانندهٔ جدید: 300 سطر
```

<div dir="rtl">

**یک فرمان، و گزارشی که سه سال کار می‌کرد از کار افتاد.**

و توجه کن که مشکل **دائمی** است، نه لحظه‌ای: تا وقتی کسی آن کدِ قدیمی را پیدا نکند و عوضش نکند، هر بار که اجرا شود همین خطا را می‌دهد. **در یک سامانهٔ واقعی، این یعنی گزارشِ شبانه از امشب دیگر ساخته نمی‌شود** — و معمولاً روزها بعد کسی متوجه می‌شود.

**و بدترین حالتش این است که تغییر را نمی‌شود ساده برگرداند.** ما اینجا آخرِ سلول اسم را برگرداندیم و همه‌چیز درست شد، چون جدولمان ۳۰۰ سطر است و هیچ‌کس در همان لحظه چیزی ننوشته بود. در تولید، بینِ آن دو لحظه سطر نوشته می‌شود، و برگرداندنِ اسم آن سطرها را برنمی‌گرداند.

## ۲. قاعدهٔ فقط-افزودنی، و اینکه از کجا می‌آید

**قاعده:** یک مهاجرت فقط چیز **اضافه** می‌کند — ستونِ تازه، جدولِ تازه، `index` تازه. حذف و تغییرِ نام و تنگ کردنِ نوع، هیچ‌کدام در همان انتشاری که استفاده از آن ستون را قطع می‌کند انجام نمی‌شوند.

**دلیلش یک عدمِ تقارن است که در همهٔ سامانه‌های واقعی وجود دارد:** برگرداندنِ **کد** به نسخهٔ قبل کارِ ساده‌ای است — همان فایل‌های قبلی را برمی‌گردانی. برگرداندنِ **اسکیما** ساده نیست، چون داده‌ای که در این فاصله نوشته شده در ساختارِ تازه است.

پس اگر مهاجرتت ستونی را حذف کرده باشد و بعد مجبور شوی کد را عقب ببری، **کدِ قدیمی سراغِ ستونی می‌رود که دیگر وجود ندارد** و بازگشت هم شکسته است. **هر تغییرِ کاهنده دو انتشار طول می‌کشد:**

1. **انتشارِ اول** — ستونِ تازه اضافه می‌شود، هر دو ستون پر می‌شوند، کدِ تازه ستونِ تازه را می‌خواند. **کدِ قدیمی هم هنوز کار می‌کند.**
2. **انتشارِ دوم** — وقتی مطمئن شدی هیچ‌کس ستونِ قدیمی را نمی‌خواند، حذفش می‌کنی.

**و بینِ آن دو انتشار باید بتوانی بی‌دردسر به عقب برگردی.** دلیلش ساده است: بازگشت به نسخهٔ قبل فقط کد را عوض می‌کند و **نمی‌تواند یک مهاجرت را پس بگیرد**، پس هر مهاجرت باید برای نسخهٔ **قبلیِ** برنامه هم بی‌خطر باشد.

## ۳. `ALTER TABLE ADD COLUMN` و سه چیزی که نمی‌تواند

</div>

```python
con.execute("ALTER TABLE members_v1 ADD COLUMN contact_phone TEXT")
con.commit()
print("ستون تازه اضافه شد:")
print(q("PRAGMA table_info(members_v1)")[["name", "type", "notnull", "dflt_value"]])
print()

for label, statement in [
    ("NOT NULL بدون DEFAULT", "ALTER TABLE members_v1 ADD COLUMN city TEXT NOT NULL"),
    ("ستون UNIQUE", "ALTER TABLE members_v1 ADD COLUMN code TEXT UNIQUE"),
]:
    try:
        con.execute(statement)
        print(f"  {label:<22} → قبول شد")
    except Exception as error:
        print(f"  {label:<22} → {type(error).__name__} | {error}")

con.execute("ALTER TABLE members_v1 ADD COLUMN city TEXT NOT NULL DEFAULT 'نامعلوم'")
con.commit()
print()
print("همان ستون، این بار با DEFAULT:")
print(q("SELECT city, COUNT(*) AS rows FROM members_v1 GROUP BY city"))
```

```text
ستون تازه اضافه شد:
            name     type  notnull dflt_value
0             id  INTEGER        0       None
1           name     TEXT        1       None
2          phone     TEXT        0       None
3  contact_phone     TEXT        0       None

  NOT NULL بدون DEFAULT  → OperationalError | Cannot add a NOT NULL column with default value NULL
  ستون UNIQUE            → OperationalError | Cannot add a UNIQUE column

همان ستون، این بار با DEFAULT:
      city  rows
0  نامعلوم   300
```

<div dir="rtl">

**دو محدودیت، و هر دو منطقی‌اند.**

`NOT NULL` بدونِ `DEFAULT` رد شد چون **۳۰۰ سطرِ موجود باید همان لحظه مقداری بگیرند** و `SQLite` نمی‌داند چه. با `DEFAULT` همان فرمان قبول شد و هر ۳۰۰ سطر مقدارِ پیش‌فرض گرفتند. **پس `DEFAULT` فقط برای سطرهای آینده نیست؛ ابزارِ اصلیِ اضافه کردنِ ستونِ اجباری به جدولی است که از قبل داده دارد.**

`UNIQUE` رد شد به دلیلِ دیگری: یک `index` یکتا می‌خواهد و `ALTER TABLE` در `SQLite` `index` نمی‌سازد. **راهش این است که ستون را ساده اضافه کنی و بعد جدا `CREATE UNIQUE INDEX` بزنی** — که اگر داده‌ات تکراری داشته باشد، همان‌جا خطا می‌گیری.

و محدودیتِ سوم، که این کد نشانش نداد: **`ALTER TABLE` در `SQLite` نمی‌تواند قیدِ `CHECK` را روی ستونی که از قبل هست بگذارد.** نحوی به نامِ `ADD CONSTRAINT` اصلاً ندارد و `syntax error` می‌گیری. ستونِ تازه می‌تواند همراهِ خودش `CHECK` بیاورد، ولی برای ستونِ موجود باید جدول را بازسازی کنی — بخشِ ۵.

## ۴. همان تغییر، دو مرحله‌ای

حالا تغییرِ بخشِ ۱ را طوری انجام می‌دهیم که هیچ خواننده‌ای نشکند. ستونِ تازه از بخشِ ۳ ساخته شده و خالی است؛ **مرحلهٔ اول پرش می‌کند.**

</div>

```python
print("مرحلهٔ ۰ — قبل از هر کاری:")
print("  خوانندهٔ قدیمی:", old_report(), "| ستون تازه چند مقدار دارد؟",
      int(q("SELECT COUNT(contact_phone) AS n FROM members_v1").iloc[0, 0]))

con.execute("UPDATE members_v1 SET contact_phone = phone WHERE contact_phone IS NULL")
con.commit()
print()
print("مرحلهٔ ۱ — پر کردن ستون تازه:")
print("  خوانندهٔ قدیمی:", old_report(), "| خوانندهٔ جدید:", new_report())
print("  سطرهایی که دو ستونشان با هم نمی‌خوانند:",
      int(q("""
          SELECT COUNT(*) AS n FROM members_v1
          WHERE phone IS NOT contact_phone
      """).iloc[0, 0]))
```

```text
مرحلهٔ ۰ — قبل از هر کاری:
  خوانندهٔ قدیمی: 300 | ستون تازه چند مقدار دارد؟ 0

مرحلهٔ ۱ — پر کردن ستون تازه:
  خوانندهٔ قدیمی: 300 | خوانندهٔ جدید: 300
  سطرهایی که دو ستونشان با هم نمی‌خوانند: 0
```

<div dir="rtl">

**هر دو خواننده کار می‌کنند و هر ۳۰۰ سطر در دو ستون مقدارِ یکسان دارند.**

و آن `IS NOT` عمدی است، نه `<>`. **اگر یک طرف مقدار داشته باشد و طرفِ دیگر `NULL`، حاصلِ `<>` درست نیست بلکه `NULL` است**، پس همان سطری که آزمون باید بگیرد بی‌صدا رد می‌شود — همان منطقِ سه‌ارزشیِ ترمِ ۱. `IS NOT` این تله را ندارد چون همیشه درست یا نادرست برمی‌گردد.

**مرحلهٔ دوم چیزی است که در همین سلول انجام نمی‌دهیم و کلِ نکته همین است:** از حالا تا انتشارِ بعدی، برنامه باید **هر دو ستون را بنویسد**. تا وقتی این کار انجام می‌شود، می‌شود کد را هر لحظه به عقب برگرداند و هیچ‌چیزی نمی‌شکند.

</div>

```sql
-- در انتشارِ اول، برنامه هر دو را می‌نویسد:
UPDATE members_v1 SET phone = ?, contact_phone = ? WHERE id = ?

-- و فقط در انتشارِ دوم، وقتی هیچ‌کس ستونِ قدیمی را نمی‌خواند:
ALTER TABLE members_v1 DROP COLUMN phone
```

<div dir="rtl">

**«وقتی هیچ‌کس نمی‌خواند» را حدس نزن، اندازه بگیر.** ساده‌ترین راهش یک شمارنده در برنامه است که هر بار ستونِ قدیمی خوانده شد یکی بالا برود؛ وقتی چند هفته صفر ماند، انتشارِ دوم امن است.

> ✅ **چک کن:** بعد از مرحلهٔ ۱، هر سه عدد باید ۳۰۰ و ۳۰۰ و ۰ باشند. اگر عددِ سوم صفر نشد، `UPDATE` همهٔ سطرها را نگرفته — و **اگر مرحلهٔ دوم را با این وضع بزنی، همان سطرها برای همیشه مقدارشان را از دست می‌دهند.**

## ۵. وقتی `ALTER` کافی نیست: بازسازیِ جدول

قیدِ `CHECK` را نمی‌شود روی ستونِ موجود گذاشت. راهش این است: **جدولِ تازه با اسکیمای درست بساز، داده را کپی کن، قدیمی را حذف کن، تازه را به نامِ قدیمی تغییرِ نام بده.**

**ولی قبل از همه، مثلِ فصلِ ۶، بشمار چند سطر قید تازه را می‌شکنند.**

</div>

```python
bad_phone = int(q("""
    SELECT COUNT(*) AS n FROM members_v1
    WHERE contact_phone IS NULL OR contact_phone NOT LIKE '09%'
""").iloc[0, 0])
duplicates = int(q("""
    SELECT COUNT(*) - COUNT(DISTINCT contact_phone) AS n FROM members_v1
""").iloc[0, 0])
print("سطرهایی که قید قالبِ تلفن را می‌شکنند:", bad_phone)
print("سطرهایی که قید یکتاییِ تلفن را می‌شکنند:", duplicates)
```

```text
سطرهایی که قید قالبِ تلفن را می‌شکنند: 0
سطرهایی که قید یکتاییِ تلفن را می‌شکنند: 12
```

<div dir="rtl">

**صفر و دوازده — پس قیدِ قالب بی‌خطر است و قیدِ یکتایی همین حالا شکسته است.** بدونِ این دو خط، مهاجرت را می‌نوشتیم و در تولید شکست می‌خورد.

پس فقط قیدِ قالب را اضافه می‌کنیم، و ستونِ `phone` را هم نگه می‌داریم، چون انتشارِ دوم هنوز نرسیده و خوانندهٔ قدیمی آن را می‌خواند. **مراحلِ بازسازی، به ترتیب، و هیچ‌کدامشان اختیاری نیست:**

</div>

```python
con.commit()                          # PRAGMA وسطِ تراکنشِ باز بی‌صدا نادیده گرفته می‌شود
con.execute("PRAGMA foreign_keys = OFF")
con.executescript("""
    BEGIN;
    CREATE TABLE members_v2 (
        id            INTEGER PRIMARY KEY,
        name          TEXT NOT NULL,
        phone         TEXT,
        contact_phone TEXT NOT NULL CONSTRAINT phone_shape
                           CHECK (contact_phone LIKE '09%'),
        city          TEXT NOT NULL DEFAULT 'نامعلوم'
    );
    INSERT INTO members_v2 (id, name, phone, contact_phone, city)
    SELECT id, name, phone, contact_phone, city FROM members_v1;
    DROP TABLE members_v1;
    ALTER TABLE members_v2 RENAME TO members_v1;
""")
print("تراکنش هنوز باز است؟", con.in_transaction)
broken = pd.read_sql_query("PRAGMA foreign_key_check", con)
print("نقض‌های کلیدِ خارجی بعد از بازسازی:", len(broken))
con.commit()
con.execute("PRAGMA foreign_keys = ON")

print("سطرهای جدولِ بازسازی‌شده:", int(q("SELECT COUNT(*) AS n FROM members_v1").iloc[0, 0]))
print(q("PRAGMA table_info(members_v1)")[["name", "type", "notnull"]])
print()
print("خوانندهٔ قدیمی:", old_report(), "| خوانندهٔ جدید:", new_report())
print("سلامت فایل:", con.execute("PRAGMA integrity_check").fetchone()[0])
try:
    con.execute("""
        INSERT INTO members_v1 (id, name, contact_phone) VALUES (?, ?, ?)
    """, (901, "عضو آزمایشی", "12345"))
except Exception as error:
    print(type(error).__name__, "|", error)
con.rollback()
```

```text
تراکنش هنوز باز است؟ True
نقض‌های کلیدِ خارجی بعد از بازسازی: 0
سطرهای جدولِ بازسازی‌شده: 300
            name     type  notnull
0             id  INTEGER        0
1           name     TEXT        1
2          phone     TEXT        0
3  contact_phone     TEXT        1
4           city     TEXT        1

خوانندهٔ قدیمی: 300 | خوانندهٔ جدید: 300
سلامت فایل: ok
IntegrityError | CHECK constraint failed: phone_shape
```

<div dir="rtl">

**سیصد سطر رفت، سیصد سطر برگشت، قید سرِ جایش نشست، هر دو خواننده هنوز کار می‌کنند، و فایل سالم است.**

سه نکته که اگر جا بیفتند این کار خطرناک می‌شود:

1. **`PRAGMA foreign_keys = OFF` قبل از شروع.** بدونِ آن، `DROP TABLE` روی جدولی که کسِ دیگری به آن ارجاع می‌دهد یا خطا می‌دهد یا — بدتر — با `ON DELETE CASCADE` سطرهای جدولِ دیگری را پاک می‌کند. و **باید بیرونِ تراکنش زده شود**، وگرنه بی‌صدا نادیده گرفته می‌شود؛ همان چیزی که فصلِ ۳ نشان داد.
2. **کلِ کار داخلِ یک تراکنش.** اگر وسطِ کپی چیزی خراب شود، یا همه‌اش انجام شده یا هیچ‌کدام. **حالتِ میانی یعنی جدولی که نه قدیمی است و نه جدید.** نامِ این خاصیت اتمی بودن است و ترمِ ۵ فصلِ ۵ کاملاً بازش می‌کند؛ فعلاً همین‌قدر بدان که `BEGIN` تا `COMMIT` یک واحدِ تقسیم‌ناپذیر است، و اینکه `BEGIN` باید **داخلِ** خودِ اسکریپت باشد. چرا، چند خط پایین‌تر می‌بینی.
3. **`PRAGMA foreign_key_check` قبل از `COMMIT`.** چون پرچم خاموش بوده، هر ارجاعِ خرابی که در این فاصله ساخته شده باشد بی‌صدا مانده. **این تنها فرصتِ گرفتنش قبل از قطعی شدنِ کار است.**

> 🔧 **اگر کار نکرد:** اگر `PRAGMA` را بعد از `BEGIN` بزنی، **هیچ خطایی نمی‌گیری و پرچم روشن می‌ماند.** خطر دقیقاً همین است. و یک تلهٔ خواهرِ همان، که این هم پیام ندارد:

</div>

```python
con.execute("BEGIN")
try:
    con.executescript("PRAGMA foreign_keys = OFF; SELECT 1;")
    print("executescript اجرا شد — و تراکنش قبلی را commit کرد.")
    con.execute("BEGIN")
except Exception as error:
    print(type(error).__module__ + "." + type(error).__name__, "|", error)
con.rollback()
con.execute("PRAGMA foreign_keys = ON")     # این اسکریپت پرچم را واقعاً خاموش کرده بود
```

```text
executescript اجرا شد — و تراکنش قبلی را commit کرد.
```

<div dir="rtl">

**`executescript` قبل از اجرا هر تراکنشِ بازی را `commit` می‌کند، بی‌صدا.**

یعنی یک `con.execute("BEGIN")` پیش از `executescript` هیچ اثری ندارد: تراکنشش همان لحظه بسته می‌شود و بعد هر فرمانِ اسکریپت جداگانه قطعی می‌شود. اگر بازسازیِ بخشِ ۵ این‌طور نوشته می‌شد و فرمانی وسطش خطا می‌داد، جدولِ قدیمی حذف شده بود و راهِ برگشتی نبود — **و آن حالتِ میانی همان چیزی است که بند ۲ می‌گفت نباید بشود.** به همین دلیل `BEGIN` داخلِ خودِ اسکریپت آمد، و `commit` را بعد از `foreign_key_check` از پایتون زدیم. خطِ «تراکنش هنوز باز است؟» در خروجیِ آن بخش همین را نشان می‌دهد.

**و بندِ اصلی: هیچ‌کدام از این دو تله خطا نمی‌دهند.** در کارِ با مهاجرت، خطا نگرفتن هیچ نشانه‌ای از درست بودن نیست؛ تنها شاهد، شمارشی است که بعدش می‌گیری.

## ۶. `PRAGMA user_version`: شمارهٔ نسخهٔ اسکیما

هر پایگاه دادهٔ `SQLite` یک عددِ صحیح در سرصفحه‌اش دارد که هیچ استفادهٔ داخلی ندارد و **کاملاً مالِ توست.** جای درستش شمارهٔ نسخهٔ اسکیماست.

**در فهرستِ زیر یک فرمانِ تازه هم هست:** `CREATE INDEX` یک ساختارِ کمکی می‌سازد که پیدا کردنِ سطرها را سریع‌تر می‌کند. **فعلاً همین‌قدر بدان؛ ترمِ ۵ فصلِ ۳ کاملاً بازش می‌کند.** دلیلِ آمدنش اینجا این است که **بی‌خطرترین مهاجرتِ ممکن است:** نه ستونی اضافه می‌کند، نه سطری، نه چیزی برمی‌دارد — پس هر نسخه‌ای از کد، قدیمی یا جدید، بعدش دقیقاً همان‌طور کار می‌کند که قبلش.

</div>

```python
MIGRATIONS = [
    (1, "ALTER TABLE members_v1 ADD COLUMN joined_at TEXT"),
    (2, "UPDATE members_v1 SET joined_at = '2020-01-01' WHERE joined_at IS NULL"),
    (3, "CREATE INDEX IF NOT EXISTS idx_members_city ON members_v1(city)"),
]


def migrate(connection):
    """هر مهاجرتِ اجرانشده را می‌زند و شماره را جلو می‌برد. اجرای دوباره بی‌خطر است."""
    version = connection.execute("PRAGMA user_version").fetchone()[0]
    applied = []
    for number, statement in MIGRATIONS:
        if number <= version:
            continue
        connection.execute(statement)
        # شماره بخشی از متنِ فرمان است نه یک مقدار، و از فهرستِ خودمان می‌آید.
        connection.execute(f"PRAGMA user_version = {number}")
        applied.append(number)
    connection.commit()
    return applied


print("نسخهٔ اسکیما در ابتدا:", con.execute("PRAGMA user_version").fetchone()[0])
print("اجرای اول  → مهاجرت‌های اعمال‌شده:", migrate(con))
print("نسخهٔ اسکیما:", con.execute("PRAGMA user_version").fetchone()[0])
print("اجرای دوم  → مهاجرت‌های اعمال‌شده:", migrate(con))
print("نسخهٔ اسکیما:", con.execute("PRAGMA user_version").fetchone()[0])
print()
print(q("SELECT joined_at, COUNT(*) AS rows FROM members_v1 GROUP BY joined_at"))
```

```text
نسخهٔ اسکیما در ابتدا: 0
اجرای اول  → مهاجرت‌های اعمال‌شده: [1, 2, 3]
نسخهٔ اسکیما: 3
اجرای دوم  → مهاجرت‌های اعمال‌شده: []
نسخهٔ اسکیما: 3

    joined_at  rows
0  2020-01-01   300
```

<div dir="rtl">

**اجرای دوم هیچ کاری نکرد، و همین کلِ ارزشِ این الگوست.**

برنامه‌ای که این تابع را در هر بالا آمدنش صدا می‌زند، **هیچ‌وقت لازم نیست بداند پایگاه داده در چه وضعی است.** پایگاه دادهٔ تازه از صفر تا آخر می‌آید، پایگاه دادهٔ سه‌ماهه فقط مهاجرت‌های تازه را می‌گیرد، و پایگاه دادهٔ به‌روز هیچ چیزی نمی‌گیرد.

**سه قاعده که این الگو را از یک اسباب‌بازی به یک ابزارِ واقعی تبدیل می‌کنند:**

1. **مهاجرتِ ثبت‌شده هرگز ویرایش نمی‌شود.** اگر مهاجرتِ شمارهٔ ۲ اشتباه بود، مهاجرتِ شمارهٔ ۴ درستش می‌کند. **پایگاه دادهٔ کسی که ۲ را قبلاً اجرا کرده، نسخهٔ ویرایش‌شده را هرگز نمی‌بیند.**
2. **شماره‌ها هیچ‌وقت دوباره استفاده نمی‌شوند** — همان درسِ `AUTOINCREMENT` فصلِ ۲، این بار روی نسخهٔ اسکیما.
3. **هر مهاجرت باید برای کدِ نسخهٔ قبل هم بی‌خطر باشد.** یعنی همان قاعدهٔ فقط-افزودنیِ بخشِ ۲، این بار به‌عنوان یک شرطِ پذیرش.

> 📏 **اندازه بگیر:** **یک سطر یعنی چه؟** در `members_v1` یک سطر یک عضو است و این در تمامِ فصل عوض نشد — **و همین چیزی است که یک مهاجرتِ سالم را تعریف می‌کند: ساختار عوض می‌شود، دانه‌بندی نه.** **با کدام شمارشِ دوم سنجیدی؟** با سه‌تا: `old_report()` و `new_report()` که هر دو ۳۰۰ دادند، شمارشِ سطرهایی که دو ستونشان نمی‌خوانند که صفر شد، و تعدادِ سطرها قبل و بعد از بازسازی که هر دو ۳۰۰ ماند. **چه کسی از قلم افتاد؟** در بخشِ ۵ هیچ‌کس، چون قبلش شمردیم که قیدِ تازه صفر سطر رد می‌کند. **ولی قیدِ یکتاییِ تلفن را نگذاشتیم و ۱۲ سطرِ تکراری هنوز سرِ جایشان‌اند** — یعنی مسئله حل نشد، فقط اعلام شد.

> 🤖 **از دستیارت بپرس:** «چرا می‌گویند مهاجرتِ پایگاه داده باید فقط-افزودنی باشد؟» بعد این را بپرس: **«اگر بخواهم نامِ یک ستون را عوض کنم و سامانه‌ام لحظه‌ای هم نباید قطع شود، چند انتشار طول می‌کشد و در هر انتشار دقیقاً چه اتفاقی می‌افتد؟»** — جوابِ درست دستِ‌کم سه مرحله دارد: افزودن و پر کردن، نوشتن در هر دو، و حذف. اگر جواب گفت «یک `ALTER TABLE` کافی است»، با بخشِ ۱ ردش کن.

## واژه‌های تازهٔ این فصل

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| migration | مایگریشن | مهاجرت؛ تغییرِ اسکیمای شماره‌دار که دقیقاً یک بار اجرا می‌شود |
| additive migration | ادیتیو مایگریشن | مهاجرتِ فقط-افزودنی؛ چیزی اضافه می‌کند و چیزی برنمی‌دارد |
| backward compatible | بک‌ورد کامپتیبل | سازگار با نسخهٔ قبلیِ کد |
| dual write | دوال رایت | نوشتن در ستونِ قدیمی و جدید، هم‌زمان |
| table rebuild | تیبل ری‌بیلد | بازسازیِ جدول وقتی `ALTER` کافی نیست |
| user_version | یوزر ورژن | عددی در سرصفحهٔ فایل که نسخهٔ اسکیما را نگه می‌دارد |

<div dir="rtl">

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا حذفِ یک ستون دو انتشار طول می‌کشد؟

**تمرینِ اجباری:** یک مهاجرتِ چهارم به فهرستِ بخشِ ۶ اضافه کن که ستونِ `national_id` را به `members_v1` بیفزاید و از `members_raw` پرش کند. **بعد `migrate` را دو بار صدا بزن و هر بار خروجی و نسخهٔ اسکیما را چاپ کن.** حالا جوابِ سؤالِ اصلی را بنویس: **اگر همین مهاجرت را روی پایگاه داده‌ای اجرا کنی که نسخه‌اش از قبل ۴ است چه می‌شود، و اگر متنِ مهاجرتِ شمارهٔ ۲ را عوض کنی چه؟**

**تمرینِ ستاره‌دار ⭐:** قیدِ یکتاییِ تلفن را واقعاً اعمال کن. اول ۱۲ سطرِ تکراری را پیدا کن و تصمیم بگیر با هرکدام چه می‌کنی — **و تصمیمت را در یک جمله بنویس، چون این یک تصمیمِ فنی نیست.** بعد `CREATE UNIQUE INDEX` را بزن. حالا سؤالِ سخت: **این کار مهاجرتِ فقط-افزودنی است یا نه؟** جوابت باید بگوید یک `index` یکتا چه چیزی را برای کدِ نسخهٔ قبل عوض می‌کند — راهنمایی: کدِ قدیمی هنوز `INSERT` می‌زند.

## در فصل بعد

هشت فصل ابزار جمع کردیم و هر کدامشان روی تکه‌ای از داده کار کردند. فصلِ آخرِ این ترم هیچ چیزِ تازه‌ای یاد نمی‌دهد و به‌جایش کارِ کامل را تحویل می‌دهد: **از همان فایلِ صادراتیِ کثیفِ فصلِ ۱ تا یک اسکیمای کامل با کلید و ارجاع و قید و زمانِ درست، به‌علاوهٔ یک مهاجرتِ واقعی روی همان.**

و آخرش همان سه پرسشِ همیشگی را از خودمان می‌پرسیم: **یک سطر یعنی چه، با کدام شمارشِ دوم سنجیدیم، و چه کسی از قلم افتاد.**

</div>

---
Source: https://yaadestan.com/courses/avand/lessons/t4/s08-migrations (یادستان, Yaadestan)
