forgeplan migrate

Команда forgeplan migrate запускает отложенные миграции схемы для таблиц LanceDB в .forgeplan/lance/. Forgeplan иногда добавляет столбцы или изменяет структуру таблиц между выпусками (например, в v0.17 → v0.18 были добавлены столбцы для BM25 и русской морфологии). migrate применяет эти изменения на месте, сохраняя все артефакты, связи и доказательства, не требуя деструктивной повторной инициализации.

Когда использовать

Сразу после обновления бинарного файла Forgeplan (cargo install forgeplan, brew upgrade forgeplan или загрузки релиза).
Когда forgeplan health или любая другая команда сообщает о несоответствии версии схемы или ошибках “missing column”.
Перед возобновлением работы в рабочем пространстве, которое последний раз использовалось в старой версии.

Когда НЕ использовать

В совершенно новом рабочем пространстве, созданном текущим бинарным файлом - мигрировать нечего.
В качестве замены для перестроения поискового индекса - миграции изменяют схему, а не содержимое. Для перестроения индекса используйте forgeplan scan-import.
В качестве инструмента восстановления для поврежденных рабочих пространств - миграции предполагают, что файлы LanceDB структурно валидны. В случае повреждения восстановите из резервной копии forgeplan export.

Использование

forgeplan migrate

Опции

  -h, --help     Вывести справку
  -V, --version  Вывести версию

Примеры

Пример 1: Миграция после обновления

cargo install forgeplan        # upgrade to new version
forgeplan migrate              # apply any pending schema changes
forgeplan health               # verify workspace is clean

Стандартная последовательность после обновления. migrate является холостой операцией, если ничего не изменилось, поэтому ее безопасно запускать безусловно после каждого обновления.

Пример 2: Исправление ошибок “missing column”

forgeplan list
# Error: column 'bm25_tokens' not found
forgeplan migrate
forgeplan list
# OK

Если команда завершается с ошибкой на уровне схемы, migrate обычно является одношаговым решением.

Пример 3: Безопасный путь отката (если migrate недостаточно)

forgeplan export --output pre-migrate-backup.json
cp -r .forgeplan .forgeplan-backup-$(date +%Y%m%d)
forgeplan migrate
# if something goes wrong:
rm -rf .forgeplan
forgeplan init -y
forgeplan import pre-migrate-backup.json

Всегда делайте резервные копии перед запуском миграций в рабочих пространствах, используемых в продакшене, с важной историей артефактов.

Как это вписывается в рабочий процесс

migrate является частью пути обновления, а не ежедневного цикла работы с артефактами. Типичное обновление версии выглядит так:

forgeplan export --output pre-upgrade.json - резервная копия для безопасности
Обновление бинарного файла (cargo install / brew upgrade)
forgeplan migrate - применение отложенных изменений схемы
forgeplan health - проверка чистоты рабочего пространства
Возобновление обычной работы (forgeplan new, forgeplan validate и т.д.)

Если migrate недостаточно (например, из-за критического изменения схемы), вернитесь к циклу экспорта + повторной инициализации + импорта, описанному в forgeplan init.

Замечания по безопасности

Всегда экспортируйте данные перед миграцией рабочих пространств, используемых в продакшене. migrate разработан как неразрушающий инструмент, но новые бинарные файлы могут содержать ошибки. forgeplan export дешев и быстр; запустите его первым.
migrate идемпотентен. Запуск его дважды подряд безопасен - второй запуск обнаружит отсутствие отложенных миграций.
.forgeplan/lance/ игнорируется Git - если миграция оставит его в странном состоянии на одной машине, rm -rf .forgeplan/lance && forgeplan scan-import перестроит индекс из отслеживаемого markdown.
Версия схемы привязана к бинарному файлу. Не используйте бинарные файлы разных версий с одним и тем же рабочим пространством без запуска migrate между ними.

См. также

forgeplan export - обязательная резервная копия для безопасности перед обновлением
forgeplan import - путь отката, если миграция не удалась
forgeplan init - полное повторное инициализация в крайнем случае
forgeplan scan-import - перестроение производного индекса из markdown
forgeplan health - проверка после миграции