Skip to content

Commit c4398ad

Browse files
AndriciucAndriciuc
authored
PG-1567-Release-notes-13.21 (#796)
* initial commit commit for 13.21 RN Q2 PG * updated major upgrade and RN Updated the variables with a date awaiting release, updated major upgrade as per pr-1599 and updated RN to include the changes in docs as highlights. * updated tarball and rn tarball updated based on Naeem * Update variables.yml added release date
1 parent f26040c commit c4398ad

8 files changed

Lines changed: 179 additions & 127 deletions

File tree

‎.github/workflows/main.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ jobs:
4444
- name: Deploy docs
4545
run: |
4646
mike deploy 13 -b publish -p
47-
mike retitle 13 "13.20" -b publish -p
47+
mike retitle 13 "13.21" -b publish -p
4848
4949
# - name: Install Node.js 14.x
5050
# uses: percona-platform/setup-node@v2

‎docs/major-upgrade.md‎

Lines changed: 115 additions & 120 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 12.18 to 12.19).
9+
* Then, perform the major upgrade to your desired version (e.g., from 12.19 to 13.21).
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 12.19 to 12.19).
15-
* Then, perform the major upgrade to your desired version (e.g., from 12.19 to 13.15).
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"
@@ -31,26 +29,19 @@ Similar to installing, we recommend you to upgrade Percona Distribution for Post
3129

3230
The general in-place upgrade flow for Percona Distribution for PostgreSQL is the following:
3331

34-
3532
1. Install Percona Distribution for PostgreSQL 13 packages.
3633

37-
3834
2. Stop the PostgreSQL service.
3935

40-
4136
3. Check the upgrade without modifying the data.
4237

43-
4438
4. Upgrade Percona Distribution for PostgreSQL.
4539

46-
4740
5. Start PostgreSQL service.
4841

49-
5042
6. Execute the **analyze_new_cluster.sh** script to generate statistics
5143
so the system is usable.
5244

53-
5445
7. Delete old packages and configuration files.
5546

5647
The exact steps may differ depending on the package manager of your operating system.
@@ -62,16 +53,18 @@ Run **all** commands as root or via **sudo**:
6253

6354
1. Install Percona Distribution for PostgreSQL 13 packages.
6455

56+
!!! note
57+
When installing version 13, if prompted via a pop-up to upgrade to the latest available version, select **No**.
6558

66-
* [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)
67-
68-
* Enable Percona repository:
59+
* [Install percona-release](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)
60+
61+
* Enable Percona repository
6962

7063
```{.bash data-prompt="$"}
7164
$ sudo percona-release setup ppg-13
7265
```
7366

74-
* Install Percona Distribution for PostgreSQL 13 package:
67+
* Install Percona Distribution for PostgreSQL 13 package
7568

7669
```{.bash data-prompt="$"}
7770
$ sudo apt install percona-postgresql-13
@@ -85,131 +78,141 @@ Run **all** commands as root or via **sudo**:
8578

8679
This stops both Percona Distribution for PostgreSQL 12 and 13.
8780

88-
8981
3. Run the database upgrade.
9082

83+
* Log in as the `postgres` user
9184

92-
* Log in as the `postgres` user.
93-
94-
```{.bash data-prompt="$"}
95-
$ sudo su postgres
96-
```
97-
98-
99-
* Change the current directory to the `tmp` directory where logs and some scripts will be recorded:
100-
101-
```{.bash data-prompt="$"}
102-
$ cd tmp/
103-
```
104-
105-
106-
* Check the ability to upgrade Percona Distribution for PostgreSQL from 12 to 13:
85+
```{.bash data-prompt="$"}
86+
$ sudo su postgres
87+
```
10788

108-
```{.bash data-prompt="$"}
109-
$ /usr/lib/postgresql/13/bin/pg_upgrade \
110-
--old-datadir=/var/lib/postgresql/12/main \
111-
--new-datadir=/var/lib/postgresql/13/main \
112-
--old-bindir=/usr/lib/postgresql/12/bin \
113-
--new-bindir=/usr/lib/postgresql/13/bin \
114-
--old-options '-c config_file=/etc/postgresql/12/main/postgresql.conf' \
115-
--new-options '-c config_file=/etc/postgresql/13/main/postgresql.conf' \
116-
--check
117-
```
89+
* Check if you can upgrade Percona Distribution for PostgreSQL from 12 to 13
11890

119-
The `--check` flag here instructs `pg_upgrade` to only check the upgrade without changing any data.
120-
121-
**Sample output**
122-
123-
```{.text .no-copy}
124-
Performing Consistency Checks
125-
-----------------------------
126-
Checking cluster versions ok
127-
Checking database user is the install user ok
128-
Checking database connection settings ok
129-
Checking for prepared transactions ok
130-
Checking for reg* data types in user tables ok
131-
Checking for contrib/isn with bigint-passing mismatch ok
132-
Checking for tables WITH OIDS ok
133-
Checking for invalid "sql_identifier" user columns ok
134-
Checking for presence of required libraries ok
135-
Checking database user is the install user ok
136-
Checking for prepared transactions ok
137-
138-
*Clusters are compatible*
139-
```
91+
```bash
92+
$ pg_upgradecluster 12 main --check
93+
# Sample output: pg_upgradecluster pre-upgrade checks ok
94+
```
14095

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

14298
* Upgrade the Percona Distribution for PostgreSQL
14399

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

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

178189
4. Start the `postgreqsl` service.
179190

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

184-
185195
5. Check the `postgresql` version.
186196

187197
* Log in as a postgres user
188-
198+
189199
```{.bash data-prompt="$"}
190200
$ sudo su postgres
191201
```
192202

193203
* Check the database version
194-
204+
195205
```{.bash data-prompt="$"}
196206
$ psql -c "SELECT version();"
197207
```
198208

209+
6. Delete the old cluster's data files.
199210
200-
6. After the upgrade, the Optimizer statistics are not transferred to the new cluster. Run the `vaccumdb` command to analyze the new cluster:
211+
!!! note
212+
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.
201213
202214
```{.bash data-prompt="$"}
203-
$ /usr/lib/postgresql/13/bin/vacuumdb --all --analyze-in-stages
204-
```
205-
206-
7. Delete the old cluster's data files:
207-
208-
```{.bash data-prompt="$"}
209-
$ ./delete_old_cluster.sh
210-
$ sudo rm -rf /etc/postgresql/13/main
211-
$ #Logout
212-
$ exit
215+
$ pg_dropcluster 12 main
213216
```
214217
215218
## On Red Hat Enterprise Linux and derivatives using `yum`
@@ -219,16 +222,14 @@ Run **all** commands as root or via **sudo**:
219222
220223
1. Install Percona Distribution for PostgreSQL 13 packages
221224
222-
223225
* [Install percona-release :octicons-link-external-16:](https://docs.percona.com/percona-software-repositories/installing.html)
224-
226+
225227
* Enable Percona repository:
226228
227229
```{.bash data-prompt="$"}
228230
$ sudo percona-release setup ppg-13
229231
```
230232
231-
232233
* Install Percona Distribution for PostgreSQL 13:
233234
234235
```{.bash data-prompt="$"}
@@ -264,7 +265,6 @@ Run **all** commands as root or via **sudo**:
264265
265266
4. Run the database upgrade.
266267
267-
268268
* Log in as the `postgres` user
269269
270270
```{.bash data-prompt="$"}
@@ -304,7 +304,6 @@ Run **all** commands as root or via **sudo**:
304304
*Clusters are compatible*
305305
```
306306
307-
308307
* Upgrade the Percona Distribution for PostgreSQL
309308
310309
```{.bash data-prompt="$"}
@@ -319,7 +318,6 @@ Run **all** commands as root or via **sudo**:
319318
The `--link` flag creates hard links to the files on the old version cluster so you don’t need to copy data.
320319
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.
321320
322-
323321
5. Start the `postgresql` 13 service.
324322
325323
```{.bash data-prompt="$"}
@@ -332,10 +330,8 @@ Run **all** commands as root or via **sudo**:
332330
$ systemctl status postgresql-13
333331
```
334332
335-
336333
7. After the upgrade, the Optimizer statistics are not transferred to the new cluster. Run the `vaccumdb` command to analyze the new cluster:
337334
338-
339335
* Log in as the postgres user
340336
341337
```{.bash data-prompt="$"}
@@ -348,7 +344,6 @@ Run **all** commands as root or via **sudo**:
348344
$ /usr/pgsql-13/bin/vacuumdb --all --analyze-in-stages
349345
```
350346
351-
352347
8. Delete Percona Distribution for PostgreSQL 12 configuration files
353348
354349
```{.bash data-prompt="$"}

0 commit comments

Comments
 (0)