Skip to content

Commit 2358c73

Browse files
AndriciucAndriciuc
authored
PG-1567-Release-notes-14.18 (#795)
* initial commit initial commit for 14.18 RNs * updated major upgrade and RN Updated the Major Upgrade topic with pg-1599 info and updated the release notes with correct links to the latest release + slight date modification to variables pending release * updated dates and procedures updated dates for tomorrow's release, updated tarball procedures based on Naeem's feedback
1 parent 4ca11b6 commit 2358c73

File tree

8 files changed

+178
-128
lines changed

8 files changed

+178
-128
lines changed

‎.github/workflows/main.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ jobs:
4545
- name: Deploy docs
4646
run: |
4747
mike deploy 14 -b publish -p
48-
mike retitle 14 "14.17" -b publish -p
48+
mike retitle 14 "14.18" -b publish -p
4949
5050
# - name: Install Node.js 14.x
5151
# uses: percona-platform/setup-node@v2

‎docs/major-upgrade.md

Lines changed: 115 additions & 122 deletions
Original file line numberDiff line numberDiff line change
@@ -3,18 +3,16 @@
33
This document describes the in-place upgrade of Percona Distribution for PostgreSQL using the `pg_upgrade`
44
tool.
55

6-
!!! important
6+
To ensure a smooth upgrade path, follow these steps:
7+
8+
* Upgrade to the latest minor version within your current major version (e.g., from 13.20 to 13.21).
9+
* Then, perform the major upgrade to your desired version (e.g., from 13.21 to 14.18).
710

11+
!!! note
812
When running a major upgrade on **RHEL 8 and compatible derivatives**, consider the following:
913

1014
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.
1115

12-
To ensure a smooth upgrade path, follow these steps:
13-
14-
* Upgrade to the latest minor version within your current major version (e.g., from 13.14 to 13.15).
15-
* Then, perform the major upgrade to your desired version (e.g., from 13.15 to 14.12).
16-
17-
1816
The in-place upgrade means installing a new version without removing the old version and keeping the data files on the server.
1917

2018
!!! admonition "See also"
@@ -29,26 +27,19 @@ Similar to installing, we recommend you to upgrade Percona Distribution for Post
2927

3028
The general in-place upgrade flow for Percona Distribution for PostgreSQL is the following:
3129

32-
3330
1. Install Percona Distribution for PostgreSQL 14 packages.
3431

35-
3632
2. Stop the PostgreSQL service.
3733

38-
3934
3. Check the upgrade without modifying the data.
4035

41-
4236
4. Upgrade Percona Distribution for PostgreSQL.
4337

44-
4538
5. Start PostgreSQL service.
4639

47-
4840
6. Execute the **analyze_new_cluster.sh** script to generate statistics
4941
so the system is usable.
5042

51-
5243
7. Delete old packages and configuration files.
5344

5445
The exact steps may differ depending on the package manager of your operating system.
@@ -60,16 +51,18 @@ Run **all** commands as root or via **sudo**:
6051

6152
1. Install Percona Distribution for PostgreSQL 14 packages.
6253

54+
!!! note
55+
When installing version 14, if prompted via a pop-up to upgrade to the latest available version, select **No**.
6356

64-
* [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)
65-
66-
* Enable Percona repository:
57+
* [Install percona-release :octicons-link-external-14:](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)
58+
59+
* Enable Percona repository
6760

6861
```{.bash data-prompt="$"}
6962
$ sudo percona-release setup ppg-14
7063
```
7164

72-
* Install Percona Distribution for PostgreSQL 14 package:
65+
* Install Percona Distribution for PostgreSQL 14 package
7366

7467
```{.bash data-prompt="$"}
7568
$ sudo apt install percona-postgresql-14
@@ -83,131 +76,141 @@ Run **all** commands as root or via **sudo**:
8376

8477
This stops both Percona Distribution for PostgreSQL 13 and 14.
8578

86-
8779
3. Run the database upgrade.
8880

81+
* Log in as the `postgres` user
8982

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

119-
**Sample output**
87+
* Check if you can upgrade Percona Distribution for PostgreSQL from 13 to 14
12088

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

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

14096
* Upgrade the Percona Distribution for PostgreSQL
14197

142-
```{.bash data-prompt="$"}
143-
$ /usr/lib/postgresql/14/bin/pg_upgrade
144-
--old-datadir=/var/lib/postgresql/13/main \
145-
--new-datadir=/var/lib/postgresql/14/main \
146-
--old-bindir=/usr/lib/postgresql/13/bin \
147-
--new-bindir=/usr/lib/postgresql/14/bin \
148-
--old-options '-c config_file=/etc/postgresql/13/main/postgresql.conf' \
149-
--new-options '-c config_file=/etc/postgresql/14/main/postgresql.conf' \
150-
--link
151-
```
152-
153-
The `--link` flag creates hard links to the files on the old version cluster so you don’t need to copy data.
154-
155-
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.
156-
157-
158-
* Go back to the regular user:
159-
160-
161-
```{.bash data-prompt="$"}
162-
$ exit
163-
```
164-
165-
166-
* The Percona Distribution for PostgreSQL 13 uses the `5432` port while the Percona Distribution for PostgreSQL 14 is set up to use the `5433` port by default. To start the Percona Distribution for PostgreSQL 14, swap ports in the configuration files of both versions.
167-
168-
```{.bash data-prompt="$"}
169-
$ sudo vim /etc/postgresql/14/main/postgresql.conf
170-
$ port = 5433 # Change to 5432 here
171-
$ sudo vim /etc/postgresql/13/main/postgresql.conf
172-
$ port = 5432 # Change to 5433 here
173-
```
98+
```bash
99+
$ pg_upgradecluster 13 main
100+
```
174101

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

176187
4. Start the `postgreqsl` service.
177188

178189
```{.bash data-prompt="$"}
179190
$ sudo systemctl start postgresql.service
180191
```
181192

182-
183193
5. Check the `postgresql` version.
184194

185195
* Log in as a postgres user
186-
196+
187197
```{.bash data-prompt="$"}
188198
$ sudo su postgres
189199
```
190200

191201
* Check the database version
192-
202+
193203
```{.bash data-prompt="$"}
194204
$ psql -c "SELECT version();"
195205
```
196206

207+
6. Delete the old cluster's data files.
197208
198-
6. After the upgrade, the Optimizer statistics are not transferred to the new cluster. Run the `vaccumdb` command to analyze the new cluster:
209+
!!! note
210+
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.
199211
200212
```{.bash data-prompt="$"}
201-
$ /usr/lib/postgresql/14/bin/vacuumdb --all --analyze-in-stages
202-
```
203-
204-
7. Delete the old cluster's data files:
205-
206-
```{.bash data-prompt="$"}
207-
$ ./delete_old_cluster.sh
208-
$ sudo rm -rf /etc/postgresql/13/main
209-
$ #Logout
210-
$ exit
213+
$ pg_dropcluster 13 main
211214
```
212215
213216
## On Red Hat Enterprise Linux and derivatives using `yum`
@@ -217,16 +220,14 @@ Run **all** commands as root or via **sudo**:
217220
218221
1. Install Percona Distribution for PostgreSQL 14 packages
219222
220-
221223
* [Install percona-release :octicons-link-external-16:](https://docs.percona.com/percona-software-repositories/installing.html)
222-
224+
223225
* Enable Percona repository:
224226
225227
```{.bash data-prompt="$"}
226228
$ sudo percona-release setup ppg-14
227229
```
228230
229-
230231
* Install Percona Distribution for PostgreSQL 14:
231232
232233
```{.bash data-prompt="$"}
@@ -262,14 +263,12 @@ Run **all** commands as root or via **sudo**:
262263
263264
4. Run the database upgrade.
264265
265-
266266
* Log in as the `postgres` user
267267
268268
```{.bash data-prompt="$"}
269269
$ sudo su postgres
270270
```
271271
272-
273272
* Check the ability to upgrade Percona Distribution for PostgreSQL from 13 to 14:
274273
275274
```{.bash data-prompt="$"}
@@ -303,7 +302,6 @@ Run **all** commands as root or via **sudo**:
303302
*Clusters are compatible*
304303
```
305304
306-
307305
* Upgrade the Percona Distribution for PostgreSQL
308306
309307
```{.bash data-prompt="$"}
@@ -318,7 +316,6 @@ Run **all** commands as root or via **sudo**:
318316
The `--link` flag creates hard links to the files on the old version cluster so you don’t need to copy data.
319317
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.
320318
321-
322319
5. Start the `postgresql` 14 service.
323320
324321
```{.bash data-prompt="$"}
@@ -331,10 +328,8 @@ Run **all** commands as root or via **sudo**:
331328
$ systemctl status postgresql-14
332329
```
333330
334-
335331
7. After the upgrade, the Optimizer statistics are not transferred to the new cluster. Run the `vaccumdb` command to analyze the new cluster:
336332
337-
338333
* Log in as the postgres user
339334
340335
```{.bash data-prompt="$"}
@@ -347,14 +342,12 @@ Run **all** commands as root or via **sudo**:
347342
$ /usr/pgsql-14/bin/vacuumdb --all --analyze-in-stages
348343
```
349344
350-
351345
8. Delete Percona Distribution for PostgreSQL 13 configuration files
352346
353347
```{.bash data-prompt="$"}
354348
$ ./delete_old_cluster.sh
355349
```
356350
357-
358351
9. Delete Percona Distribution old data files
359352
360353
```{.bash data-prompt="$"}

0 commit comments

Comments
 (0)