Skip to content

Commit 4363938

Browse files
AndriciucAndriciuc
authored
PG-1567-Release-notes-15.13 (#794)
* Backport: Updated links + install/tarball docs (based on 0d46fe5, modified for v15) * PG-1567-Release-notes-15.13 initial commit * updated with changes to major upgrade and RN Added major upgrade changes as per pg-1599, updated RN with note of the doc change and small variable addition for pending release date * updated tarball commands and updated date for dates variable release 02-June * Update release-notes-v15.13.md removed previous highlights and kept "based on 15.13" * updated ver updated table ver nr and cover page date
1 parent 4ebd0d5 commit 4363938

File tree

8 files changed

+183
-131
lines changed

8 files changed

+183
-131
lines changed

‎.github/workflows/main.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ jobs:
4646
- name: Deploy docs
4747
run: |
4848
mike deploy 15 -b publish -p
49-
mike retitle 15 "15.12" -b publish -p
49+
mike retitle 15 "15.13" -b publish -p
5050
5151
# - name: Install Node.js 14.x
5252
# uses: percona-platform/setup-node@v2

‎docs/major-upgrade.md

Lines changed: 116 additions & 123 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,16 @@
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:
7+
* Upgrade to the latest minor version within your current major version (e.g., from 14.17 to 14.18).
8+
* Then, perform the major upgrade to your desired version (e.g., from 14.18 to 15.13).
89

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.
10+
!!! note
1011

11-
To ensure a smooth upgrade path, follow these steps:
12-
13-
* Upgrade to the latest minor version within your current major version (e.g., from 14.11 to 14.12).
14-
* Then, perform the major upgrade to your desired version (e.g., from 14.12 to 15.7).
12+
When running a major upgrade on **RHEL 8 and compatible derivatives**, consider the following:
1513

14+
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.
1615

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

@@ -28,26 +27,19 @@ Similar to installing, we recommend you to upgrade Percona Distribution for Post
2827

2928
The general in-place upgrade flow for Percona Distribution for PostgreSQL is the following:
3029

31-
3230
1. Install Percona Distribution for PostgreSQL 15 packages.
3331

34-
3532
2. Stop the PostgreSQL service.
3633

37-
3834
3. Check the upgrade without modifying the data.
3935

40-
4136
4. Upgrade Percona Distribution for PostgreSQL.
4237

43-
4438
5. Start PostgreSQL service.
4539

46-
4740
6. Execute the **analyze_new_cluster.sh** script to generate statistics
4841
so the system is usable.
4942

50-
5143
7. Delete old packages and configuration files.
5244

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

6052
1. Install Percona Distribution for PostgreSQL 15 packages.
6153

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

63-
* [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)
64-
65-
* Enable Percona repository:
57+
* [Install percona-release :octicons-link-external-15:](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
6660

6761
```{.bash data-prompt="$"}
6862
$ sudo percona-release setup ppg-15
6963
```
7064

71-
* Install Percona Distribution for PostgreSQL 15 package:
65+
* Install Percona Distribution for PostgreSQL 15 package
7266

7367
```{.bash data-prompt="$"}
7468
$ sudo apt install percona-postgresql-15
@@ -82,152 +76,158 @@ Run **all** commands as root or via **sudo**:
8276

8377
This stops both Percona Distribution for PostgreSQL 14 and 15.
8478

85-
8679
3. Run the database upgrade.
8780

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

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 14 to 15:
104-
105-
```{.bash data-prompt="$"}
106-
$ /usr/lib/postgresql/15/bin/pg_upgrade \
107-
--old-datadir=/var/lib/postgresql/14/main \
108-
--new-datadir=/var/lib/postgresql/15/main \
109-
--old-bindir=/usr/lib/postgresql/14/bin \
110-
--new-bindir=/usr/lib/postgresql/15/bin \
111-
--old-options '-c config_file=/etc/postgresql/14/main/postgresql.conf' \
112-
--new-options '-c config_file=/etc/postgresql/15/main/postgresql.conf' \
113-
--check
114-
```
115-
116-
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+
```
11786

118-
**Sample output**
87+
* Check if you can upgrade Percona Distribution for PostgreSQL from 14 to 15
11988

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-
```
89+
```{.bash data-prompt="$"}
90+
$ pg_upgradecluster 14 main --check
91+
# Sample output: pg_upgradecluster pre-upgrade checks ok
92+
```
13793

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

13996
* Upgrade the Percona Distribution for PostgreSQL
14097

141-
```{.bash data-prompt="$"}
142-
$ /usr/lib/postgresql/15/bin/pg_upgrade
143-
--old-datadir=/var/lib/postgresql/14/main \
144-
--new-datadir=/var/lib/postgresql/15/main \
145-
--old-bindir=/usr/lib/postgresql/14/bin \
146-
--new-bindir=/usr/lib/postgresql/15/bin \
147-
--old-options '-c config_file=/etc/postgresql/14/main/postgresql.conf' \
148-
--new-options '-c config_file=/etc/postgresql/15/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-
160-
```{.bash data-prompt="$"}
161-
$ exit
162-
```
163-
164-
165-
* The Percona Distribution for PostgreSQL 14 uses the `5432` port while the Percona Distribution for PostgreSQL 15 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.
166-
167-
```{.bash data-prompt="$"}
168-
$ sudo vim /etc/postgresql/15/main/postgresql.conf
169-
$ port = 5433 # Change to 5432 here
170-
$ sudo vim /etc/postgresql/14/main/postgresql.conf
171-
$ port = 5432 # Change to 5433 here
172-
```
98+
```{.bash data-prompt="$"}
99+
$ pg_upgradecluster 14 main
100+
```
173101

102+
<details>
103+
<summary>Sample output (click to expand)</summary>
104+
```bash
105+
Upgrading cluster 14/main to 15/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 14 main
112+
113+
Ver Cluster Port Status Owner Data directory Log file
114+
15 main 5432 online postgres /var/lib/postgresql/15/main /var/log/postgresql/postgresql-15-main.log
115+
116+
Sample output:
117+
Upgrading cluster 14/main to 15/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 15/main ...
122+
/usr/lib/postgresql/15/bin/initdb -D /var/lib/postgresql/15/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/15/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 14 main
179+
180+
Ver Cluster Port Status Owner Data directory Log file
181+
14 main 5433 down postgres /var/lib/postgresql/14/main /var/log/postgresql/postgresql-14-main.log
182+
Ver Cluster Port Status Owner Data directory Log file
183+
15 main 5432 online postgres /var/lib/postgresql/15/main /var/log/postgresql/postgresql-15-main.log
184+
```
185+
</details>
174186

175187
4. Start the `postgreqsl` service.
176188

177189
```{.bash data-prompt="$"}
178190
$ sudo systemctl start postgresql.service
179191
```
180192

181-
182193
5. Check the `postgresql` version.
183194

184195
* Log in as a postgres user
185-
196+
186197
```{.bash data-prompt="$"}
187198
$ sudo su postgres
188199
```
189200

190201
* Check the database version
191-
202+
192203
```{.bash data-prompt="$"}
193204
$ psql -c "SELECT version();"
194205
```
195206

207+
6. Delete the old cluster's data files.
196208
197-
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.
198211
199212
```{.bash data-prompt="$"}
200-
$ /usr/lib/postgresql/15/bin/vacuumdb --all --analyze-in-stages
213+
$ pg_dropcluster 14 main
201214
```
202215
203-
7. Delete the old cluster's data files:
204-
205-
```{.bash data-prompt="$"}
206-
$ ./delete_old_cluster.sh
207-
$ sudo rm -rf /etc/postgresql/14/main
208-
$ #Logout
209-
$ exit
210-
```
211-
212-
213-
214216
## On Red Hat Enterprise Linux and CentOS using `yum`
215217
216218
Run **all** commands as root or via **sudo**:
217219
{.power-number}
218220
219221
1. Install Percona Distribution for PostgreSQL 15 packages
220222
221-
222223
* [Install percona-release :octicons-link-external-16:](https://docs.percona.com/percona-software-repositories/installing.html)
223-
224+
224225
* Enable Percona repository:
225226
226227
```{.bash data-prompt="$"}
227228
$ sudo percona-release setup ppg-15
228229
```
229230
230-
231231
* Install Percona Distribution for PostgreSQL 15:
232232
233233
```{.bash data-prompt="$"}
@@ -263,14 +263,12 @@ Run **all** commands as root or via **sudo**:
263263
264264
4. Run the database upgrade.
265265
266-
267266
* Log in as the `postgres` user
268267
269268
```{.bash data-prompt="$"}
270269
$ sudo su postgres
271270
```
272271
273-
274272
* Check the ability to upgrade Percona Distribution for PostgreSQL from 14 to 15:
275273
276274
```{.bash data-prompt="$"}
@@ -304,7 +302,6 @@ Run **all** commands as root or via **sudo**:
304302
*Clusters are compatible*
305303
```
306304
307-
308305
* Upgrade the Percona Distribution for PostgreSQL
309306
310307
```{.bash data-prompt="$"}
@@ -319,7 +316,6 @@ Run **all** commands as root or via **sudo**:
319316
The `--link` flag creates hard links to the files on the old version cluster so you don’t need to copy data.
320317
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.
321318
322-
323319
5. Start the `postgresql` 15 service.
324320
325321
```{.bash data-prompt="$"}
@@ -332,10 +328,8 @@ Run **all** commands as root or via **sudo**:
332328
$ systemctl status postgresql-15
333329
```
334330
335-
336331
7. After the upgrade, the Optimizer statistics are not transferred to the new cluster. Run the `vaccumdb` command to analyze the new cluster:
337332
338-
339333
* Log in as the postgres user
340334
341335
```{.bash data-prompt="$"}
@@ -348,7 +342,6 @@ Run **all** commands as root or via **sudo**:
348342
$ /usr/pgsql-15/bin/vacuumdb --all --analyze-in-stages
349343
```
350344
351-
352345
8. Delete Percona Distribution for PostgreSQL 14 configuration files
353346
354347
```{.bash data-prompt="$"}

0 commit comments

Comments
 (0)