命令¶

您將使用幾個命令與遷移以及 Django 對資料庫結構描述的處理互動

• migrate，負責應用和取消應用遷移。

• makemigrations，負責根據您對模型所做的變更建立新的遷移。

• sqlmigrate，顯示遷移的 SQL 陳述式。

• showmigrations，列出專案的遷移及其狀態。

您應該將遷移視為資料庫結構描述的版本控制系統。makemigrations 負責將您的模型變更打包成單獨的遷移檔案 - 類似於 commit - 而 migrate 負責將它們應用到您的資料庫。

每個應用程式的遷移檔案都位於該應用程式內的「migrations」目錄中，並且設計為作為其程式碼庫的一部分提交和發布。您應該在您的開發機器上進行一次，然後在您同事的機器、您的預備機器，以及最終在您的生產機器上執行相同的遷移。

遷移將以相同的方式在相同的資料集上執行並產生一致的結果，這表示您在開發和預備環境中所看到的內容，在相同的條件下，與在生產環境中發生的情況完全相同。

Django 將會對您模型或欄位的任何變更建立遷移 - 即使是不影響資料庫的選項 - 因為它正確重建欄位的唯一方法是擁有歷史記錄中的所有變更，並且您稍後可能需要在某些資料遷移中使用這些選項（例如，如果您已設定自訂驗證器）。

後端支援¶

所有 Django 隨附的後端都支援遷移，以及任何第三方後端，如果它們已編寫程式以支援結構描述變更（透過 SchemaEditor 類別完成）。

然而，在結構描述遷移方面，某些資料庫比其他資料庫更具能力；一些注意事項如下所述。

工作流程¶

Django 可以為您建立遷移。對您的模型進行變更 - 例如，新增欄位並移除模型 - 然後執行 makemigrations

$ python manage.py makemigrations
Migrations for 'books':
  books/migrations/0003_auto.py:
    ~ Alter field author on book

您的模型將被掃描並與目前包含在您的遷移檔案中的版本進行比較，然後將寫出新的遷移集。請務必閱讀輸出，以查看 makemigrations 認為您已變更的內容 - 它並不完美，對於複雜的變更，它可能無法偵測到您預期的內容。

當您擁有新的遷移檔案後，您應該將它們應用到您的資料庫，以確保它們按預期運作

$ python manage.py migrate
Operations to perform:
  Apply all migrations: books
Running migrations:
  Rendering model states... DONE
  Applying books.0003_auto... OK

遷移應用後，將遷移和模型變更作為單一提交提交到您的版本控制系統 - 這樣，當其他開發人員（或您的生產伺服器）簽出程式碼時，他們將同時取得模型變更和隨附的遷移。

如果您想要為遷移提供一個有意義的名稱而不是產生的名稱，您可以使用 makemigrations --name 選項

$ python manage.py makemigrations --name changed_my_model your_app_label

交易¶

在支援 DDL 交易的資料庫（SQLite 和 PostgreSQL）上，所有遷移操作預設都會在單一交易中執行。相反地，如果資料庫不支援 DDL 交易（例如 MySQL、Oracle），則所有操作都將在沒有交易的情況下執行。

您可以透過將 atomic 屬性設定為 False 來防止遷移在交易中執行。例如

from django.db import migrations


class Migration(migrations.Migration):
    atomic = False

也可以使用 atomic() 或透過將 atomic=True 傳遞給 RunPython，在交易內執行部分遷移。請參閱 非原子遷移 以取得更多詳細資訊。

相依性¶

雖然遷移是針對每個應用程式，但您的模型所暗示的表格和關係太複雜，無法一次為一個應用程式建立。當您進行需要執行其他操作的遷移時 - 例如，您在 books 應用程式中新增一個 ForeignKey 到您的 authors 應用程式 - 產生的遷移將包含對 authors 中遷移的相依性。

這表示當您執行遷移時，authors 遷移會先執行並建立 ForeignKey 參考的表格，然後建立 ForeignKey 欄位的遷移會在之後執行並建立約束。如果沒有發生這種情況，遷移將嘗試建立 ForeignKey 欄位，而沒有它所參考的表格存在，並且您的資料庫會擲回錯誤。

這種相依性行為會影響您限制為單一應用程式的大多數遷移操作。限制為單一應用程式（在 makemigrations 或 migrate 中）是一個盡力而為的承諾，而不是保證；任何其他需要用於正確取得相依性的應用程式都將會被使用。

沒有遷移的應用程式不得與有遷移的應用程式建立關聯（ForeignKey、ManyToManyField 等）。有時它可能可以運作，但不受支援。

遷移檔案¶

遷移以磁碟格式儲存，這裡稱為「遷移檔案」。這些檔案實際上是普通的 Python 檔案，具有約定的物件佈局，以宣告式風格編寫。

一個基本的遷移檔案看起來像這樣

from django.db import migrations, models


class Migration(migrations.Migration):
    dependencies = [("migrations", "0001_initial")]

    operations = [
        migrations.DeleteModel("Tribble"),
        migrations.AddField("Author", "rating", models.IntegerField(default=0)),
    ]

當 Django 載入遷移檔案（作為一個 Python 模組）時，它會尋找一個名為 Migration 的 django.db.migrations.Migration 的子類別。然後它會檢查這個物件的四個屬性，其中只有兩個屬性在大多數情況下使用

• dependencies，這個遷移所依賴的遷移列表。

• operations，一個定義這個遷移所做事情的 Operation 類別列表。

操作是關鍵；它們是一組宣告式的指令，告訴 Django 需要進行哪些架構變更。Django 會掃描它們，並建立所有應用程式所有架構變更的記憶體表示，並使用它來產生進行架構變更的 SQL。

該記憶體結構也用於計算您的模型與目前的遷移狀態之間的差異；Django 會按照順序在記憶體中的模型集上執行所有變更，以得出您上次執行 makemigrations 時的模型狀態。然後，它會使用這些模型與 models.py 檔案中的模型進行比較，以計算出您所做的變更。

您應該很少需要手動編輯遷移檔案，但如果您需要，完全可以手動編寫它們。一些更複雜的操作是無法自動偵測到的，只能透過手寫的遷移來使用，所以如果您必須編輯它們，請不要感到害怕。

class MyManager(models.Manager):
    use_in_migrations = True


class MyModel(models.Model):
    objects = MyManager()

class MyManager(MyBaseManager.from_queryset(CustomQuerySet)):
    use_in_migrations = True


class MyModel(models.Model):
    objects = MyManager()

將遷移新增到應用程式¶

新的應用程式會預先配置為接受遷移，因此您可以在進行一些變更後執行 makemigrations 來新增遷移。

如果您的應用程式已經有模型和資料庫表，但還沒有遷移（例如，您是針對以前的 Django 版本建立的），您需要透過執行以下命令將其轉換為使用遷移

$ python manage.py makemigrations your_app_label

這會為您的應用程式建立一個新的初始遷移。現在，執行 python manage.py migrate --fake-initial，Django 會偵測到您有一個初始遷移，而且它想要建立的資料表已存在，並將遷移標記為已應用。（如果沒有 migrate --fake-initial 標誌，該命令會因為它想要建立的資料表已存在而錯誤退出。）

請注意，這僅在滿足以下兩個條件的情況下才有效

• 自從您建立資料表以來，您沒有變更您的模型。為了使遷移正常運作，您必須先建立初始遷移，然後再進行變更，因為 Django 會將變更與遷移檔案進行比較，而不是資料庫。

• 您沒有手動編輯您的資料庫 - Django 將無法偵測到您的資料庫與您的模型不符，您只會在遷移嘗試修改這些資料表時收到錯誤。

反轉遷移¶

可以透過傳遞上一個遷移的編號，使用 migrate 反轉遷移。例如，要反轉遷移 books.0003

$ python manage.py migrate books 0002
Operations to perform:
  Target specific migration: 0002_auto, from books
Running migrations:
  Rendering model states... DONE
  Unapplying books.0003_auto... OK

...\> py manage.py migrate books 0002
Operations to perform:
  Target specific migration: 0002_auto, from books
Running migrations:
  Rendering model states... DONE
  Unapplying books.0003_auto... OK

如果要反轉應用程式的所有已應用遷移，請使用名稱 zero

$ python manage.py migrate books zero
Operations to perform:
  Unapply all migrations: books
Running migrations:
  Rendering model states... DONE
  Unapplying books.0002_auto... OK
  Unapplying books.0001_initial... OK

...\> py manage.py migrate books zero
Operations to perform:
  Unapply all migrations: books
Running migrations:
  Rendering model states... DONE
  Unapplying books.0002_auto... OK
  Unapplying books.0001_initial... OK

如果遷移包含任何不可逆的操作，則該遷移是不可逆的。嘗試反轉此類遷移將會引發 IrreversibleError

$ python manage.py migrate books 0002
Operations to perform:
  Target specific migration: 0002_auto, from books
Running migrations:
  Rendering model states... DONE
  Unapplying books.0003_auto...Traceback (most recent call last):
django.db.migrations.exceptions.IrreversibleError: Operation <RunSQL  sql='DROP TABLE demo_books'> in books.0003_auto is not reversible

...\> py manage.py migrate books 0002
Operations to perform:
  Target specific migration: 0002_auto, from books
Running migrations:
  Rendering model states... DONE
  Unapplying books.0003_auto...Traceback (most recent call last):
django.db.migrations.exceptions.IrreversibleError: Operation <RunSQL  sql='DROP TABLE demo_books'> in books.0003_auto is not reversible

歷史模型¶

當您執行遷移時，Django 會根據儲存在遷移檔案中的模型的歷史版本來運作。如果您使用 RunPython 操作編寫 Python 程式碼，或者您的資料庫路由器上有 allow_migrate 方法，您需要使用這些歷史模型版本，而不是直接匯入它們。

由於無法序列化任意的 Python 程式碼，這些歷史模型不會包含您定義的任何自訂方法。然而，它們會具有相同的欄位、關聯、管理員（僅限於具有 use_in_migrations = True 的管理員）和 Meta 選項（也會進行版本控制，因此它們可能與您目前的選項不同）。

在欄位選項（例如 upload_to 和 limit_choices_to）中以及具有 use_in_migrations = True 的管理員的模型管理員宣告中對函式的參照，都會在遷移中進行序列化，因此只要有遷移參照它們，就需要保留這些函式和類別。任何自訂模型欄位也需要保留，因為這些欄位是由遷移直接匯入的。

此外，模型的具體基底類別會儲存為指標，因此只要有遷移包含對它們的參照，您就必須始終保留基底類別。好處是，這些基底類別的方法和管理員會正常繼承，因此如果您絕對需要存取這些方法和管理員，您可以選擇將它們移至超類別中。

若要移除舊的參照，您可以壓縮遷移，或者，如果參照不多，則可以將它們複製到遷移檔案中。

移除模型欄位時的考量¶

與上一節中描述的「參照歷史函式」的考量類似，如果您從專案或協力廠商應用程式中移除自訂模型欄位，若這些欄位在舊遷移中被參照，則會導致問題。

為了協助解決此情況，Django 提供了一些模型欄位屬性，以利用系統檢查框架來協助模型欄位的棄用。

將 system_check_deprecated_details 屬性新增至您的模型欄位，如下所示

class IPAddressField(Field):
    system_check_deprecated_details = {
        "msg": (
            "IPAddressField has been deprecated. Support for it (except "
            "in historical migrations) will be removed in Django 1.9."
        ),
        "hint": "Use GenericIPAddressField instead.",  # optional
        "id": "fields.W900",  # pick a unique ID for your field.
    }

在您選擇的棄用期間（Django 本身欄位的兩個或三個功能版本）之後，將 system_check_deprecated_details 屬性變更為 system_check_removed_details，並更新字典，如下所示

class IPAddressField(Field):
    system_check_removed_details = {
        "msg": (
            "IPAddressField has been removed except for support in "
            "historical migrations."
        ),
        "hint": "Use GenericIPAddressField instead.",
        "id": "fields.E900",  # pick a unique ID for your field.
    }

您應該保留欄位在資料庫遷移中運作所需的方法，例如 __init__()、deconstruct() 和 get_internal_type()。只要存在任何參照該欄位的遷移，請保留此存根欄位。例如，在壓縮遷移並移除舊遷移後，您應該可以完全移除該欄位。

資料遷移¶

除了變更資料庫綱要之外，您也可以使用遷移來變更資料庫中的資料本身，如果需要，也可以與綱要結合使用。

變更資料的遷移通常稱為「資料遷移」；最好將它們寫成單獨的遷移，與您的綱要遷移並列。

Django 無法像處理綱要遷移一樣自動為您產生資料遷移，但編寫它們並不難。Django 中的遷移檔案是由操作組成，而您用於資料遷移的主要操作是RunPython。

首先，建立一個您可以從中工作的空遷移檔案（Django 會將該檔案放在正確的位置，建議一個名稱，並為您新增相依性）

python manage.py makemigrations --empty yourappname

然後，開啟該檔案；它應該看起來像這樣

# Generated by Django A.B on YYYY-MM-DD HH:MM
from django.db import migrations


class Migration(migrations.Migration):
    dependencies = [
        ("yourappname", "0001_initial"),
    ]

    operations = []

現在，您只需要建立一個新函式，並讓RunPython使用它。RunPython期望一個可呼叫物件作為其引數，該可呼叫物件接受兩個引數 - 第一個是應用程式註冊表，其中已載入所有模型的歷史版本，以符合遷移在您的歷史記錄中所處的位置，第二個是SchemaEditor，您可以使用它來手動執行資料庫綱要變更（但請注意，這樣做可能會混淆遷移自動偵測器！）

讓我們編寫一個遷移，該遷移會使用 first_name 和 last_name 的組合值來填入我們新的 name 欄位（我們已經清醒地意識到並非所有人都有名字和姓氏）。我們只需要使用歷史模型並迭代各行

from django.db import migrations


def combine_names(apps, schema_editor):
    # We can't import the Person model directly as it may be a newer
    # version than this migration expects. We use the historical version.
    Person = apps.get_model("yourappname", "Person")
    for person in Person.objects.all():
        person.name = f"{person.first_name} {person.last_name}"
        person.save()


class Migration(migrations.Migration):
    dependencies = [
        ("yourappname", "0001_initial"),
    ]

    operations = [
        migrations.RunPython(combine_names),
    ]

完成後，我們可以照常執行 python manage.py migrate，並且資料遷移將與其他遷移一起執行。

您可以將第二個可呼叫物件傳遞給RunPython，以執行您希望在向後遷移時執行的任何邏輯。如果省略此可呼叫物件，則向後遷移會引發例外。

class Migration(migrations.Migration):
    dependencies = [
        ("app1", "0001_initial"),
        # added dependency to enable using models from app2 in move_m1
        ("app2", "0004_foobar"),
    ]

    operations = [
        migrations.RunPython(move_m1),
    ]

壓縮遷移¶

建議您隨意進行遷移，而無需擔心有多少個遷移；遷移程式碼經過最佳化處理，可以一次處理數百個遷移，而不會有太大的速度下降。但是，最終您會希望從數百個遷移縮減為少數幾個遷移，這就是壓縮的用武之地。

壓縮是指將現有的多個遷移縮減為一個（或有時是幾個）仍然表示相同變更的遷移。

Django 通過取得您所有現有的遷移、提取它們的 Operation，然後將它們按順序排列，然後在其上執行最佳化工具以嘗試縮短列表的長度來執行此操作 - 例如，它知道 CreateModel 和 DeleteModel 相互抵消，並且它知道 AddField 可以捲入 CreateModel 中。

一旦操作順序被盡可能縮減（可能縮減的量取決於您的模型之間的緊密程度，以及您是否有任何 RunSQL 或 RunPython 操作（除非它們被標記為 elidable，否則無法透過它們進行最佳化）），Django 會將其寫回一組新的遷移檔案中。

這些檔案會被標記為取代先前壓縮的遷移檔案，因此它們可以與舊的遷移檔案共存，而 Django 會根據您在歷史記錄中的位置，智能地在它們之間切換。如果您仍在進行壓縮的遷移集合中，它會繼續使用它們，直到到達結尾，然後切換到壓縮後的歷史記錄；而新的安裝將會使用新的壓縮遷移，並跳過所有舊的遷移。

這使您能夠進行壓縮，而不會干擾目前在生產環境中尚未完全更新的系統。建議的流程是先壓縮，保留舊檔案，提交並發布，等待所有系統都使用新版本升級（或者如果您是第三方專案，請確保您的使用者依序升級版本，不要跳過任何版本），然後刪除舊檔案，提交並進行第二次發布。

支援這一切的命令是 squashmigrations - 傳遞您要壓縮的應用程式標籤和遷移名稱，它就會開始工作。

$ ./manage.py squashmigrations myapp 0004
Will squash the following migrations:
 - 0001_initial
 - 0002_some_change
 - 0003_another_change
 - 0004_undo_something
Do you wish to proceed? [y/N] y
Optimizing...
  Optimized from 12 operations to 7 operations.
Created new squashed migration /home/andrew/Programs/DjangoTest/test/migrations/0001_squashed_0004_undo_something.py
  You should commit this migration but leave the old ones in place;
  the new migration will be used for new installs. Once you are sure
  all instances of the codebase have applied the migrations you squashed,
  you can delete them.

如果您想要設定壓縮遷移的名稱，而不是使用自動產生的名稱，請使用 squashmigrations --squashed-name 選項。

請注意，Django 中的模型相互依賴關係可能變得非常複雜，壓縮可能會導致無法運行的遷移；可能是優化錯誤（在這種情況下，您可以嘗試使用 --no-optimize 再次嘗試，但您也應該報告問題），或者出現 CircularDependencyError，在這種情況下，您可以手動解決它。

若要手動解決 CircularDependencyError，請將循環依賴迴圈中的一個 ForeignKey 分解到一個單獨的遷移中，並將對其他應用程式的依賴關係與其一起移動。如果您不確定，請參閱當被要求從您的模型建立全新的遷移時，makemigrations 如何處理這個問題。在 Django 的未來版本中，將會更新 squashmigrations 以嘗試自行解決這些錯誤。

一旦您壓縮了遷移，您應該將它與它所取代的遷移一起提交，並將此變更分發到您應用程式的所有執行個體，確保它們執行 migrate 以將變更儲存在它們的資料庫中。

然後您必須將壓縮的遷移轉換為正常的遷移，方法是

• 刪除它所取代的所有遷移檔案。

• 更新所有依賴已刪除遷移的遷移，使其改為依賴壓縮的遷移。

• 移除壓縮遷移的 Migration 類別中的 replaces 屬性（這是 Django 判斷它是否為壓縮遷移的方式）。

序列化值¶

遷移是包含您模型舊定義的 Python 檔案 - 因此，為了寫入它們，Django 必須取得您模型的目前狀態，並將它們序列化到檔案中。

雖然 Django 可以序列化大多數東西，但有些東西我們無法將其序列化為有效的 Python 表示形式 - 沒有 Python 標準說明如何將值轉換回程式碼（repr() 僅適用於基本值，並且沒有指定導入路徑）。

Django 可以序列化以下內容

• int、float、bool、str、bytes、None、NoneType

• list、set、tuple、dict、range。

• datetime.date、datetime.time 和 datetime.datetime 實例（包括那些具有時區意識的實例）

• decimal.Decimal 實例

• enum.Enum 和 enum.Flag 實例

• uuid.UUID 實例

• 具有可序列化 func、args 和 keywords 值的 functools.partial() 和 functools.partialmethod 實例。

• 來自 pathlib 的純粹和具體路徑物件。具體路徑會轉換為它們的純粹路徑等效項，例如 pathlib.PosixPath 轉換為 pathlib.PurePosixPath。

• os.PathLike 實例，例如 os.DirEntry，它們會使用 os.fspath() 轉換為 str 或 bytes。

• 封裝可序列化值的 LazyObject 實例。

• 列舉類型（例如 TextChoices 或 IntegerChoices）的實例。

• 任何 Django 欄位

• 任何函式或方法參考（例如 datetime.datetime.today）（必須在模組的頂層範圍內）

  • 如果使用 functools.wraps() 正確封裝，則可以裝飾函式

  • 明確支援 functools.cache() 和 functools.lru_cache() 裝飾器

• 從類別主體內使用的未綁定方法

• 任何類別參考（必須在模組的頂層範圍內）

• 任何具有自訂 deconstruct() 方法的項目（請參閱下方）

Django 無法序列化

• 巢狀類別

• 任意類別實例（例如 MyClass(4.3, 5.7)）

• Lambda 函式

from decimal import Decimal

from django.db.migrations.serializer import BaseSerializer
from django.db.migrations.writer import MigrationWriter


class DecimalSerializer(BaseSerializer):
    def serialize(self):
        return repr(self.value), {"from decimal import Decimal"}


MigrationWriter.register_serializer(Decimal, DecimalSerializer)

from django.utils.deconstruct import deconstructible


@deconstructible
class MyCustomClass:
    def __init__(self, foo=1):
        self.foo = foo
        ...

    def __eq__(self, other):
        return self.foo == other.foo

支援多個 Django 版本¶

如果您是具有模型的第三方應用程式的維護者，您可能需要發布支援多個 Django 版本的遷移。在這種情況下，您應該 **使用您希望支援的最低 Django 版本** 執行 makemigrations。

遷移系統將根據與 Django 其餘部分相同的策略來維持向後相容性，因此在 Django X.Y 上產生的遷移檔案應該在 Django X.Y+1 上保持不變地執行。但是，遷移系統不保證向前相容性。可能會新增新功能，並且使用較新版本的 Django 產生的遷移檔案可能無法在較舊的版本上執行。