← Cloudflare Durable Objects / durable-objects / reference

Миграции классов Durable Object (устаревший способ)

Миграция представляет собой процесс сопоставления имени класса с состоянием среды выполнения. Этот процесс передаёт изменения в среду выполнения Workers и предоставляет ей инструкции о том, как обрабатывать эти изменения.

Чтобы применить миграцию, нужно:

1. Отредактируйте файл конфигурации Wrangler (см. конфигурация Wrangler для миграций).
2. Повторно разверните Worker с помощью npx wrangler deploy.

Вам необходимо запустить процесс миграции в следующих случаях:

• Создайте новый Durable Object class.
• Переименование класса Durable Object.
• Удалите класс Durable Object.
• Перенос существующего класса Durable Objects.

Наиболее распространённой является миграция нового класса, которая сообщает среде выполнения, что загружается новый класс Durable Object. Она же требуется при создании вашего первого класса Durable Object.

Чтобы применить миграцию создания:

{
	// Creating a new Durable Object class
	"durable_objects": {
		"bindings": [
			{
				"name": "DURABLE_OBJECT_A",
				"class_name": "DurableObjectAClass"
			}
		]
	},
	// Add the lines below for a Create migration.
	"migrations": [
		{
			"tag": "v1",
			"new_sqlite_classes": [
				"DurableObjectAClass"
			]
		}
	]
}

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

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

Используйте new_classes в миграции в файле Wrangler вашего Worker, чтобы создать класс Durable Object с бэкендом хранилища ключ-значение:

{
	"migrations": [
		{
			"tag": "v1", // Should be unique for each entry
			"new_classes": [
				// Array of new classes
				"MyDurableObject",
			],
		},
	],
}

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

Выполнение миграции Delete приведёт к удалению всех Durable Objects, связанных с удаляемым классом, включая все их сохранённые данные.

• Не выполняйте миграцию Delete для класса, предварительно не убедившись, что вы больше не используете Durable Objects в этом Worker, то есть сначала удалите привязку из Worker.
• Перед удалением скопируйте все важные данные в другое место.
• Запускать миграцию Delete для класса, который был переименован или перенесён, не обязательно.

Чтобы применить миграцию удаления:

{
	// Remove the binding for the DeprecatedObjectClass DO
	// {"durable_objects": {"bindings": [
	//   {
	//     "name": "DEPRECATED_OBJECT",
	//     "class_name": "DeprecatedObjectClass"
	//   }
	// ]}}
	"migrations": [
		{
			"tag": "v3", // Should be unique for each entry
			"deleted_classes": [ // Array of deleted classes
				"DeprecatedObjectClass"
			]
		}
	]
}

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

Миграции переименования используются для переноса сохранённых Durable Objects между двумя классами Durable Object в одном файле кода Worker.

Чтобы применить миграцию переименования:

{
	"durable_objects": {
		"bindings": [
			{
				"name": "MY_DURABLE_OBJECT",
				// Update the binding to the new class name.
				"class_name": "UpdatedName"
			}
		]
	},
	// Renaming classes
	"migrations": [
		{
			"tag": "v3",
			"renamed_classes": [ // Array of rename directives
				{
					"from": "OldName",
					"to": "UpdatedName"
				}
			]
		}
	]
}

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

[[migrations]]
tag = "v3"

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

Миграции переноса используются для переноса сохранённых Durable Objects между двумя классами Durable Object, находящимися в разных файлах кода Worker.

Если вы хотите перенести сохранённые Durable Objects между двумя классами Durable Object в одном файле кода Worker, используйте Миграции переименования взамен.

Чтобы применить миграцию переноса:

{
	// destination worker
	"durable_objects": {
		"bindings": [
			{
				"name": "MY_DURABLE_OBJECT",
				"class_name": "TransferredClass"
			}
		]
	},
	// Transferring class
	"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"

• Миграции выполняются через [[migrations]] ключ configurations в вашем wrangler.toml файл или migrations ключ в вашем wrangler.jsonc файл.

• Для миграций требуется тег миграции, который задаётся в tag свойство в каждой записи миграции.

• Теги миграций работают как уникальные имена и используются для определения того, какие миграции уже были применены. После того как для кода Worker задан тег миграции, все последующие развёртывания этого кода должны включать тег миграции.

• Список миграций представляет собой упорядоченный массив таблиц, который указывается как ключ в файле конфигурации Wrangler.

• Вы можете определить миграцию для каждого окружения, а также на верхнем уровне.

  • Миграция верхнего уровня указывается на верхнем уровне migrations ключ в файле конфигурации Wrangler.
  • Миграция на уровне окружения задаётся с помощью migrations ключ внутри env ключ файла конфигурации Wrangler ([env.<environment_name>.migrations]).
    • Пример файла Wrangler:
    wrangler.jsonc

    {
      // top-level default migrations
      "migrations": [
        { "tag": "v1", "new_sqlite_classes": ["MyDurableObject"] },
      ],
      "env": {
        "staging": {
          // migration override for staging
          "migrations": [
            { "tag": "v1-staging", "new_sqlite_classes": ["MyDurableObject"] },
          ],
        },
      },
    }

  • Если миграция указана только на верхнем уровне, а не на уровне окружения, окружение унаследует миграцию верхнего уровня.
  • Миграции на уровне окружения имеют приоритет над миграциями верхнего уровня.

• Все миграции применяются при развёртывании. Каждая миграция может быть применена только один раз на окружение.

• Каждая миграция в списке может содержать несколько директив, а по мере усложнения проекта можно указывать несколько миграций.

Нельзя включить хранилище на основе SQLite для уже развёрнутого класса Durable Object, поэтому указание new_sqlite_classes в последующих миграциях завершится ошибкой. Автоматическая миграция развёрнутых классов с бэкенда хранилища ключ-значение на бэкенд хранилища SQLite станет доступна в будущем.