1<chapter id="upgrading-repmgr" xreflabel="Upgrading repmgr"> 2 <title>Upgrading repmgr</title> 3 4 <indexterm> 5 <primary>upgrading</primary> 6 </indexterm> 7 8 9 <para> 10 &repmgr; is updated regularly with minor releases (e.g. 4.0.1 to 4.0.2) 11 containing bugfixes and other minor improvements. Any substantial new 12 functionality will be included in a major release (e.g. 4.0 to 4.1). 13 </para> 14 15 <sect1 id="upgrading-repmgr-extension" xreflabel="Upgrading repmgr 4.x and later"> 16 <title>Upgrading repmgr 4.x and later</title> 17 18 <indexterm> 19 <primary>upgrading</primary> 20 <secondary>repmgr 4.x and later</secondary> 21 </indexterm> 22 <para> 23 From version 4, &repmgr; consists of three elements: 24 <itemizedlist spacing="compact" mark="bullet"> 25 26 <listitem> 27 <simpara> 28 the <application>repmgr</application> and &repmgrd; executables 29 </simpara> 30 </listitem> 31 32 <listitem> 33 <simpara> 34 the objects for the &repmgr; PostgreSQL extension (SQL files for creating/updating 35 repmgr metadata, and the extension control file) 36 </simpara> 37 </listitem> 38 39 <listitem> 40 <simpara> 41 the shared library module used by &repmgrd; which 42 is resident in the PostgreSQL backend 43 </simpara> 44 </listitem> 45 </itemizedlist> 46 </para> 47 <para> 48 With <emphasis>minor releases</emphasis>, usually changes are only made to the <application>repmgr</application> 49 and &repmgrd; executables. In this case, the upgrade is quite straightforward, 50 and is simply a case of installing the new version, and restarting &repmgrd; 51 (if running). 52 </para> 53 54 <para> 55 For <emphasis>major releases</emphasis>, the &repmgr; PostgreSQL extension will need to be updated 56 to the latest version. Additionally, if the shared library module has been updated (this is sometimes, 57 but not always the case), PostgreSQL itself will need to be restarted on each node. 58 </para> 59 <important> 60 <para> 61 Always check the <link linkend="appendix-release-notes">release notes</link> for every 62 release as they may contain upgrade instructions particular to individual versions. 63 </para> 64 </important> 65 66 <sect2 id="upgrading-minor-version" xreflabel="Upgrading a minor version release"> 67 <title>Upgrading a minor version release</title> 68 69 <indexterm> 70 <primary>upgrading</primary> 71 <secondary>minor release</secondary> 72 </indexterm> 73 74 <para> 75 The process for installing minor version upgrades is quite straightforward: 76 77 <itemizedlist spacing="compact" mark="bullet"> 78 79 <listitem> 80 <simpara> 81 install the new &repmgr; version 82 </simpara> 83 </listitem> 84 85 <listitem> 86 <simpara> 87 restart &repmgrd; on all nodes where it is running 88 </simpara> 89 </listitem> 90 91 </itemizedlist> 92 93 </para> 94 95 <note> 96 <para> 97 Some packaging systems (e.g. <link linkend="packages-debian-ubuntu">Debian/Ubuntu</link> 98 may restart &repmgrd; as part of the package upgrade process. 99 </para> 100 </note> 101 102 <para> 103 Minor version upgrades can be performed in any order on the nodes in the replication 104 cluster. 105 </para> 106 107 <para> 108 A PostgreSQL restart is <emphasis>not</emphasis> required for minor version upgrades. 109 </para> 110 111 <note> 112 <para> 113 The same &repmgr; "major version" (e.g. <literal>4.2</literal>) must be 114 installed on all nodes in the replication cluster. While it's possible to have differing 115 &repmgr; "minor versions" (e.g. <literal>4.2.1</literal>) on different nodes, 116 we strongly recommend updating all nodes to the latest minor version. 117 </para> 118 </note> 119 120 </sect2> 121 122 <sect2 id="upgrading-major-version" xreflabel="Upgrading a major version release"> 123 <title>Upgrading a major version release</title> 124 125 <indexterm> 126 <primary>upgrading</primary> 127 <secondary>major release</secondary> 128 </indexterm> 129 130 <para> 131 "major version" upgrades need to be planned more carefully, as they may include 132 changes to the &repmgr; metadata (which need to be propagated from the primary to all 133 standbys) and/or changes to the shared object file used by &repmgrd; 134 (which require a PostgreSQL restart). 135 </para> 136 <para> 137 With this in mind, 138 </para> 139 140 <para> 141 <orderedlist> 142 143 <listitem> 144 <simpara> 145 Stop &repmgrd; (if in use) on all nodes where it is running. 146 </simpara> 147 </listitem> 148 149 <listitem> 150 <simpara> 151 Disable the &repmgrd; service on all nodes where it is in use; 152 this is to prevent packages from prematurely restarting &repmgrd;. 153 </simpara> 154 </listitem> 155 156 <listitem> 157 <simpara> 158 Install the updated package (or compile the updated source) on all nodes. 159 </simpara> 160 </listitem> 161 162 <listitem> 163 <para> 164 If running a <literal>systemd</literal>-based Linux distribution, execute (as <literal>root</literal>, 165 or with appropriate <literal>sudo</literal> permissions): 166 <programlisting> 167systemctl daemon-reload</programlisting> 168 </para> 169 </listitem> 170 171 <listitem> 172 <simpara> 173 If the &repmgr; shared library module has been updated (check the <link linkend="appendix-release-notes">release notes</link>!), 174 restart PostgreSQL, then &repmgrd; (if in use) on each node, 175 The order in which this is applied to individual nodes is not critical, 176 and it's also fine to restart PostgreSQL on all nodes first before starting &repmgrd;. 177 </simpara> 178 <simpara> 179 Note that if the upgrade requires a PostgreSQL restart, &repmgrd; 180 will only function correctly once all nodes have been restarted. 181 </simpara> 182 </listitem> 183 184 <listitem> 185 <para> 186 On the primary node, execute 187 <programlisting> 188ALTER EXTENSION repmgr UPDATE</programlisting> 189 in the database where &repmgr; is installed. 190 </para> 191 </listitem> 192 193 <listitem> 194 <simpara> 195 Reenable the &repmgrd; service on all nodes where it is in use, and 196 ensure it is running. 197 </simpara> 198 </listitem> 199 200 </orderedlist> 201 </para> 202 <tip> 203 <para> 204 If the &repmgr; upgrade requires a PostgreSQL restart, combine the &repmgr; upgrade 205 with a PostgreSQL minor version upgrade, which will require a restart in any case. 206 </para> 207 <para> 208 New PostgreSQL minor versions are usually released every couple of months; 209 see the <ulink url="https://www.postgresql.org/developer/roadmap/">Roadmap</ulink> 210 for the current schedule. 211 </para> 212 </tip> 213 </sect2> 214 215 <sect2 id="upgrading-check-repmgrd" xreflabel="Checking repmgrd status after an upgrade"> 216 <title>Checking repmgrd status after an upgrade</title> 217 218 <indexterm> 219 <primary>upgrading</primary> 220 <secondary>checking repmgrd status</secondary> 221 </indexterm> 222 <para> 223 From <link linkend="release-4.2">repmgr 4.2</link>, once the upgrade is complete, execute the 224 <command><link linkend="repmgr-service-status">repmgr service status</link></command> 225 (&repmgr; 4.2 - 4.4: <command><link linkend="repmgr-service-status">repmgr daemon status</link></command>) 226 command (on any node) to show an overview of the status of &repmgrd; on all nodes. 227 </para> 228 </sect2> 229 </sect1> 230 231 <sect1 id="upgrading-and-pg-upgrade" xreflabel="pg_upgrade and repmgr"> 232 <title>pg_upgrade and repmgr</title> 233 234 <indexterm> 235 <primary>upgrading</primary> 236 <secondary>pg_upgrade</secondary> 237 </indexterm> 238 <indexterm> 239 <primary>pg_upgrade</primary> 240 </indexterm> 241 242 <para> 243 <application>pg_upgrade</application> requires that if any functions are 244 dependent on a shared library, this library must be present in both 245 the old and new installations before <application>pg_upgrade</application> 246 can be executed. 247 </para> 248 <para> 249 To minimize the risk of any upgrade issues (particularly if an upgrade to 250 a new major &repmgr; version is involved), we recommend upgrading 251 &repmgr; on the old server <emphasis>before</emphasis> running 252 <application>pg_upgrade</application> to ensure that old and new 253 versions are the same. 254 </para> 255 <note> 256 <simpara> 257 This issue applies to any PostgreSQL extension which has 258 dependencies on a shared library. 259 </simpara> 260 </note> 261 <para> 262 For further details please see the <ulink url="https://www.postgresql.org/docs/current/pgupgrade.html">pg_upgrade documentation</ulink>. 263 </para> 264 <para> 265 If replication slots are in use, bear in mind these will <emphasis>not</emphasis> 266 be recreated by <application>pg_upgrade</application>. These will need to 267 be recreated manually. 268 </para> 269 <tip> 270 <para> 271 Use <command><link linkend="repmgr-node-check">repmgr node check</link></command> 272 to determine which replication slots need to be recreated. 273 </para> 274 </tip> 275 276 <sect2 id="upgrading-pg-upgrade-standby" xreflabel="pg_upgrade and upgrading standbys"> 277 <title>Upgrading standbys with pg_upgrade and rsync</title> 278 <para> 279 If you are intending to upgrade a standby using the <command>rsync</command> method described 280 in the <ulink url="https://www.postgresql.org/docs/current/pgupgrade.html#PGUPGRADE-STEP-REPLICAS">pg_upgrade documentation</ulink>, 281 you <emphasis>must</emphasis> ensure the standby's replication configuration is present and correct 282 before starting the standby. 283 </para> 284 <para> 285 Use <link linkend="repmgr-standby-clone">repmgr standby clone --replication-conf-only</link> to generate 286 the correct replication configuration. 287 </para> 288 289 <tip> 290 <para> 291 If upgrading from PostgreSQL 11 or earlier, be sure to delete <filename>recovery.conf</filename>, if present, 292 otherwise PostgreSQL will refuse to start. 293 </para> 294 </tip> 295 296 </sect2> 297 298 299 </sect1> 300 301 302 <sect1 id="upgrading-from-repmgr-3" xreflabel="Upgrading from repmgr 3.x"> 303 <title>Upgrading from repmgr 3.x</title> 304 305 <indexterm> 306 <primary>upgrading</primary> 307 <secondary>from repmgr 3.x</secondary> 308 </indexterm> 309 310 <para> 311 The upgrade process consists of two steps: 312 <orderedlist> 313 <listitem> 314 <simpara> 315 converting the <filename>repmgr.conf</filename> configuration files 316 </simpara> 317 </listitem> 318 <listitem> 319 <simpara> 320 upgrading the repmgr schema using <command>CREATE EXTENSION</command> (PostgreSQL 12 and earlier) 321 </simpara> 322 </listitem> 323 </orderedlist> 324 </para> 325 <para> 326 A script is provided to assist with converting <filename>repmgr.conf</filename>. 327 </para> 328 <para> 329 The schema upgrade (which converts the &repmgr; metadata into 330 a packaged PostgreSQL extension) is normally carried out 331 automatically when the &repmgr; extension is created. 332 </para> 333 <para> 334 The shared library has been renamed from <literal>repmgr_funcs</literal> to 335 <literal>repmgr</literal> - if it's set in <varname>shared_preload_libraries</varname> 336 in <filename>postgresql.conf</filename> it will need to be updated to the new name: 337 <programlisting> 338 shared_preload_libraries = 'repmgr'</programlisting> 339 </para> 340 341 <sect2 id="converting-repmgr-conf"> 342 <title>Converting repmgr.conf configuration files</title> 343 <para> 344 With a completely new repmgr version, we've taken the opportunity 345 to rename some configuration items for 346 clarity and consistency, both between the configuration file and 347 the column names in <structname>repmgr.nodes</structname> 348 (e.g. <varname>node</varname> to <varname>node_id</varname>), and 349 also for consistency with PostgreSQL naming conventions 350 (e.g. <varname>loglevel</varname> to <varname>log_level</varname>). 351 </para> 352 <para> 353 Other configuration items have been changed to command line options, 354 and vice-versa, e.g. to avoid hard-coding items such as a a node's 355 upstream ID, which might change over time. 356 </para> 357 <para> 358 &repmgr; will issue a warning about deprecated/altered options. 359 </para> 360 <sect3> 361 <title>Changed parameters in "repmgr.conf"</title> 362 <para> 363 Following parameters have been added: 364 <itemizedlist spacing="compact" mark="bullet"> 365 <listitem> 366 <simpara><varname>data_directory</varname>: this is mandatory and must 367 contain the path to the node's data directory</simpara> 368 </listitem> 369 <listitem> 370 <simpara><varname>monitoring_history</varname>: this replaces the 371 &repmgrd; command line option 372 <literal>--monitoring-history</literal></simpara> 373 </listitem> 374 </itemizedlist> 375 </para> 376 <para> 377 Following parameters have been renamed: 378 </para> 379 <table tocentry="1" id="repmgr3-repmgr4-renamed-parameters"> 380 <title>Parameters renamed in repmgr4</title> 381 <tgroup cols="2"> 382 <thead> 383 <row> 384 <entry>repmgr3</entry> 385 <entry>repmgr4</entry> 386 </row> 387 </thead> 388 <tbody> 389 <row> 390 <entry><varname>node</varname></entry> 391 <entry><varname>node_id</varname></entry> 392 </row> 393 <row> 394 <entry><varname>loglevel</varname></entry> 395 <entry><varname>log_level</varname></entry> 396 </row> 397 <row> 398 <entry><varname>logfacility</varname></entry> 399 <entry><varname>log_facility</varname></entry> 400 </row> 401 <row> 402 <entry><varname>logfile</varname></entry> 403 <entry><varname>log_file</varname></entry> 404 </row> 405 <row> 406 <entry><varname>barman_server</varname></entry> 407 <entry><varname>barman_host</varname></entry> 408 </row> 409 <row> 410 <entry><varname>master_reponse_timeout</varname></entry> 411 <entry><varname>async_query_timeout</varname></entry> 412 </row> 413 </tbody> 414 </tgroup> 415 </table> 416 <note> 417 <para> 418 From &repmgr; 4, <literal>barman_server</literal> refers 419 to the server configured in Barman (in &repmgr; 3, the deprecated 420 <literal>cluster</literal> parameter was used for this); 421 the physical Barman hostname is configured with 422 <literal>barman_host</literal> (see <xref linkend="cloning-from-barman-prerequisites"/> 423 for details). 424 </para> 425 </note> 426 <para> 427 Following parameters have been removed: 428 <itemizedlist spacing="compact" mark="bullet"> 429 <listitem> 430 <simpara><varname>cluster</varname>: is no longer required and will 431 be ignored.</simpara> 432 </listitem> 433 <listitem> 434 <simpara><varname>upstream_node</varname>: is replaced by the 435 command-line parameter <literal>--upstream-node-id</literal></simpara> 436 </listitem> 437 </itemizedlist> 438 </para> 439 </sect3> 440 <sect3> 441 <title>Conversion script</title> 442 <para> 443 To assist with conversion of <filename>repmgr.conf</filename> files, a Perl script 444 is provided in <filename>contrib/convert-config.pl</filename>. 445 Use like this: 446 <programlisting> 447 $ ./convert-config.pl /etc/repmgr.conf 448 node_id=2 449 node_name='node2' 450 conninfo='host=node2 dbname=repmgr user=repmgr connect_timeout=2' 451 pg_ctl_options='-l /var/log/postgres/startup.log' 452 rsync_options='--exclude=postgresql.local.conf --archive' 453 log_level='INFO' 454 pg_basebackup_options='--no-slot' 455 data_directory=''</programlisting> 456 </para> 457 <para> 458 The converted file is printed to <literal>STDOUT</literal> and the original file is not 459 changed. 460 </para> 461 <para> 462 Please note that the the conversion script will add an empty 463 placeholder parameter for <varname>data_directory</varname>, which 464 is a required parameter from &repmgr; 4. This must be manually modified to contain 465 the correct data directory. 466 </para> 467 </sect3> 468 </sect2> 469 <sect2> 470 <title>Upgrading the repmgr schema (PostgreSQL 12 and earlier)</title> 471 <para> 472 Ensure &repmgrd; is not running, or any cron jobs which execute the 473 <command>repmgr</command> binary. 474 </para> 475 <para> 476 Install the latest &repmgr; package; any <literal>repmgr 3.x</literal> packages 477 should be uninstalled (if not automatically uninstalled already by your packaging system). 478 </para> 479 <sect3> 480 <title>Upgrading from repmgr 3.1.1 or earlier</title> 481 <tip> 482 <simpara> 483 If you don't care about any data from the existing &repmgr; installation, 484 (e.g. the contents of the <structname>events</structname> and <structname>monitoring</structname> 485 tables), the follwing steps can be skipped; proceed to <xref linkend="upgrade-reregister-nodes"/>. 486 </simpara> 487 </tip> 488 489 <para> 490 If your repmgr version is 3.1.1 or earlier, you will need to update 491 the schema to the latest version in the 3.x series (3.3.2) before 492 converting the installation to repmgr 4. 493 </para> 494 <para> 495 To do this, apply the following upgrade scripts as appropriate for 496 your current version: 497 <itemizedlist spacing="compact" mark="bullet"> 498 <listitem> 499 <simpara> 500 <ulink url="https://raw.githubusercontent.com/2ndQuadrant/repmgr/REL3_3_STABLE/sql/repmgr3.0_repmgr3.1.sql">repmgr3.0_repmgr3.1.sql</ulink></simpara> 501 </listitem> 502 <listitem> 503 <simpara><ulink url="https://raw.githubusercontent.com/2ndQuadrant/repmgr/REL3_3_STABLE/sql/repmgr3.1.1_repmgr3.1.2.sql">repmgr3.1.1_repmgr3.1.2.sql</ulink></simpara> 504 </listitem> 505 </itemizedlist> 506 </para> 507 <para> 508 For more details see the 509 <ulink url="https://repmgr.org/release-notes-3.3.2.html#upgrading">repmgr 3 upgrade notes</ulink>. 510 </para> 511 </sect3> 512 <sect3> 513 <title>Manually create the repmgr extension</title> 514 <para> 515 In the database used by the existing &repmgr; installation, execute: 516 <programlisting> 517 CREATE EXTENSION repmgr FROM unpackaged</programlisting> 518 </para> 519 520 <para> 521 This will move and convert all objects from the existing schema 522 into the new, standard <literal>repmgr</literal> schema. 523 </para> 524 <note> 525 <simpara>There must be only one schema matching <literal>repmgr_%</literal> in the 526 database, otherwise this step may not work. 527 </simpara> 528 </note> 529 </sect3> 530 </sect2> 531 532 <sect2> 533 <title>Upgrading the repmgr schema (PostgreSQL 13 and later)</title> 534 <para> 535 Beginning with PostgreSQL 13, the <command>CREATE EXTENSION ... FROM unpackaged</command> 536 syntax is no longer available. In the unlikely event you have ended up with an 537 installation running PostgreSQL 13 or later and containing the legacy &repmgr; 538 schema, there is no convenient way of upgrading this; instead you'll just need 539 to re-register the nodes as detailed in <link linkend="upgrade-reregister-nodes">the following section</link>, 540 which will create the &repmgr; extension automatically. 541 </para> 542 <para> 543 Any historical data you wish to retain (e.g. the contents of the <structname>events</structname> 544 and <structname>monitoring</structname> tables) will need to be exported manually. 545 </para> 546 </sect2> 547 <sect2 id="upgrade-reregister-nodes"> 548 <title>Re-register each node</title> 549 <para> 550 This is necessary to update the <literal>repmgr</literal> metadata with some additional items. 551 </para> 552 <para> 553 On the primary node, execute e.g. 554 <programlisting> 555 repmgr primary register -f /etc/repmgr.conf --force</programlisting> 556 </para> 557 <para> 558 If not already present (e.g. after executing <command>CREATE EXTENSION repmgr FROM unpackaged</command>), 559 the &repmgr; extension will be automatically created by <command>repmgr primary register</command>. 560 </para> 561 <para> 562 On each standby node, execute e.g. 563 <programlisting> 564 repmgr standby register -f /etc/repmgr.conf --force</programlisting> 565 </para> 566 <para> 567 Check the data is updated as expected by examining the <structname>repmgr.nodes</structname> 568 table; restart &repmgrd; if required. 569 </para> 570 <para> 571 The original <literal>repmgr_$cluster</literal> schema can be dropped at any time. 572 </para> 573 574 </sect2> 575 576 <sect2 id="upgrade-drop-repmgr-cluster-schema"> 577 <title>Drop the legacy repmgr schema</title> 578 <para> 579 Once the cluster has been registered with the current &repmgr; version, the legacy 580 <literal>repmgr_$cluster</literal> schema can be dropped at any time with: 581<programlisting> 582 DROP SCHEMA repmgr_$cluster CASCADE</programlisting> 583 (substitute <literal>$cluster</literal> with the value of the <varname>clustername</varname> 584 variable used in &repmgr; 3.x). 585 </para> 586 </sect2> 587 </sect1> 588 589</chapter> 590