Skip to content

Commit 2b90a9d

Browse files
AndriciucAndriciuc
authored
PG-1567-Release-notes-16.9 (#793)
* Create release-notes-v16.9.md initial commit * updated ver nr and dates updated version numbers and added release variable * Update variables.yml updated with date * Updated rel notes link For 16.8 and 16.9 * updated major-upgrade Updated with a bit more feedback on the !!! important note, reworded it a bit. * upgraded major steps based on pg-1599, updated steps to upgrade major version On Debian and Ubuntu using `apt` topic * Added documentation note To the release notes regarding the new updated major upgrade chapter steps * small fixes small linting updates and added latest release note to index * updated tarball with a precondition Added additional precondition + set the correct date of release for 16.9 * small fix fixed space and reworded based on feedback from Naeem * date updates date updates and release notes informing user they are based and built upon 16.8 release
1 parent eaca92d commit 2b90a9d

File tree

9 files changed

+187
-122
lines changed

9 files changed

+187
-122
lines changed

‎.github/workflows/main.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ jobs:
4343
- name: Deploy docs
4444
run: |
4545
mike deploy 16 -b publish -p
46-
mike retitle 16 "16.8" -b publish -p
46+
mike retitle 16 "16.9" -b publish -p
4747
4848
# - name: Install Node.js 14.x
4949
# uses: percona-platform/setup-node@v2

‎docs/major-upgrade.md

Lines changed: 114 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,15 @@
22

33
This document describes the in-place upgrade of Percona Distribution for PostgreSQL using the `pg_upgrade` tool.
44

5-
!!! important
5+
To ensure a smooth upgrade path, follow these steps:
66

7-
When running a major upgrade on **RHEL 8 and compatible derivatives**, consider the following:
8-
9-
Percona Distribution for PostgreSQL 16.3, 15.7, 14.12, 13.15 and 12.18 include `llvm` packages 16.0.6, while its previous versions 16.2, 15.6, 14.11, 13.14, and 12.17 include `llvm` 12.0.1. Since `llvm` libraries differ and are not compatible, the direct major version upgrade from 15.6 to 16.3 may cause issues.
7+
* Upgrade to the latest minor version within your current major version (e.g., from 15.11 to 15.13).
8+
* Then, perform the major upgrade to your desired version (e.g., from 15.13 to 16.9).
109

11-
To ensure a smooth upgrade path, follow these steps:
10+
!!! Note
11+
When running a major upgrade for **RHEL 8 and compatible derivatives**, consider the following:
1212

13-
* Upgrade to the latest minor version within your current major version (e.g., from 15.6 to 15.7).
14-
* Then, perform the major upgrade to your desired version (e.g., from 15.7 to 16.3).
13+
Percona Distribution for PostgreSQL 16.3, 15.7, 14.12, 13.15 and 12.18 include `llvm` packages 16.0.6, while its previous versions 16.2, 15.6, 14.11, 13.14, and 12.17 include `llvm` 12.0.1. Since `llvm` libraries differ and are not compatible, the direct major version upgrade from 15.6 to 16.3 may cause issues.
1514

1615
The in-place upgrade means installing a new version without removing the old version and keeping the data files on the server.
1716

@@ -58,17 +57,18 @@ Run **all** commands as root or via **sudo**:
5857

5958
1. Install Percona Distribution for PostgreSQL 16 packages.
6059

60+
!!! note
61+
When installing version 16, if prompted via a pop-up to upgrade to the latest available version, select **No**.
6162

6263
* [Install percona-release :octicons-link-external-16:](https://docs.percona.com/percona-software-repositories/installing.html). If you have installed it before, [update it to the latest version](https://docs.percona.com/percona-software-repositories/updating.html)
63-
64-
* Enable Percona repository:
64+
65+
* Enable Percona repository
6566

6667
```{.bash data-prompt="$"}
6768
$ sudo percona-release setup ppg-16
6869
```
6970

70-
71-
* Install Percona Distribution for PostgreSQL 16 package:
71+
* Install Percona Distribution for PostgreSQL 16 package
7272

7373
```{.bash data-prompt="$"}
7474
$ sudo apt install percona-postgresql-16
@@ -82,141 +82,150 @@ Run **all** commands as root or via **sudo**:
8282

8383
This stops both Percona Distribution for PostgreSQL 15 and 16.
8484

85-
8685
3. Run the database upgrade.
8786

87+
* Log in as the `postgres` user
8888

89-
* Log in as the `postgres` user.
90-
91-
```{.bash data-prompt="$"}
92-
$ sudo su postgres
93-
```
94-
95-
96-
* Change the current directory to the `tmp` directory where logs and some scripts will be recorded:
97-
98-
```{.bash data-prompt="$"}
99-
$ cd tmp/
100-
```
101-
102-
103-
* Check the ability to upgrade Percona Distribution for PostgreSQL from 15 to 16:
104-
105-
```{.bash data-prompt="$"}
106-
$ /usr/lib/postgresql/16/bin/pg_upgrade \
107-
--old-datadir=/var/lib/postgresql/15/main \
108-
--new-datadir=/var/lib/postgresql/16/main \
109-
--old-bindir=/usr/lib/postgresql/15/bin \
110-
--new-bindir=/usr/lib/postgresql/16/bin \
111-
--old-options '-c config_file=/etc/postgresql/15/main/postgresql.conf' \
112-
--new-options '-c config_file=/etc/postgresql/16/main/postgresql.conf' \
113-
--check
114-
```
115-
116-
The `--check` flag here instructs `pg_upgrade` to only check the upgrade without changing any data.
89+
```{.bash data-prompt="$"}
90+
$ sudo su postgres
91+
```
11792

118-
**Sample output**
93+
* Check if you can upgrade Percona Distribution for PostgreSQL from 15 to 16
11994

120-
```
121-
Performing Consistency Checks
122-
-----------------------------
123-
Checking cluster versions ok
124-
Checking database user is the install user ok
125-
Checking database connection settings ok
126-
Checking for prepared transactions ok
127-
Checking for reg* data types in user tables ok
128-
Checking for contrib/isn with bigint-passing mismatch ok
129-
Checking for tables WITH OIDS ok
130-
Checking for invalid "sql_identifier" user columns ok
131-
Checking for presence of required libraries ok
132-
Checking database user is the install user ok
133-
Checking for prepared transactions ok
134-
135-
*Clusters are compatible*
136-
```
95+
```bash
96+
$ pg_upgradecluster 15 main --check
97+
# Sample output: pg_upgradecluster pre-upgrade checks ok
98+
```
13799

100+
The `--check` flag here instructs `pg_upgrade` to only check the upgrade without changing any data.
138101

139102
* Upgrade the Percona Distribution for PostgreSQL
140103

141-
```{.bash data-prompt="$"}
142-
$ /usr/lib/postgresql/16/bin/pg_upgrade \
143-
--old-datadir=/var/lib/postgresql/15/main \
144-
--new-datadir=/var/lib/postgresql/16/main \
145-
--old-bindir=/usr/lib/postgresql/15/bin \
146-
--new-bindir=/usr/lib/postgresql/16/bin \
147-
--old-options '-c config_file=/etc/postgresql/15/main/postgresql.conf' \
148-
--new-options '-c config_file=/etc/postgresql/16/main/postgresql.conf' \
149-
--link
150-
```
151-
152-
The `--link` flag creates hard links to the files on the old version cluster so you don’t need to copy data.
153-
154-
If you don’t wish to use the `--link` option, make sure that you have enough disk space to store 2 copies of files for both old version and new version clusters.
155-
156-
157-
* Go back to the regular user:
158-
159-
```{.bash data-prompt="$"}
160-
$ exit
161-
```
162-
163-
164-
* The Percona Distribution for PostgreSQL 15 uses the `5432` port while the Percona Distribution for PostgreSQL 16 is set up to use the `5433` port by default. To start the Percona Distribution for PostgreSQL 15, swap ports in the configuration files of both versions.
165-
166-
```{.bash data-prompt="$"}
167-
$ sudo vim /etc/postgresql/16/main/postgresql.conf
168-
$ port = 5433 # Change to 5432 here
169-
$ sudo vim /etc/postgresql/15/main/postgresql.conf
170-
$ port = 5432 # Change to 5433 here
171-
```
104+
```bash
105+
$ pg_upgradecluster 15 main
106+
```
172107

108+
<details>
109+
<summary>Sample output (click to expand)</summary>
110+
```bash
111+
Upgrading cluster 15/main to 16/main ...
112+
Stopping old cluster...
113+
Restarting old cluster with restricted connections...
114+
...
115+
Success. Please check that the upgraded cluster works. If it does,
116+
you can remove the old cluster with:
117+
pg_dropcluster 15 main
118+
119+
Ver Cluster Port Status Owner Data directory Log file
120+
16 main 5432 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16-main.log
121+
122+
Sample output:
123+
Upgrading cluster 15/main to 16/main ...
124+
Stopping old cluster...
125+
Restarting old cluster with restricted connections...
126+
Notice: extra pg_ctl/postgres options given, bypassing systemctl for start operation
127+
Creating new PostgreSQL cluster 16/main ...
128+
/usr/lib/postgresql/16/bin/initdb -D /var/lib/postgresql/16/main --auth-local peer --auth-host scram-sha-256 --no-instructions --encoding UTF8 --lc-collate C.UTF-8 --lc-ctype C.UTF-8 --locale-provider libc
129+
The files belonging to this database system will be owned by user "postgres".
130+
This user must also own the server process.
131+
132+
The database cluster will be initialized with locale "C.UTF-8".
133+
The default text search configuration will be set to "english".
134+
135+
Data page checksums are disabled.
136+
137+
fixing permissions on existing directory /var/lib/postgresql/16/main ... ok
138+
creating subdirectories ... ok
139+
selecting dynamic shared memory implementation ... posix
140+
selecting default max_connections ... 100
141+
selecting default shared_buffers ... 128MB
142+
selecting default time zone ... Etc/UTC
143+
creating configuration files ... ok
144+
running bootstrap script ... ok
145+
performing post-bootstrap initialization ... ok
146+
syncing data to disk ... ok
147+
148+
Copying old configuration files...
149+
Copying old start.conf...
150+
Copying old pg_ctl.conf...
151+
Starting new cluster...
152+
Notice: extra pg_ctl/postgres options given, bypassing systemctl for start operation
153+
Running init phase upgrade hook scripts ...
154+
155+
Roles, databases, schemas, ACLs...
156+
set_config
157+
------------
158+
159+
(1 row)
160+
161+
set_config
162+
------------
163+
164+
(1 row)
165+
166+
Fixing hardcoded library paths for stored procedures...
167+
Upgrading database template1...
168+
Fixing hardcoded library paths for stored procedures...
169+
Upgrading database postgres...
170+
Stopping target cluster...
171+
Stopping old cluster...
172+
Disabling automatic startup of old cluster...
173+
Starting upgraded cluster on port 5432...
174+
Running finish phase upgrade hook scripts ...
175+
vacuumdb: processing database "postgres": Generating minimal optimizer statistics (1 target)
176+
vacuumdb: processing database "template1": Generating minimal optimizer statistics (1 target)
177+
vacuumdb: processing database "postgres": Generating medium optimizer statistics (10 targets)
178+
vacuumdb: processing database "template1": Generating medium optimizer statistics (10 targets)
179+
vacuumdb: processing database "postgres": Generating default (full) optimizer statistics
180+
vacuumdb: processing database "template1": Generating default (full) optimizer statistics
181+
182+
Success. Please check that the upgraded cluster works. If it does,
183+
you can remove the old cluster with
184+
pg_dropcluster 15 main
185+
186+
Ver Cluster Port Status Owner Data directory Log file
187+
15 main 5433 down postgres /var/lib/postgresql/15/main /var/log/postgresql/postgresql-15-main.log
188+
Ver Cluster Port Status Owner Data directory Log file
189+
16 main 5432 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16-main.log
190+
```
191+
</details>
173192

174193
4. Start the `postgreqsl` service.
175194

176195
```{.bash data-prompt="$"}
177196
$ sudo systemctl start postgresql.service
178197
```
179198

180-
181199
5. Check the `postgresql` version.
182200

183201
* Log in as a postgres user
184-
202+
185203
```{.bash data-prompt="$"}
186204
$ sudo su postgres
187205
```
188206

189207
* Check the database version
190-
208+
191209
```{.bash data-prompt="$"}
192210
$ psql -c "SELECT version();"
193211
```
194212

213+
6. Delete the old cluster's data files.
195214
196-
6. After the upgrade, the Optimizer statistics are not transferred to the new cluster. Run the `vaccumdb` command to analyze the new cluster:
197-
198-
```{.bash data-prompt="$"}
199-
$ /usr/lib/postgresql/16/bin/vacuumdb --all --analyze-in-stages
200-
```
215+
!!! note
216+
Before deleting the old cluster, verify that the newly upgraded cluster is fully operational. Keeping the old cluster does not negatively affect the functionality or performance of your upgraded cluster.
201217
202-
7. Delete the old cluster's data files:
203-
204218
```{.bash data-prompt="$"}
205-
$ ./delete_old_cluster.sh
206-
$ sudo rm -rf /etc/postgresql/15/main
207-
$ #Logout
208-
$ exit
219+
$ pg_dropcluster 15 main
209220
```
210221
211-
212222
## On Red Hat Enterprise Linux and CentOS using `yum`
213223
214224
Run **all** commands as root or via **sudo**:
215225
{.power-number}
216226
217227
1. Install Percona Distribution for PostgreSQL 16 packages
218228
219-
220229
* [Install percona-release :octicons-link-external-16:](https://docs.percona.com/percona-software-repositories/installing.html)
221230
222231
* Enable Percona repository:
@@ -225,7 +234,6 @@ Run **all** commands as root or via **sudo**:
225234
$ sudo percona-release setup ppg-16
226235
```
227236
228-
229237
* Install Percona Distribution for PostgreSQL 16:
230238
231239
```{.bash data-prompt="$"}
@@ -253,24 +261,20 @@ Run **all** commands as root or via **sudo**:
253261
$ /usr/pgsql-16/bin/initdb -D /var/lib/pgsql/16/data
254262
```
255263
256-
257264
3. Stop the `postgresql` 15 service
258265
259266
```{.bash data-prompt="$"}
260267
$ systemctl stop postgresql-15
261268
```
262269
263-
264270
4. Run the database upgrade.
265271
266-
267272
* Log in as the `postgres` user
268273
269274
```{.bash data-prompt="$"}
270275
$ sudo su postgres
271276
```
272277
273-
274278
* Check the ability to upgrade Percona Distribution for PostgreSQL from 15 to 16:
275279
276280
```{.bash data-prompt="$"}
@@ -304,7 +308,6 @@ Run **all** commands as root or via **sudo**:
304308
*Clusters are compatible*
305309
```
306310
307-
308311
* Upgrade the Percona Distribution for PostgreSQL
309312
310313
```{.bash data-prompt="$"}
@@ -319,7 +322,6 @@ Run **all** commands as root or via **sudo**:
319322
The `--link` flag creates hard links to the files on the old version cluster so you don’t need to copy data.
320323
If you don’t wish to use the `--link` option, make sure that you have enough disk space to store 2 copies of files for both old version and new version clusters.
321324
322-
323325
5. Start the `postgresql` 16 service.
324326
325327
```{.bash data-prompt="$"}
@@ -332,10 +334,8 @@ Run **all** commands as root or via **sudo**:
332334
$ systemctl status postgresql-16
333335
```
334336
335-
336337
7. After the upgrade, the Optimizer statistics are not transferred to the new cluster. Run the `vaccumdb` command to analyze the new cluster:
337338
338-
339339
* Log in as the postgres user
340340
341341
```{.bash data-prompt="$"}
@@ -348,14 +348,12 @@ Run **all** commands as root or via **sudo**:
348348
$ /usr/pgsql-16/bin/vacuumdb --all --analyze-in-stages
349349
```
350350
351-
352351
8. Delete Percona Distribution for PostgreSQL 15 configuration files
353352
354353
```{.bash data-prompt="$"}
355354
$ ./delete_old_cluster.sh
356355
```
357356
358-
359357
9. Delete Percona Distribution old data files
360358
361359
```{.bash data-prompt="$"}

0 commit comments

Comments
 (0)