GitHub

Обновление существующих баз ParadeDB ​

Продакшн- и dev-конфигурации Compose в репозитории используют paradedb/paradedb:v0.25.11-pg17. Эта статья описывает обновление 0.22.x → 0.25.11 с сохранением основной версии PostgreSQL 17; она не подходит для перехода PostgreSQL на другую основную версию и не означает, что другие старые версии в Helm можно обновлять так же напрямую.

Эта линия версий относительно v0.22.6-pg17 приносит PostgreSQL 17.9 → 17.11, pgvector 0.8.1 → 0.8.4 (исправляет переполнение буфера параллельной сборки HNSW и повреждение индекса при HNSW vacuum) и восстановление после сбоев на основе WAL в pg_search (начиная с 0.24.0, см. paradedb#4901).

WARNING

После замены образа каталог расширений обязательно нужно обновить до версии, соответствующей образу. Пока каталог остаётся на старой версии, некоторые SQL-функции расширений (например, paradedb.version_info()) вызывают сегментацию из-за несовпадения сигнатуры с новыми бинарными файлами, что роняет весь экземпляр PostgreSQL и приводит его в состояние восстановления. Также не выполняйте на новом образе ALTER EXTENSION pg_search UPDATE TO '0.22.6' — это вызовет то же самое несовпадение.

Порядок обновления ​

Все команды выполняются в корне репозитория. Для команд базы данных в среде разработки используйте docker compose -f docker-compose.dev.yml, dev-бэкенд на хосте останавливается вручную; в dev-compose сервиса app нет. Сохраняйте исходный том данных, не выполняйте down -v, не удаляйте тома и не заменяйте образ на PG18.

  1. Остановите app и других, кто пишет в базу данных; если включён Langfuse, остановите также его web/worker, а локально запущенный dev-бэкенд тоже нужно остановить.
bash
  # Стандартное развёртывание; в среде разработки остановите процесс бэкенда на хосте
  docker compose stop app
  # Выполняйте, только если включён Langfuse
  docker compose stop langfuse-web langfuse-worker
  1. Сделайте резервную копию всех баз данных и ролей, включая базу Langfuse, и убедитесь, что её можно восстановить. Резервная копия хранится вне тома данных базы данных.
bash
  umask 077
  docker compose exec -T postgres sh -c 'pg_dumpall -U "$POSTGRES_USER"' > paradedb-before-upgrade.sql

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

  1. Используя обновлённый Compose, замените только контейнер базы данных:
bash
  docker compose pull postgres
  docker compose up -d --no-deps --wait postgres
  1. Завершите SQL-обновление расширения. Простая замена образа не обновит версию pg_extension в существующей базе данных. Новый образ поставляет полную цепочку скриптов обновления с 0.22.x, поэтому любую 0.22.x можно обновить одной ступенью до версии по умолчанию в образе:
bash
  docker compose exec -T postgres sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -v ON_ERROR_STOP=1' <<'SQL'
  ALTER EXTENSION pg_search UPDATE;
  ALTER EXTENSION vector UPDATE;
  SELECT extname, extversion FROM pg_extension WHERE extname IN ('pg_search', 'vector');
  SELECT * FROM paradedb.version_info();
  SQL

Выполните то же самое в других базах данных, где уже установлены pg_search или vector, включая postgres, шаблонные базы или базу Langfuse. Не устанавливайте расширение в базах, которым оно изначально не нужно, только ради обновления. И каталог, и paradedb.version_info() должны сообщать 0.25.11, а vector — 0.8.4.

  1. Верните ранее работавшие сервисы записи, убедитесь в состоянии миграций базы данных и выполните характерные проверки поиска по ключевым словам и векторам. Существующие индексы BM25 и HNSW остаются пригодными для чтения и записи в новой версии — специально перестраивать все индексы или повторно импортировать документы не требуется; при аномалиях выполните REINDEX. Храните резервную копию до завершения проверки.

Область действия автоматической миграции ​

Миграции, выполняющиеся при запуске aihelpme.ru, обновляют расширения только внутри базы данных aihelpme.ru, соблюдают app.skip_embedding, не устанавливают отсутствующие расширения, а также не понижают версии и не обрабатывают другие линии версий:

  • 000115: если установленный pg_search имеет версию 0.22.0–0.25.10, а сервер предоставляет 0.25.11, обновляет до 0.25.11; если установленный vector имеет версию 0.8.0–0.8.3, а сервер предоставляет 0.8.4, обновляет до 0.8.4.
  • 000099: историческая миграция, обновляет 0.22.2–0.22.5 до 0.22.6 только когда сервер предоставляет пакет расширения 0.22.6 (то есть по-прежнему используется образ v0.22.6-pg17); на новых образах она пропускается и передаёт управление 000115.

Если эти миграции уже выполнились до замены образа базы данных, после установки нового образа они автоматически не запустятся снова, и нужно вручную выполнить приведённый выше SQL. В старых приложениях без соответствующих миграций также нужен ручной апгрейд. Расширения в других базах данных не могут управляться миграциями aihelpme.ru.

Откат и проверка воспроизведения ​

Для отката нужно восстановить резервную копию/снимок, сделанные до обновления, в отдельный том данных и использовать вместе со старым образом. Простое возвращение тега образа к старой версии не отменяет изменения SQL расширения; начиная с pg_search 0.24 в WAL записываются записи с собственным resource manager'ом, которые старый образ не умеет проигрывать. Down-файлы миграций тоже не пытаются понизить версию расширения.

В репозитории есть скрипт изолированной проверки: по умолчанию он проверяет обновление 0.22.2 → 0.25.11, а также можно проверить историческое патч-обновление с помощью --to 0.22.6:

bash
docker pull paradedb/paradedb:v0.22.2-pg17
docker pull paradedb/paradedb:v0.25.11-pg17
python3 scripts/test_paradedb_upgrade.py

Скрипт использует временные контейнеры и тома, не публикует порты; он проверяет обновление одного и того же тома данных, содержимое таблиц, поиск по ключевым словам/векторам, идемпотентность миграций и результат после перезапуска, а также выводит резервную копию и журналы. Этот тест проверяет фиксированные тестовые данные; при развёртывании всё равно нужно проверять свои данные и нагрузку поиска.

Версия v0.8.3 · MIT License

© aihelpme.ru