Durable Object 类迁移（旧版）

迁移是从类名到运行时状态的映射过程。此过程向 Workers 运行时传达变更，并为运行时提供如何处理这些变更的指令。

要应用迁移，您需要：

编辑 Wrangler 配置文件（请参阅迁移 Wrangler 配置）。
使用 npx wrangler deploy 重新部署 Worker。

在以下情况下必须启动迁移过程：

创建新的 Durable Object 类。
重命名 Durable Object 类。
删除 Durable Object 类。
转移现有 Durable Objects 类。

创建迁移

最常执行的迁移是新建类迁移，它告知运行时正在上传新的 Durable Object 类。这也是创建第一个 Durable Object 类时需要的迁移。

要应用新建类迁移：

在您的 Wrangler 配置文件中添加以下行：

{
  "migrations": [
    {
      "tag": "<v1>", // 迁移标识符。这在每个迁移条目中应该是唯一的
      "new_sqlite_classes": [ // 新类的数组
        "<NewDurableObjectClass>"
      ]
    }
  ]
}

[[migrations]]
tag = "<v1>"
new_sqlite_classes = [ "<NewDurableObjectClass>" ]

新建类迁移包含：

用于标识迁移的 tag。
包含新 Durable Object 类的 new_sqlite_classes 数组。

确保在您的 Worker 代码中引用了正确的 Durable Object 类名。
部署 Worker。

新建类迁移示例 (Create migration example)

要创建新的 Durable Object 绑定 DURABLE_OBJECT_A，您的 Wrangler 配置文件应该类似于以下内容：

{
	// 创建一个新的 Durable Object 类
	"durable_objects": {
		"bindings": [
			{
				"name": "DURABLE_OBJECT_A",
				"class_name": "DurableObjectAClass"
			}
		]
	},
	// 为新建类迁移添加以下行。
	"migrations": [
		{
			"tag": "v1",
			"new_sqlite_classes": [
				"DurableObjectAClass"
			]
		}
	]
}

[[durable_objects.bindings]]
name = "DURABLE_OBJECT_A"
class_name = "DurableObjectAClass"

[[migrations]]
tag = "v1"
new_sqlite_classes = [ "DurableObjectAClass" ]

使用键值存储创建 Durable Object 类

在 Worker 的 Wrangler 文件中对迁移使用 new_classes，以使用键值存储后端创建 Durable Object 类：

{
	"migrations": [
		{
			"tag": "v1", // 每个条目应该唯一
			"new_classes": [
				// 新类的数组
				"MyDurableObject",
			],
		},
	],
}

[[migrations]]
tag = "v1"
new_classes = [ "MyDurableObject" ]

删除类迁移

运行删除类迁移将删除与已删除类关联的所有 Durable Object，包括其所有存储的数据。

在首先确保您不再依赖该 Worker 内的 Durable Object 之前，请勿对类运行删除类迁移，即首先从 Worker 中删除绑定。
在删除之前，请将任何重要数据复制到其他位置。
您无需对已重命名或转移的类运行删除类迁移。

要应用删除类迁移：

从 Wrangler 配置文件中删除您希望删除的类的绑定。
从您的 Worker 代码中删除您希望删除的类的引用。

在您的 Wrangler 配置文件中添加以下行。

{
  "migrations": [
    {
      "tag": "<v2>", // 迁移标识符。这在每个迁移条目中应该是唯一的
      "deleted_classes": [ // 已删除类名的数组
        "<ClassToDelete>"
      ]
    }
  ]
}

[[migrations]]
tag = "<v2>"
deleted_classes = [ "<ClassToDelete>" ]

删除类迁移包含：

用于标识迁移的 tag。
包含已删除 Durable Object 类的 deleted_classes 数组。

部署 Worker。

删除类迁移示例 (Delete migration example)

要删除 Durable Object 绑定 DEPRECATED_OBJECT，您的 Wrangler 配置文件应该类似于以下内容：

{
	// 删除 DeprecatedObjectClass DO 的绑定
	// {"durable_objects": {"bindings": [
	//   {
	//     "name": "DEPRECATED_OBJECT",
	//     "class_name": "DeprecatedObjectClass"
	//   }
	// ]}}
	"migrations": [
		{
			"tag": "v3", // 每个条目应该唯一
			"deleted_classes": [ // 已删除类的数组
				"DeprecatedObjectClass"
			]
		}
	]
}

[[migrations]]
tag = "v3"
deleted_classes = [ "DeprecatedObjectClass" ]

重命名类迁移

重命名类迁移用于在同一个 Worker 代码文件中的两个 Durable Object 类之间转移存储的 Durable Object。

要应用重命名类迁移：

通过以下方式编辑您的 Wrangler 配置文件，将以前的类名更新为新的类名：

{
  "durable_objects": {
    "bindings": [
      {
        "name": "<MY_DURABLE_OBJECT>",
        "class_name": "<UpdatedDurableObject>" // 将类名更新为新类名
      }
    ]
  },
  "migrations": [
    {
      "tag": "<v3>", // 迁移标识符。这在每个迁移条目中应该是唯一的
      "renamed_classes": [ // 重命名指令数组
        {
          "from": "<OldDurableObject>",
          "to": "<UpdatedDurableObject>"
        }
      ]
    }
  ]
}

[[durable_objects.bindings]]
name = "<MY_DURABLE_OBJECT>"
class_name = "<UpdatedDurableObject>"

[[migrations]]
tag = "<v3>"

  [[migrations.renamed_classes]]
  from = "<OldDurableObject>"
  to = "<UpdatedDurableObject>"

重命名类迁移包含：

用于标识迁移的 tag。
renamed_classes 数组，其中包含带有 from 和 to 属性的对象。
from 属性是旧的 Durable Object 类名。
to 属性是重命名后的 Durable Object 类名。

在您的 Worker 代码中引用新的 Durable Object 类名。
部署 Worker。

重命名类迁移示例 (Rename migration example)

要将 Durable Object 类从 OldName 重命名为 UpdatedName，您的 Wrangler 配置文件应该类似于以下内容：

{
	"durable_objects": {
		"bindings": [
			{
				"name": "MY_DURABLE_OBJECT",
				// 将绑定更新为新的类名。
				"class_name": "UpdatedName"
			}
		]
	},
	// 重命名类
	"migrations": [
		{
			"tag": "v3",
			"renamed_classes": [ // 重命名指令数组
				{
					"from": "OldName",
					"to": "UpdatedName"
				}
			]
		}
	]
}

[[durable_objects.bindings]]
name = "MY_DURABLE_OBJECT"
class_name = "UpdatedName"

[[migrations]]
tag = "v3"

  [[migrations.renamed_classes]]
  from = "OldName"
  to = "UpdatedName"

转移类迁移

转移类迁移用于在不同 Worker 代码文件中的两个 Durable Object 类之间转移存储的 Durable Object。

如果您想在同一个 Worker 代码文件中的两个 Durable Object 类之间转移存储的 Durable Object，请改用重命名类迁移。

要应用转移类迁移：

通过以下方式编辑您的 Wrangler 配置文件：

{
  "durable_objects": {
    "bindings": [
      {
        "name": "<MY_DURABLE_OBJECT>",
        "class_name": "<DestinationDurableObjectClass>"
      }
    ]
  },
  "migrations": [
    {
      "tag": "<v4>", // 迁移标识符。这在每个迁移条目中应该是唯一的
      "transferred_classes": [
        {
          "from": "<SourceDurableObjectClass>",
          "from_script": "<SourceWorkerScript>",
          "to": "<DestinationDurableObjectClass>"
        }
      ]
    }
  ]
}

[[durable_objects.bindings]]
name = "<MY_DURABLE_OBJECT>"
class_name = "<DestinationDurableObjectClass>"

[[migrations]]
tag = "<v4>"

  [[migrations.transferred_classes]]
  from = "<SourceDurableObjectClass>"
  from_script = "<SourceWorkerScript>"
  to = "<DestinationDurableObjectClass>"

转移类迁移包含：

用于标识迁移的 tag。
transferred_classes 数组，其中包含带有 from、from_script 和 to 属性的对象。
- from 属性是源 Durable Object 类的名称。
- from_script 属性是源 Worker 脚本的名称。
- to 属性是目标 Durable Object 类的名称。

确保在您的 Worker 代码中引用新的目标 Durable Object 类名。
部署 Worker。

转移类迁移示例 (Transfer migration example)

您可以将存储的 Durable Object 从名为 OldWorkerScript 的 Worker 脚本中的 DurableObjectExample 转移到 TransferredClass。您的新 Worker 代码（目标 Worker 代码）的 Wrangler 配置文件配置如下所示：

{
	// 目标 worker
	"durable_objects": {
		"bindings": [
			{
				"name": "MY_DURABLE_OBJECT",
				"class_name": "TransferredClass"
			}
		]
	},
	// 转移类
	"migrations": [
		{
			"tag": "v4",
			"transferred_classes": [
				{
					"from": "DurableObjectExample",
					"from_script": "OldWorkerScript",
					"to": "TransferredClass"
				}
			]
		}
	]
}

[[durable_objects.bindings]]
name = "MY_DURABLE_OBJECT"
class_name = "TransferredClass"

[[migrations]]
tag = "v4"

  [[migrations.transferred_classes]]
  from = "DurableObjectExample"
  from_script = "OldWorkerScript"
  to = "TransferredClass"

迁移 Wrangler 配置

迁移是通过 wrangler.toml 文件中的 [[migrations]] 配置键或 wrangler.jsonc 文件中的 migrations 键来执行的。
迁移需要一个迁移标签，该标签由每个迁移条目中的 tag 属性定义。
迁移标签被视为唯一的名称，用于确定已应用了哪些迁移。一旦给定的 Worker 代码设置了迁移标签，所有未来的 Worker 代码部署都必须包含迁移标签。
迁移列表是一个有序的表格数组，在您的 Wrangler 配置文件中指定为一个键。
您可以为每个环境以及顶层定义迁移。
- 顶层迁移在 Wrangler 配置文件的顶层 migrations 键中指定。
- 环境级迁移在 Wrangler 配置文件的 env 键内的 migrations 键中指定（[env.<environment_name>.migrations]）。
  - 示例 Wrangler 文件：
  wrangler.jsoncjsonc
```
{
  // 顶层默认迁移
  "migrations": [
    { "tag": "v1", "new_sqlite_classes": ["MyDurableObject"] },
  ],
  "env": {
    "staging": {
      // 针对 staging 环境的迁移覆盖
      "migrations": [
        { "tag": "v1-staging", "new_sqlite_classes": ["MyDurableObject"] },
      ],
    },
  },
}
```
- 如果迁移仅在顶层指定，而未在环境层指定，则环境将继承顶层迁移。
- 环境级的迁移会覆盖顶层的迁移。
所有迁移都会在部署时应用。每个迁移在每个环境中只能应用一次。
列表中的每个迁移都可以有多个指令，随着项目复杂度增加，可以指定多个迁移。

您无法在已部署的现有 Durable Object 类上启用 SQLite 存储后端，因此在以后的迁移中设置 new_sqlite_classes 将失败并报错。已部署类从键值存储后端到 SQLite 存储后端的自动迁移将在未来提供。