# Обновление кластера {: #update_cluster }

Обновление кластера поддерживается в двух режимах:

- с остановкой всех инстансов кластера (более надёжный и рекомендованный
  способ)
- без остановки кластера, т.е. с поэтапным переводом инстансов на новую
  версию продукта (более рискованный способ, но позволяющий избежать
  простоя)

В обоих случаях после обновления версии Picodata в кластере могут
различаться максимум на 1 минорное значение. Например, в кластере могут
одновременно работать инстансы с Picodata 25.4 и 25.5.

См. также:

- [Политика версионирования](../overview/versioning.md)

!!! warning "Важно"
    Перед обновлением кластера сделайте его [резервную
    копию](backup_and_restore.md) — она пригодится для отката кластера к
    первоначальному состоянию в случае проблем обновления.

## Обновление с остановкой кластера {: #upgrade_stopped_cluster }

Обновление кластера этим способом более предпочтительно, так как
происходит быстрее и предсказуемее. Процедура сводится к:

- организации запланированного окна обслуживания, в течение которого кластер будет недоступен для клиентов
- отключению всех плагинов в кластере (при их наличии)
- остановке всех инстансов кластера
- установке новой версии ПО (см. [ниже](#update_software))
- поэтапному запуску инстансов уже на новой версии ПО
- включению плагинов (при их наличии)

### Отключение плагинов {: #disable_plugins }

Если в кластере включены плагины, то перед обновлением их необходимо отключить:

- определите состав плагинов и их версии (`SELECT * FROM _pico_plugin;`)
- для каждого плагина выполните команду вида `ALTER PLUGIN plugin_name
  0.0.1 DISABLE;`, указав корректные имя и версию

### Остановка инстансов {: #stop_instances }

См. раздел [Завершение работы и обработка сигналов](../tutorial/run.md#secure_stop).

### Обновление ПО {: #update_software }

При использовании Picodata в промышленной среде следует обновить
[поставляемую сборку продукта]. Если Picodata была установлена из
готового пакета для определенной ОС, то следует обновить этот пакет.
При наличии подключенного репозитория Picodata обновленный пакет будет
доставлен в рамках общего обновления системы (`sudo apt-get upgrade`
для систем c Apt и `sudo dnf update` для систем с Yum/DNF). Если пакет
был установлен вручную, без подключения репозитория Picodata, то
следует воспользоваться системными средствами для управления
индивидуальными пакетами (`dpkg`/`rpm`).

??? example "Обновление Picodata из исходного кода"
    Если Picodata была собрана из исходного кода, то необходимо обновить
    данные локальной копии Git-репозитория (`git pull && git submodule
    update --init --recursive`), очистить данные предыдущей сборки (`cargo
    clean`) и [собрать](../tutorial/install.md#building) новую версию бинарного файла `picodata`.
    Важно [удостовериться](../tutorial/install.md#post_install_check), что после этого будет
    запускаться именно новая версия `picodata`

[поставляемую сборку продукта]: https://picodata.io/download

### Запуск после обновления {: #start_after_upgrade }

После обновления следует перезапустить инстансы Picodata с прежними
параметрами. Рекомендуется в первую очередь запустить [голосующие]
инстансы, затем — остальные.

### Обновление и включение плагинов {: #plugin_upgrade }

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

Ниже приведён порядок действий для обновления
отдельного плагина в кластере. Если плагинов несколько, то указанные
шаги следует выполнить для каждого плагина.

1. [Отключите плагин](#disable_plugins) и [выключите
инстанс](#stop_instances). Поместите файлы плагина в директорию,
заданную для параметра [`instance.share_dir`]. Если при пересборке плагина
его версия не менялась, то замените файлы старой версии. Повторите эти
действия для всех инстансов кластера.

1. [Запустите](#start_after_upgrade) кластер с новой версией Picodata.

1. Выполните действия по включению плагина. Пример необходимых команд:
```sql
CREATE PLUGIN plugin_name 0.2.0;
ALTER PLUGIN plugin_name 0.2.0 ADD SERVICE plugin_service_name TO TIER tier_name;
ALTER PLUGIN plugin_name MIGRATE TO 0.2.0;
ALTER PLUGIN plugin_name 0.2.0 ENABLE;
```

1. Если у плагина есть настраиваемые параметры, которые необходимо
задать, используйте команду `picodata plugin configure`. Пример:
```shell
picodata plugin configure --peer andy@127.0.0.1:3001 --service-password-file pass.txt plugin_name 0.2 plugin_dir/plugin_config.yaml
```

См. также:

- [ALTER PLUGIN](../reference/sql/alter_plugin.md)
- [Управление плагинами](../dev/plugin_mgmt.md)

[`instance.share_dir`]: ../reference/config.md#instance_share_dir
[голосующие]: ../overview/description.md#raft_model

## Обновление без остановки кластера {: #upgrade_running_cluster }

Для обновления кластера без остановки достаточно установить новую версию
Picodata на каждый узел и последовательно перезапустить инстансы.

## Действия после обновления кластера {: #post_upgrade_servicing }

### Проверка гетерогенности кластера {: #check_versions }

После завершения процедуры обновления проверьте, что все инстансы
кластера перешли на новую версию и находятся в состоянии `Online`. Пример:

```sql
SELECT name, picodata_version,current_state FROM _pico_instance;
+------+------------------------+----------------+
| name | picodata_version       | current_state   |
+================================================+
| i1   | 25.5.0-1566-g7f2b88e29 | ["Online", 10] |
|------+------------------------+----------------|
| i2   | 25.5.0-1566-g7f2b88e29 | ["Online", 6]  |
|------+------------------------+----------------|
| i3   | 25.5.0-1566-g7f2b88e29 | ["Online", 7]  |
|------+------------------------+----------------|
| i4   | 25.5.0-1566-g7f2b88e29 | ["Online", 11] |
+------+------------------------+----------------+
(4 rows)
```

Эту информацию можно посмотреть и через [веб-интерфейс
Picodata](../tutorial/webui.md).

Если часть инстансов находятся в состоянии `Offline` и/или остались на
прежней версии, проверьте сетевую доступность соответствующих узлов и
попробуйте перезапустить инстансы. Если это не поможет, удалите такие
инстансы из кластера вручную (см. [ниже](#forced_expel)).

### Проверка применения нового набора системных таблиц {: #check_system_tables_upgrade }

Новая функциональность, поставляемая с актуальной версией Picodata,
может отражаться на составе [системных таблиц] (глобальные таблицы с
префиксом `_pico`, хранящие настройки СУБД). При обновлении кластера,
изменения полей в системных таблицах вступят в силу после перехода всех
инстансов кластера на новую версию Picodata. Для отслеживания этого
используйте следующую команду, которая действует глобально в рамках
кластера:

```sql
SELECT value FROM _pico_property WHERE key = 'system_catalog_version';
```
Значение 'system_catalog_version' обязательно меняется при обновлении на
новую мажорную версию Picodata. Сравнивая это значение до и после
обновления, вы можете определить, что кластер успешно обновился.

[системных таблиц]: ../architecture/system_tables.md

### Удаление инстансов из кластера вручную {: #forced_expel }

При обновлении кластера без остановки возможна ситуация, когда в
raft-группе продолжают числиться инстансы, которых фактически уже нет
(например, из-за изменения UUID). Для удаления таких инстансов из
кластера вручную понадобится команда [expel] и UUID этих инстансов.
Значения UUID можно получить следующим образом:
```shell
picodata status --peer admin@<binary-адрес одного из новых инстансов>
```
Пример вызова `expel`:
```shell
picodata expel --peer admin@<binary-адрес одного из новых инстансов> <UUID инстанса, который нужно удалить> --force
```
Это команда потребует пароль администратора СУБД. Если пароль не был установлен, то подключитесь к кластеру командой `picodata admin` и установите его:
```sql
ALTER USER admin WITH PASSWORD '<my secret pass>'
```

[expel]: ../tutorial/node_expel.md

### Откат обновления {: #rollback_upgrade }

Если обновление прошло неуспешно, попробуйте его откатить: остановите
кластер и затем восстановите его из [резервной
копии](backup_and_restore.md).

См. также:

- [Устранение неполадок](troubleshooting.md)
