PostgreSQL-pg_upgrade 大版本升级14.7-15.2

标签：15.2 upgrade ok -- Checking 版本升级 pgccc new pg

1 大纲

pg_upgrade -b oldbindir -B newbindir -d oldconfigdir -D newconfigdir [option...]

2 描述

PG_UPGRADE(以前称为PG_Migrator)允许将存储在PostgreSQL数据文件中的数据升级到较新的PostgreSQL主要版本，而无需进行主要版本升级通常所需的数据转储/恢复，例如从9.5.8升级到9.6.4或从10.7升级到11.2，或从14.7升级到15.2。

次要版本升级(例如，从9.6.2升级到9.6.3或从10.1升级到10.2)不需要。

主要的PostgreSQL版本定期添加新功能，这些功能经常更改系统表的布局，但内部数据存储格式很少更改。PG_UPGRADE利用这一事实，通过创建新的系统表并简单地重用旧的用户数据文件来执行快速升级。如果将来的主要版本以使旧数据格式不可读的方式更改数据存储格式，则PG_UPGRADE将不能用于此类升级。(社区将努力避免此类情况。)。

pg_upgrade会尽最大努力确保新旧集群是二进制兼容的，例如，通过检查兼容的编译时设置，包括32/64位二进制文件。重要的是，任何外部模块也是二进制兼容的，尽管这不能通过PG_UPGRADE进行检查。

PG_UPGRADE支持从8.4.X及更高版本升级到当前主要版本的PostgreSQL，包括快照和测试版。

3 选项

pg_upgrade接受下列命令行参数：

-b bindir
--old-bindir=bindir
旧的 PostgreSQL 可执行文件目录； 环境变量PGBINOLD

-B bindir
--new-bindir=bindir
新的 PostgreSQL 可执行文件目录； 默认为pg_upgrade所在的目录； 环境变量PGBINNEW

-c
--check
只检查集簇，不更改任何数据

-d configdir
--old-datadir=configdir
旧的集簇数据目录；环境变量 PGDATAOLD

-D configdir
--new-datadir=configdir
新的集簇数据目录；环境变量 PGDATANEW

-j
--jobs=njobs
要同时使用的进程或线程数

-k
--link
使用硬链接来代替将文件拷贝到新集簇

-o options
--old-options options
直接传送给旧 postgres命令的选项，多个选项可以追加在后面

-O options
--new-options options
直接传送给新 postgres命令的选项，多个选项可以追加在后面

-p port
--old-port=port
旧的集簇端口号；环境变量 PGPORTOLD

-P port
--new-port=port
新的集簇端口号；环境变量 PGPORTNEW

-r
--retain
即使在成功完成后也保留 SQL 和日志文件

-s dir
--socketdir=dir
用于升级期间postmaster套接字的目录;默认是当前目录; 环境变量 PGSOCKETDIR

-U username
--username=username
集簇的安装用户名；环境变量 PGUSER

-v
--verbose
启用详细的内部日志

-V
--version
显示版本信息，然后退出

--clone
使用有效的文件克隆（在一些系统上也被称为“reflinks”），而不是将文件拷贝到新群集。 这可以导致数据文件接近瞬时的复制，从而获得-k/--link的速度优势，同时保留旧群集不受影响。

文件克隆仅在某些操作系统和文件系统上得到支持。如果选中但不被支持，则 pg_upgrade运行将会出错。 目前，它支持在Linux（内核4.5或更高版本）上的Btrfs和XFS（在文件系统创建reflink支持），以及macOS上的APFS。

-?
--help
显示帮助，然后退出

4 升级

4.1 移动旧集簇（可选）

1.1 假如，你使用的是一个与版本相关的安装目录（例如 /pgccc/app/14.7），则不需要移动它。在安装过程中，会自动创建新版本的相关的安装目录，与旧版本区别开来。

1.2 假如，你使用的目录不是与版本相关的（例如 /pgccc/app），那么就有必要移动当前的postgresql安装目录，以避免干扰新版本postgresql安装目录。

当前的postgresql服务被关闭后，就可以重命名postgresql安装目录。假台旧目录是：/pgccc/app，则重命名为：mv /pgccc/app /pgccc/app.old。

以下的安装演示，是属于1.1的情况。

4.2 源码安装，编译新版本

使用与旧版本集簇配置兼容的configure编译新的PostgreSQL源码。在开始升级之前，pg_upgrade 将检查pg_controldata来确保所有设置都是兼容的。

# 在root下操作：
wget https://ftp.postgresql.org/pub/source/v15.2/postgresql-15.2.tar.gz
tar -zxvf postgresql-15.2.tar.gz
cd postgresql-15.2
chmod +x configure
./configure --prefix=/pgccc/app/15.2

4.3 安装新的 PostgreSQL 二进制文件

安装新服务器的二进制文件和支持文件。pg_upgrade 会被包含在默认的安装中。

对于源码安装，如果你希望把新服务器安装在一个自定义的位置，可以使用prefix变量：（configure参数已经设置prefix，此处不再配置）

例如：make prefix=/usr/local/pgsql.new install

# 具体过程太长 不做截图等
make
make install

4.4 初始化新的 Postgresql 集簇

官方原文：Initialize the new cluster using initdb. Again, use compatible initdb flags that match the old cluster. Many prebuilt installers do this step automatically. There is no need to start the new cluster.

翻译：使用initdb初始化新集簇。这里也要使用与旧集簇相兼容的initdb标志。许多预编译的安装程序会自动做这个步骤。这里没有必要启动新集簇。

说明：要使用新版本中的 initdb 初始化,否则会在check阶段提示错误 This utility can only upgrade to PostgreSQL version 15.要使用新版本的新的数据目录 /pgccc/pgdata.new 此目录会在初始化时自动创建。

# 初始化新集簇
su - postgres

[postgres@pgccc ~]$ /pgccc/app/15.2/bin/initdb -D /pgccc/pgdata.new -U postgres
The files belonging to this database system will be owned by user "postgres".
This user must also own the server process.

The database cluster will be initialized with locale "en_US.UTF-8".
The default database encoding has accordingly been set to "UTF8".
The default text search configuration will be set to "english".

Data page checksums are disabled.

creating directory /pgccc/pgdata.new ... ok
creating subdirectories ... ok
selecting dynamic shared memory implementation ... posix
selecting default max_connections ... 100
selecting default shared_buffers ... 128MB
selecting default time zone ... Asia/Shanghai
creating configuration files ... ok
running bootstrap script ... ok
performing post-bootstrap initialization ... ok
syncing data to disk ... ok

initdb: warning: enabling "trust" authentication for local connections
initdb: hint: You can change this by editing pg_hba.conf or using the option -A, or --auth-local and --auth-host, the next time you run initdb.

Success. You can now start the database server using:

    /pgccc/app/15.2/bin/pg_ctl -D /pgccc/pgdata.new -l logfile start

[postgres@pgccc ~]$

4.5 安装扩展共享对象文件

许多扩展和自定义模块，无论是来自contrib或其他源，使用共享对象文件(或DLLs)，例如， pgcrypto.so。如果旧集群使用过这些，匹配新服务器二进制的共享对象文件，必须安装在新集群中。通常是通过操作系统命令。不要加载模式定义，例如CREATE EXTENSION pgcrypto，因为这些将从旧集群复制。如果扩展更新是可用的，pg_upgrade将报告这一点，并创建一个脚本，可以稍后运行来更新它们。

后面的操作中，有做过 file_fdw ，在进行升级检查是会有相关 fatal 提示。

4.6 拷贝定制的全文本索引文件

从旧集群向新集群拷贝任何定制化全文本检索文件(词典、同义词、辞典、停用词)

4.7 调整认证

pg_upgrade将会多次连接到旧服务器和新服务器，因此要在 pg_hba.conf 中把认证设置成 peer或者使用一个~/.pgpass文件（见第 34.15 节）。

4.8 停止两个服务器

确认两个数据库服务器都被停止使用。

# STOP 旧/新服务
pg_ctl -D /pgccc/pgdata -U postgres -l logfile stop
pg_ctl -D /pgccc/pgdata.new -U postgres -l logfile stop

# 直到后面的步骤之前，流复制和日志传送后备服务器可以保持运行。

4.9 准备工作

如果正在使用小节步骤 11（升级流复制和日志传送后备服务器）中给出的方法升级后备服务器，对旧的主集簇和后备集簇运行 pg_controldata 以验证旧的后备服务器已经完全追上。验证“Latest checkpoint location”值在所有集簇中都匹配（如果旧后备服务器在旧的主服务器之前被关闭或者如果旧的后备服务器仍在运行，则将会出现失配）。

此外，要确保在新的主集簇上的 postgresql.conf 文件中，wal_level未设置为 minimal。

4.10 运行 pg_upgrade

在这里需运行新版本目录下的pg_upgrade二进制文件。

运行pg_upgrade，需要分别指定新旧版本数据（data）目录和可执行文件（bin）目录。

这里也可指定用户和端口,以及你是否想要用链接或克隆来取代默认的复制行为对数据文件进行处理。

如果你使用链接模式，升级将会快很多（不需要文件拷贝）并且将使用更少的磁盘空间，但是在升级后一旦启动新集簇，旧集簇就无法被访问。

链接模式也要求新旧集簇数据目录位于同一个文件系统中（表空间和 pg_wal可以在不同的文件系统中）。

克隆模式提供了相同的速度以及磁盘空间优势，但不会导致新群集启动后旧群集不可用。

克隆模式还需要新旧数据目录位于同一文件系统中。此模式仅在某些操作系统和文件系统上可用。

--jobs选项允许多个 CPU 核心被用来复制/链接文件以及并行地转储和重载数据库模式。

这个选项一个比较好的值是 CPU 核心数和表空间数的最大值。

这个选项可以显著地减少升级运行在一台多处理器机器上的多数据库服务器的时间。

一旦启动，pg_upgrade将验证两个集簇是否兼容并且执行升级。

本示例，没有使用 --link 或 --clone

你可以使用pg_upgrade --check来只执行检查，这种模式即使在旧服务器还在运行时也能使用。

pg_upgrade --check也将列出任何在更新后需要做的手工调整。

如果你将要使用链接或克隆模式，你应该使用--link或--clone选项和--check一起来启用链接模式相关的检查。

pg_upgrade 要求在当前目录中有写权限。

1.默认使用操作系统命令复制数据文件到新目录，这种方式需要文件系统上有足够的空间存储双份数据，如果数据量很大，复制数据文件的过程会占用较长的升级时间。

2.使用 —link 参数，在新数据目录下做数据文件的硬链接，优点是不需要双倍空间存储数据文件，并且升级过程中不需要复制数据文件，节约升级时间，缺点是使用新版本软件启动数据库后不能再使用旧版本软件启动数据库，不利于升级后的回滚，建议做好数据库备份。

3.使用 —clone 参数，有操作系统内核版本和文件系统类型限制，比如需要XFS格式。这种方式也需要文件系统上有足够的空间存储双份数据，但是相比于第一种方式，速度要快得多，堪比第二种方式。

本示例，没有使用 --link 或 --clone

需要注意的是，不可以在升级期间访问这些集簇。pg_upgrade 默认会在端口 50432 上运行服务器来避免意外的客户端连接。在做升级时，可以对两个集簇使用相同的端口号，因为新旧集簇不会在同时被运行。不过，在检查一个旧的运行中服务器时，新旧端口号必须不同。

如果在恢复数据库模式时发生错误，pg_upgrade将会退出并且你必须按照下文步骤 17中所说的恢复旧集簇。

要再次尝试pg_upgrade，你将需要修改旧集簇，这样 pg_upgrade 模式会成功恢复。

如果问题是一个 contrib模块，你可能需要从旧集簇中卸载该模块并且在升级后重新把它安装在新集簇中，不过这样做的前提是该模块没有被用来存储用户数据。

# 检测
[postgres@pgccc ~]$ /pgccc/app/15.2/bin/pg_upgrade -b /pgccc/app/14.7/bin -B /pgccc/app/15.2/bin -d /pgccc/pgdata -D /pgccc/pgdata.new -c
Performing Consistency Checks
-----------------------------
Checking cluster versions                                   ok
Checking database user is the install user                  ok
Checking database connection settings                       ok
Checking for prepared transactions                          ok
Checking for system-defined composite types in user tables  ok
Checking for reg* data types in user tables                 ok
Checking for contrib/isn with bigint-passing mismatch       ok
Checking for presence of required libraries                 ok
Checking database user is the install user                  ok
Checking for prepared transactions                          ok
Checking for new cluster tablespace directories             ok

*Clusters are compatible*
[postgres@pgccc ~]$

# 升级
[postgres@pgccc ~]$ /pgccc/app/15.2/bin/pg_upgrade -b /pgccc/app/14.7/bin -B /pgccc/app/15.2/bin -d /pgccc/pgdata -D /pgccc/pgdata.new
Performing Consistency Checks
-----------------------------
Checking cluster versions                                   ok
Checking database user is the install user                  ok
Checking database connection settings                       ok
Checking for prepared transactions                          ok
Checking for system-defined composite types in user tables  ok
Checking for reg* data types in user tables                 ok
Checking for contrib/isn with bigint-passing mismatch       ok
Creating dump of global objects                             ok
Creating dump of database schemas                           
                                                            ok
Checking for presence of required libraries                 ok
Checking database user is the install user                  ok
Checking for prepared transactions                          ok
Checking for new cluster tablespace directories             ok

If pg_upgrade fails after this point, you must re-initdb the
new cluster before continuing.

Performing Upgrade
------------------
Analyzing all rows in the new cluster                       ok
Freezing all rows in the new cluster                        ok
Deleting files from new pg_xact                             ok
Copying old pg_xact to new server                           ok
Setting oldest XID for new cluster                          ok
Setting next transaction ID and epoch for new cluster       ok
Deleting files from new pg_multixact/offsets                ok
Copying old pg_multixact/offsets to new server              ok
Deleting files from new pg_multixact/members                ok
Copying old pg_multixact/members to new server              ok
Setting next multixact ID and offset for new cluster        ok
Resetting WAL archives                                      ok
Setting frozenxid and minmxid counters in new cluster       ok
Restoring global objects in the new cluster                 ok
Restoring database schemas in the new cluster               
                                                            ok
Copying user relation files                                 
                                                            ok
Setting next OID for new cluster                            ok
Sync data directory to disk                                 ok
Creating script to delete old cluster                       ok
Checking for extension updates                              ok

Upgrade Complete
----------------
Optimizer statistics are not transferred by pg_upgrade.
Once you start the new server, consider running:
    /pgccc/app/15.2/bin/vacuumdb --all --analyze-in-stages

Running this script will delete the old cluster's data files:
    ./delete_old_cluster.sh

4.11 修改环境变量为新版本相关

[postgres@pgccc ~]$ vim ~/.bash_profile
... ...
#指向PG可执行程序的路径(安装路径)
export PGHOME=/pgccc/app/15.2
#指向数据库目录
export PGDATA=/pgccc/pgdata.new
... ...
[postgres@pgccc ~]$ source ~/.bash_profile

4.12 启动数据库并查看版本

[postgres@pgccc ~]$ pg_start
waiting for server to start....2023-04-23 19:59:41.893 CST [30499] LOG:  starting PostgreSQL 15.2 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 4.8.5 20150623 (Red Hat 4.8.5-44), 64-bit
2023-04-23 19:59:41.893 CST [30499] LOG:  listening on IPv6 address "::1", port 5432
2023-04-23 19:59:41.893 CST [30499] LOG:  listening on IPv4 address "127.0.0.1", port 5432
2023-04-23 19:59:41.901 CST [30499] LOG:  listening on Unix socket "/tmp/.s.PGSQL.5432"
2023-04-23 19:59:41.913 CST [30502] LOG:  database system was shut down at 2023-04-23 19:55:55 CST
2023-04-23 19:59:41.919 CST [30499] LOG:  database system is ready to accept connections
 done
server started
[postgres@pgccc ~]$ psql
psql (15.2)
Type "help" for help.

postgres=# exit
[postgres@pgccc ~]$

5 遇到的问题

提示，新的安装中缺少可加载的插件。你可以将插件从旧的集簇删除，也可将其添加到新集簇。

查看下方提示的日志记录，提示缺少 file_fdw 。这里的处理是，将其从旧集簇删除。

[postgres@pgccc ~]$ /pgccc/app/15.2/bin/pg_upgrade -b /pgccc/app/14.7/bin -B /pgccc/app/15.2/bin -d /pgccc/pgdata -D /pgccc/pgdata.new -c
Performing Consistency Checks
-----------------------------
Checking cluster versions                                   ok
Checking database user is the install user                  ok
Checking database connection settings                       ok
Checking for prepared transactions                          ok
Checking for system-defined composite types in user tables  ok
Checking for reg* data types in user tables                 ok
Checking for contrib/isn with bigint-passing mismatch       ok
Checking for presence of required libraries                 fatal

Your installation references loadable libraries that are missing from the
new installation.  You can add these libraries to the new installation,
or remove the functions using them from the old installation.  A list of
problem libraries is in the file:
    /pgccc/pgdata.new/pg_upgrade_output.d/20230801T100522.997/loadable_libraries.txt

Failure, exiting
[postgres@pgccc ~]$ cat /pgccc/pgdata.new/pg_upgrade_output.d/20230801T100522.997/loadable_libraries.txt
could not load library "$libdir/file_fdw": ERROR:  could not access file "$libdir/file_fdw": No such file or directory
In database: postgres
[postgres@pgccc ~]$ pg_start
waiting for server to start....2023-08-01 10:06:35.705 CST [28982] LOG:  redirecting log output to logging collector process
2023-08-01 10:06:35.705 CST [28982] HINT:  Future log output will appear in directory "log".
 done
server started
[postgres@pgccc ~]$ psql
psql (14.7)
Type "help" for help.

postgres=# drop extension file_fdw;
ERROR:  cannot drop extension file_fdw because other objects depend on it
DETAIL:  server pg_log depends on foreign-data wrapper file_fdw
user mapping for postgres on server pg_log depends on server pg_log
foreign table pglog3 depends on server pg_log
foreign table passwd depends on server pg_log
foreign table pglog4 depends on server pg_log
foreign table pglog5 depends on server pg_log
HINT:  Use DROP ... CASCADE to drop the dependent objects too.
postgres=#
postgres=# drop extension file_fdw CASCADE;
NOTICE:  drop cascades to 6 other objects
DETAIL:  drop cascades to server pg_log
drop cascades to user mapping for postgres on server pg_log
drop cascades to foreign table pglog3
drop cascades to foreign table passwd
drop cascades to foreign table pglog4
drop cascades to foreign table pglog5
DROP EXTENSION
postgres=#

6 回退

################################################

若需回退到旧版本的数据库，可以分为以下三种情况：

################################################

1、如果只运行了 —check 选项命令，表示没有真正执行升级，重新启动服务即可；

2、如果升级时没有使用 —link 选项，旧版本的数据库集群没有任何修改，重新启动服务即可；

3、如果升级时使用了 —link 选项，数据库文件可能已经被新版本的集群使用：

a、如果 pg_upgrade 在链接操作之前终止，旧版本的数据库集群没有任何修改，重新启动服务即可；

b、如果没有启动过新版本的后台服务，旧版本的数据库集群没有修改，但是链接过程已经将 $PGDATA/global/pg_control 文件重命名为 $PGDATA/global/pg_control.old；此时需要将该文件名中的 .old 后缀去掉，然后重新启动服务即可；

c、如果已经启动了新版本的数据库集群，已经修改了数据库文件，再启动旧版本的服务可能导致数据损坏；此时需要通过备份文件还原旧版本的数据库。(所以做任何操作之前，需要备份数据库，以便回退)。所以在升级中，尽量避免使用link参数进行升级。

标签：15.2,upgrade,ok,--,Checking,版本升级,pgccc,new,pg
From： https://blog.51cto.com/baoyw/6935266