HOWTO: Обновление версии PostgreSQL: различия между версиями

Текущая версия от 06:07, 21 августа 2025

В данном разделе описана процедура обновления PostgreSQL между основными версиями (например, с версии 11 на версию 17).

Обновление внутри версии (например, с версии 17.1 на версию 17.2) происходит автоматически и не требует дополнительных действий.

Рекомендуем ознакомиться с официальными инструкциями по обновлению на сайте postgresql.org.

В дистрибутиве Debian и основанных на нем существует пакет postgresql-common, устанавливаемый автоматически при установке пакета PostgreSQL. В состав postgresql-common входят инструменты, упрощающие работу с кластерами баз данных PostgreSQL. В том числе и обновление кластеров БД.

Кластером баз данных (Database cluster) в PostgreSQL называется экземпляр сервера вместе со всеми обслуживаемыми БД, а не распределенную систему, как может показаться.

В следующем примере будет показано обновление кластера БД с версии 11 на версию 17 используя инструменты из пакета postgresql-common.

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

Остановить USERSIDE.
Обновить текущую версию пакета postgresql в пределах основной версии (например, с 11.5 до 11.22).
Обновить версию пакета postgis до самой последней версии (например, с 2.5 до 3.3.4).
Обновить расширение PostGIS во всех базах данных кластера.
Установить новую версию пакета postgresql не удаляя старой (например 17.1)
Сделать запасную резервную копию базы данных и настроек
Удалить кластер БД, созданный автоматически сценарием при установке новой версии
Выполнить обновление кластера БД старой версии до кластера новой версии
Проверить работу USERSIDE
Удалить кластер БД старой версии, устаревшие пакеты и запасные резервные копии

Выделите время на эту операцию. Она может занять довольно продролжительное время в зависимости от размера базы данных и производительности сервера. Также обязательно убедитесь в наличии свободного места, которое понадобится для обновления кластера (как минимум столько же, сколько занимает текущий кластер, но лучше больше).

Посмотреть видеоинструкцию на asciinema.

Пошаговая инструкция

SQL-запросы с оператором SELECT, приведенные далее, необходимы для определения текущих установленных версий в качестве справочной информации.

Остановить USERSIDE

sudo supervisorctl stop all
sudo systemctl stop php8.3-fpm

Версия php указана для примера. Используйте ту, что испльзуется у вас.

Закомментируйте запуск всех модулей и userside в crontab. Если используете сателлиты, остановите службы и на них.

Обновить текущую версии postgresql в пределах основной версии

Проверить текущие версии системных пакетов PostgreSQL и PostGIS. Обновить текущие установленные версии PostgreSQL и PostGIS до посладних версий в пределах их основных версий, а также, если текущая версия PostGIS ниже 3, установить дополнительно пакет PostGIS 3 для вашей версии PostgreSQL. Если у вас уже сейчас установлен PostGIS 3, то вам нужно только лишь его обновить до последней версии.

# получить версию postgresql и версию расширения postgis для базы данных userside
sudo -u postgres psql -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"

# обновить такущие версии пакетов
sudo apt update
sudo apt install --only-upgrade -y postgresql-11 postgresql-11-postgis-2.5
# только если текущая версия postgis ниже 3, дополнительно установить postgis-3 для текущей версии postgres
sudo apt install -y postgresql-11-postgis-3

Вместо 11 и 2.5, конечно же, укажите те версии, которе фактически установлены у вас.

Обновить расширение postgis до самой последней версии

После обновления пакета postgis необходимо соответственно обновить и само расширение postgis в базах данных, где это расширение присутствует. У вас может быть, например, копия базы данных userside для тестов - не забудьте про нее.

sudo -u postgres psql -d userside -A -t -c "ALTER EXTENSION postgis UPDATE"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"

Вторая команда отобразит текущую версию расширения PostGIS после обновления.

Обновление с PostGIS 2.5 на PostGIS 3.x

Если предыдущий запрос SELECT PostGIS_full_version() отображает информацию подобно такой:

POSTGIS="3.3.4 3.3.4" [EXTENSION] . . .
. . .
[UNPACKAGED!] (raster procs from "2.5.5 r0" need upgrade)

То следующая информация для вас. Иначе пропустите этот раздел.

Между версиям PosGIS 2 и 3 существует некоторая разница, которая требует дополнительных действий при обновлении.

# дважды один и тот же запрос
sudo -u postgres psql -d userside -A -t -c "SELECT postgis_extensions_upgrade()"
sudo -u postgres psql -d userside -A -t -c "SELECT postgis_extensions_upgrade()"
# удалить расширение raster, которое раньше было частью расширения postgis
sudo -u postgres psql -d userside -A -t -c "DROP EXTENSION postgis_raster"

Установить новые версии пакетов

Также удалить старый пакет postgis версии 2, если он был установлен.

sudo apt install -y postgresql-17 postgresql-17-postgis-3
sudo apt purge -y postgresql-11-postgis-2.5

Сделать запасную резервную копию базы данных и конфигурации

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

sudo -u postgres pg_dump --no-acl -Fp -Z 5 userside --file=/backup/userside_emergency.sql.gz
sudo -u postgres pg_dump --no-acl -Fc userside --file=/backup/userside_emergency.dump
sudo tar czf /backup/postgres_config_emergency.tgz -C /etc/postgresql/11/main .

Каталог /backup должен существовать и должен быть доступен для записи всем пользователям.

Удалить автоматически созданный кластер БД

При помощи утилиты pg_lsclusters из postgresql-common посмотрите, как выглядят ваши кластеры БД:

sudo pg_lsclusters

Вывод команды будет примерно следующим:

Ver Cluster Port Status Owner    Data directory              Log file
11  main    5432 online postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
17  main    5433 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17.log

Кластер 17/main был создан автоматически сценарием установки postgresql и использует новый порт 5433. Его нужно остановить и удалить — он не нужен, т.к. будет выполняться процедура миграции кластера, которая создаст новый кластер автоматически.

sudo pg_dropcluster 17 main --stop

Повторное выполнение команды pg_lsclusters должно показать, что у вас остался один кластер 11/main.

Выполнить обновление кластера БД старой версии до кластера новой версии

Остановите службу postgresql

sudo systemctl stop postgresql

Запустите процесс обновления кластера БД 11/main используя утилиту pg_upgradecluster из пакета postgresql-common. Это действие может занять много времени и дискового пространства.

sudo pg_upgradecluster 11 main

После завершения операции обновления вы увидите новое состояние кластеров (старая версия должна находиться в режиме down и порт 5432 теперь назначен новому кластеру 17/main):

Ver Cluster Port Status Owner    Data directory              Log file
11  main    5433 down   postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
17  main    5432 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17.log

Запустите службу postgres

sudo systemctl start postgresql

Проверить работу USERSIDE

Сначала выполните команды, отображающие версии, чтобы убедиться что база данных теперь работает на кластере БД новой версии:

sudo -u postgres psql -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"

Вы должны увидеть 17ю версию postgresql и 3.x.x версию postgis.

Теперь запустите службу FPM и зайдите в USERSIDE через браузер.

sudo systemctl start php8.3-fpm

Так как другие службы остановлены, вы, вероятно, увидите ошибки связанные с ними, но при этом интерфейс USERSIDE должен открыться без ошибок подключения к базе данных. Если все успешно, то раскомментируйте закомментированные ранее строки в crontab и запустите внешние службы, находящиеся под управлением supervisor, в том числе на сателлите:

sudo supervisorctl start all
sudo supervisorctl status

Очистка после успешного обновления

Если USERSIDE работает корректно, ошибок взаимодействия с БД нет, то можно удалить старый кластер и пакеты. Вы также, по желанию, можете удалить аварийные резервные копии или подождать несколько дней, чтобы точно убедиться, что они не пригодятся.

sudo pg_dropcluster 11 main --stop
sudo apt purge -y postgresql-11 postgresql-11-postgis-3
sudo apt autoremove -y
sudo rm /backup/userside_emergency* /backup/postgres_config_emergency.tgz
sudo rm -rf /var/lib/postgresql/11/main

@@ Строка 1: / Строка 1: @@
 [[HOWTO:_PostgreSQL_version_upgrade|en]] | [[HOWTO:_Обновление_версии_PostgreSQL|ru]]
-В данном разделе описана процедура обновления PostgreSQL ''между основными версиями'' (например, с версии 11 на версию 16).
+В данном разделе описана процедура обновления PostgreSQL ''между основными версиями'' (например, с версии 11 на версию 17).
-Обновление внутри версии (например, с версии 16.1 на версию 16.2) ''происходит автоматически и не требует дополнительных действий''.
+Обновление внутри версии (например, с версии 17.1 на версию 17.2) ''происходит автоматически и не требует дополнительных действий''.
-'''Рекомендуем ознакомиться с официальными инструкциями по обновлению''' на сайте [https://www.postgresql.org/docs/16/upgrading.html postgresql.org].
+'''Рекомендуем ознакомиться с официальными инструкциями по обновлению''' на сайте [https://www.postgresql.org/docs/current/upgrading.html postgresql.org].
 В дистрибутиве Debian и основанных на нем существует пакет [https://packages.debian.org/sid/postgresql-common postgresql-common], устанавливаемый автоматически при установке пакета PostgreSQL. В состав postgresql-common входят инструменты, упрощающие работу с кластерами баз данных PostgreSQL. В том числе и обновление кластеров БД.
-Кластером баз данных ([https://www.postgresql.org/docs/16/glossary.html Database cluster]) в PostgreSQL называется экземпляр сервера вместе со всеми обслуживаемыми БД, а не распределенную систему, как может показаться.
+Кластером баз данных ([https://www.postgresql.org/docs/current/glossary.html Database cluster]) в PostgreSQL называется экземпляр сервера вместе со всеми обслуживаемыми БД, а не распределенную систему, как может показаться.
-В следующем примере будет показано обновление кластера БД с версии 11 на версию 16 используя инструменты из пакета '''postgresql-common'''.
+В следующем примере будет показано обновление кластера БД с версии 11 на версию 17 используя инструменты из пакета '''postgresql-common'''.
 == Порядок обновления ==
 # Остановить USERSIDE.
-# Обновить текущую версии postgresql в пределах основной версии (например, с 11.5 до 11.22).
+# Обновить текущую версию пакета postgresql в пределах основной версии (например, с 11.5 до 11.22).
-# Обновить расширение postgis до самой последней версии (например, с 2.5 до 3.1). Также обязательно обновить расширение и в самой базе данных.
+# Обновить версию пакета postgis до самой последней версии (например, с 2.5 до 3.3.4).
-# Установить новую версию postgresql не удаляя старой (например 16.1)
+# Обновить расширение PostGIS во всех базах данных кластера.
+# Установить новую версию пакета postgresql не удаляя старой (например 17.1)
 # Сделать запасную резервную копию базы данных и настроек
 # Удалить кластер БД, созданный автоматически сценарием при установке новой версии
@@ Строка 25: / Строка 26: @@
 Выделите время на эту операцию. Она может занять довольно продролжительное время в зависимости от размера базы данных и производительности сервера. Также обязательно убедитесь в наличии свободного места, которое понадобится для обновления кластера (как минимум столько же, сколько занимает текущий кластер, но лучше больше).
+[https://asciinema.org/a/do2AE0z30mg5JLIuI9zhGTPoR Посмотреть видеоинструкцию на asciinema].
 == Пошаговая инструкция ==
+SQL-запросы с оператором <code>SELECT</code>, приведенные далее, необходимы для определения текущих установленных версий в качестве справочной информации.
 === Остановить USERSIDE ===
 <pre>
 sudo supervisorctl stop all
-sudo systemctl stop php8.1-fpm
+sudo systemctl stop php8.3-fpm
 </pre>
 Версия php указана для примера. Используйте ту, что испльзуется у вас.
-Закомментируйте запуск всех модулей и userside в crontab.
+Закомментируйте запуск всех модулей и userside в crontab. Если используете [[Usm_poller_(as_satellite)|сателлиты]], остановите службы и на них.
 === Обновить текущую версии postgresql в пределах основной версии ===
-Проверить текущие версии. Обновить текущие пакеты PostgreSQL и PostGIS:
+Проверить текущие версии системных пакетов PostgreSQL и PostGIS. Обновить текущие установленные версии PostgreSQL и PostGIS до посладних версий в пределах их основных версий, а также, если текущая версия PostGIS ниже 3, установить дополнительно пакет PostGIS 3 для вашей версии PostgreSQL. Если у вас уже сейчас установлен PostGIS 3, то вам нужно только лишь его обновить до последней версии.
 <pre>
-sudo -u postgres psql -d userside -A -t -c "SELECT VERSION()"
+# получить версию postgresql и версию расширения postgis для базы данных userside
+sudo -u postgres psql -A -t -c "SELECT VERSION()"
 sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
+# обновить такущие версии пакетов
 sudo apt update
 sudo apt install --only-upgrade -y postgresql-11 postgresql-11-postgis-2.5
+# только если текущая версия postgis ниже 3, дополнительно установить postgis-3 для текущей версии postgres
+sudo apt install -y postgresql-11-postgis-3
 </pre>
-Вместо 11 и 2.5 укажите те версии, которе фактически установлены у вас.
+Вместо 11 и 2.5, конечно же, укажите те версии, которе фактически установлены у вас.
 === Обновить расширение postgis до самой последней версии ===
-Обязательно также обновить расширение в базе данных!
+После обновления пакета postgis необходимо соответственно обновить и само расширение postgis в базах данных, где это расширение присутствует. У вас может быть, например, копия базы данных userside для тестов - не забудьте про нее.
 <pre>
-sudo apt install -y postgresql-11-postgis-3
 sudo -u postgres psql -d userside -A -t -c "ALTER EXTENSION postgis UPDATE"
 sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
+</pre>
+Вторая команда отобразит текущую версию расширения PostGIS после обновления.
+=== Обновление с PostGIS 2.5 на PostGIS 3.x ===
+Если предыдущий запрос <code>SELECT PostGIS_full_version()</code> отображает информацию подобно такой:
+<pre>
+POSTGIS="3.3.4 3.3.4" [EXTENSION] . . .
+. . .
+[UNPACKAGED!] (raster procs from "2.5.5 r0" need upgrade)
+</pre>
+То следующая информация для вас. Иначе пропустите этот раздел.
+Между версиям PosGIS 2 и 3 существует некоторая разница, которая требует дополнительных действий при обновлении.
+<pre>
+# дважды один и тот же запрос
+sudo -u postgres psql -d userside -A -t -c "SELECT postgis_extensions_upgrade()"
+sudo -u postgres psql -d userside -A -t -c "SELECT postgis_extensions_upgrade()"
+# удалить расширение raster, которое раньше было частью расширения postgis
+sudo -u postgres psql -d userside -A -t -c "DROP EXTENSION postgis_raster"
 </pre>
-=== Установить новую версию postgresql не удаляя старой ===
+=== Установить новые версии пакетов ===
+Также удалить старый пакет postgis версии 2, если он был установлен.
 <pre>
-sudo apt install -y postgresql-16 postgresql-16-postgis-3
+sudo apt install -y postgresql-17 postgresql-17-postgis-3
+sudo apt purge -y postgresql-11-postgis-2.5
 </pre>
-=== Сделать запасную резервную копию базы данных и настроек ===
+=== Сделать запасную резервную копию базы данных и конфигурации ===
-Число 11 в имени файлов — это номер версии PostgreSQL, к которой относится эта резервная копия.
+Инструмент миграции кластеров делает это абсолютно безопасно, однако дополнительная осторожность лишней не будет. Сделайте запасные временные резервные копии нужных баз данных и конфигурации, которые в конце обновления можно будет смело удалить.
 <pre>
-sudo -u postgres pg_dump --no-acl -Fp -Z 5 userside --file=userside_emergency_11.sql.gz
+sudo -u postgres pg_dump --no-acl -Fp -Z 5 userside --file=/backup/userside_emergency.sql.gz
-sudo -u postgres pg_dump --no-acl -Fc userside --file=/userside_emergency_11.dump
+sudo -u postgres pg_dump --no-acl -Fc userside --file=/backup/userside_emergency.dump
-sudo tar xzf postgres_config_emergency_11.tgz /etc/postgresql/11/main
+sudo tar czf /backup/postgres_config_emergency.tgz -C /etc/postgresql/11/main .
 </pre>
+Каталог /backup должен существовать и должен быть доступен для записи всем пользователям.
-=== Удалить кластер БД, созданный автоматически сценарием при установке новой версии ===
+=== Удалить автоматически созданный кластер БД ===
 При помощи утилиты <code>pg_lsclusters</code> из postgresql-common посмотрите, как выглядят ваши кластеры БД:
 <pre>
@@ Строка 79: / Строка 107: @@
 Ver Cluster Port Status Owner    Data directory              Log file
   main    5432 online postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
-main    5433 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16.log
+main    5433 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17.log
 </pre>
-Кластер 16/main был создан автоматически сценарием установки postgresql. Его нужно остановить и удалить.
+Кластер 17/main был создан автоматически сценарием установки postgresql и использует новый порт 5433. Его нужно остановить и удалить — он не нужен, т.к. будет выполняться процедура миграции кластера, которая создаст новый кластер автоматически.
 <pre>
-sudo pg_dropcluster 16 main --stop
+sudo pg_dropcluster 17 main --stop
 </pre>
 Повторное выполнение команды <code>pg_lsclusters</code> должно показать, что у вас остался один кластер '''11/main'''.
@@ Строка 94: / Строка 122: @@
 Запустите процесс обновления кластера БД '''11/main''' используя утилиту <code>pg_upgradecluster</code> из пакета postgresql-common. Это действие может занять много времени и дискового пространства.
 <pre>
-sudo pg_upgradecluster -m upgrade 11 main
+sudo pg_upgradecluster 11 main
 </pre>
-После завершения процедуры запустите службу postgres
+После завершения операции обновления вы увидите новое состояние кластеров (старая версия должна находиться в режиме '''down''' и порт 5432 теперь назначен новому кластеру '''17/main'''):
 <pre>
-sudo systemctl start postgresql
+Ver Cluster Port Status Owner    Data directory              Log file
+  main    5433 down   postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
+  main    5432 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17.log
 </pre>
-Проверьте, как выглядят ваши кластеры БД
+Запустите службу postgres
 <pre>
-sudo pg_lsclusters
+sudo systemctl start postgresql
-</pre>
-Старая версия должна находиться в режиме '''down'''. Вывод команды будет примерно следующим:
-<pre>
-Ver Cluster Port Status Owner    Data directory              Log file
-  main    5433 down   postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
-  main    5432 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16.log
 </pre>
@@ Строка 114: / Строка 138: @@
 Сначала выполните команды, отображающие версии, чтобы убедиться что база данных теперь работает на кластере БД новой версии:
 <pre>
-sudo -u postgres psql -d userside -A -t -c "SELECT VERSION()"
+sudo -u postgres psql -A -t -c "SELECT VERSION()"
 sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
 </pre>
-Вы должны увидеть 16ю версию postgresql и 3.1 версию postgis. Может быть к тому времени, как вы будете читать эти строки, версия postgis будет более новой.
+Вы должны увидеть 17ю версию postgresql и 3.x.x версию postgis.
-Теперь запустите службу FPM и попробуйте зайти в USERSIDE через браузер.
+Теперь запустите службу FPM и зайдите в USERSIDE через браузер.
 <pre>
-sudo systemctl start php8.1-fpm
+sudo systemctl start php8.3-fpm
 </pre>
-Так как другие слудбы остановлены, вы, вероятно, увидите ошибки связанные с ними, но при этом интерфейс USERSIDE должен открыться без ошибок подключения к базе данных.
+Так как другие службы остановлены, вы, вероятно, увидите ошибки связанные с ними, но при этом интерфейс USERSIDE должен открыться без ошибок подключения к базе данных.
-Если все успешно, то раскомментируйте закомментированные ранее строки в crontab и запустите внешние службы, находящиеся под управлением supervisor:
+Если все успешно, то раскомментируйте закомментированные ранее строки в crontab и запустите внешние службы, находящиеся под управлением supervisor, в том числе на сателлите:
 <pre>
 sudo supervisorctl start all
@@ Строка 130: / Строка 154: @@
 </pre>
-=== Удалить кластер БД старой версии, устаревшие пакеты и запасные резервные копии ===
+=== Очистка после успешного обновления ===
 Если USERSIDE работает корректно, ошибок взаимодействия с БД нет, то можно удалить старый кластер и пакеты. Вы также, по желанию, можете удалить аварийные резервные копии или подождать несколько дней, чтобы точно убедиться, что они не пригодятся.
 <pre>
 sudo pg_dropcluster 11 main --stop
-sudo apt purge -y postgresql-11 postgresql-11-postgis-2.5 postgresql-11-postgis-3
+sudo apt purge -y postgresql-11 postgresql-11-postgis-3
 sudo apt autoremove -y
-sudo rm userside_emergency_11* postgres_config_emergency_11.tgz
+sudo rm /backup/userside_emergency* /backup/postgres_config_emergency.tgz
+sudo rm -rf /var/lib/postgresql/11/main
 </pre>
-Видеоинструкция (устаревшая версия): https://youtu.be/c9ULVSz8yQM