1<!-- 2doc/src/sgml/ref/pgupgrade.sgml 3PostgreSQL documentation 4--> 5 6<refentry id="pgupgrade"> 7 <indexterm zone="pgupgrade"> 8 <primary>pg_upgrade</primary> 9 </indexterm> 10 11 <refmeta> 12 <refentrytitle><application>pg_upgrade</application></refentrytitle> 13 <manvolnum>1</manvolnum> 14 <refmiscinfo>Application</refmiscinfo> 15 </refmeta> 16 17 <refnamediv> 18 <refname>pg_upgrade</refname> 19 <refpurpose>upgrade a <productname>PostgreSQL</productname> server instance</refpurpose> 20 </refnamediv> 21 22 <refsynopsisdiv> 23 <cmdsynopsis> 24 <command>pg_upgrade</command> 25 <arg choice="plain"><option>-b</option></arg> 26 <arg choice="plain"><replaceable>oldbindir</replaceable></arg> 27 <arg choice="plain"><option>-B</option></arg> 28 <arg choice="plain"><replaceable>newbindir</replaceable></arg> 29 <arg choice="plain"><option>-d</option></arg> 30 <arg choice="plain"><replaceable>oldconfigdir</replaceable></arg> 31 <arg choice="plain"><option>-D</option></arg> 32 <arg choice="plain"><replaceable>newconfigdir</replaceable></arg> 33 <arg rep="repeat"><replaceable>option</replaceable></arg> 34 </cmdsynopsis> 35 </refsynopsisdiv> 36 37 <refsect1> 38 <title>Description</title> 39 40 <para> 41 <application>pg_upgrade</> (formerly called <application>pg_migrator</>) allows data 42 stored in <productname>PostgreSQL</> data files to be upgraded to a later <productname>PostgreSQL</> 43 major version without the data dump/reload typically required for 44 major version upgrades, e.g., from 9.5.8 to 9.6.4 or from 10.7 to 11.2. 45 It is not required for minor version upgrades, e.g., from 9.6.2 to 9.6.3 46 or from 10.1 to 10.2. 47 </para> 48 49 <para> 50 Major PostgreSQL releases regularly add new features that often 51 change the layout of the system tables, but the internal data storage 52 format rarely changes. <application>pg_upgrade</> uses this fact 53 to perform rapid upgrades by creating new system tables and simply 54 reusing the old user data files. If a future major release ever 55 changes the data storage format in a way that makes the old data 56 format unreadable, <application>pg_upgrade</> will not be usable 57 for such upgrades. (The community will attempt to avoid such 58 situations.) 59 </para> 60 61 <para> 62 <application>pg_upgrade</> does its best to 63 make sure the old and new clusters are binary-compatible, e.g., by 64 checking for compatible compile-time settings, including 32/64-bit 65 binaries. It is important that 66 any external modules are also binary compatible, though this cannot 67 be checked by <application>pg_upgrade</>. 68 </para> 69 70 <para> 71 pg_upgrade supports upgrades from 8.4.X and later to the current 72 major release of <productname>PostgreSQL</>, including snapshot and beta releases. 73 </para> 74 </refsect1> 75 76 <refsect1> 77 <title>Options</title> 78 79 <para> 80 <application>pg_upgrade</application> accepts the following command-line arguments: 81 82 <variablelist> 83 84 <varlistentry> 85 <term><option>-b</option> <replaceable>bindir</></term> 86 <term><option>--old-bindir=</option><replaceable>bindir</></term> 87 <listitem><para>the old PostgreSQL executable directory; 88 environment variable <envar>PGBINOLD</></para></listitem> 89 </varlistentry> 90 91 <varlistentry> 92 <term><option>-B</option> <replaceable>bindir</></term> 93 <term><option>--new-bindir=</option><replaceable>bindir</></term> 94 <listitem><para>the new PostgreSQL executable directory; 95 environment variable <envar>PGBINNEW</></para></listitem> 96 </varlistentry> 97 98 <varlistentry> 99 <term><option>-c</option></term> 100 <term><option>--check</option></term> 101 <listitem><para>check clusters only, don't change any data</para></listitem> 102 </varlistentry> 103 104 <varlistentry> 105 <term><option>-d</option> <replaceable>configdir</></term> 106 <term><option>--old-datadir=</option><replaceable>configdir</></term> 107 <listitem><para>the old database cluster configuration directory; environment 108 variable <envar>PGDATAOLD</></para></listitem> 109 </varlistentry> 110 111 <varlistentry> 112 <term><option>-D</option> <replaceable>configdir</></term> 113 <term><option>--new-datadir=</option><replaceable>configdir</>y</term> 114 <listitem><para>the new database cluster configuration directory; environment 115 variable <envar>PGDATANEW</></para></listitem> 116 </varlistentry> 117 118 <varlistentry> 119 <term><option>-j <replaceable class="parameter">njobs</replaceable></option></term> 120 <term><option>--jobs=<replaceable class="parameter">njobs</replaceable></option></term> 121 <listitem><para>number of simultaneous processes or threads to use 122 </para></listitem> 123 </varlistentry> 124 125 <varlistentry> 126 <term><option>-k</option></term> 127 <term><option>--link</option></term> 128 <listitem><para>use hard links instead of copying files to the new 129 cluster</para></listitem> 130 </varlistentry> 131 132 <varlistentry> 133 <term><option>-o</option> <replaceable class="parameter">options</replaceable></term> 134 <term><option>--old-options</option> <replaceable class="parameter">options</replaceable></term> 135 <listitem><para>options to be passed directly to the 136 old <command>postgres</command> command; multiple 137 option invocations are appended</para></listitem> 138 </varlistentry> 139 140 <varlistentry> 141 <term><option>-O</option> <replaceable class="parameter">options</replaceable></term> 142 <term><option>--new-options</option> <replaceable class="parameter">options</replaceable></term> 143 <listitem><para>options to be passed directly to the 144 new <command>postgres</command> command; multiple 145 option invocations are appended</para></listitem> 146 </varlistentry> 147 148 <varlistentry> 149 <term><option>-p</option> <replaceable>port</></term> 150 <term><option>--old-port=</option><replaceable>port</></term> 151 <listitem><para>the old cluster port number; environment 152 variable <envar>PGPORTOLD</></para></listitem> 153 </varlistentry> 154 155 <varlistentry> 156 <term><option>-P</option> <replaceable>port</></term> 157 <term><option>--new-port=</option><replaceable>port</></term> 158 <listitem><para>the new cluster port number; environment 159 variable <envar>PGPORTNEW</></para></listitem> 160 </varlistentry> 161 162 <varlistentry> 163 <term><option>-r</option></term> 164 <term><option>--retain</option></term> 165 <listitem><para>retain SQL and log files even after successful completion 166 </para></listitem> 167 </varlistentry> 168 169 <varlistentry> 170 <term><option>-U</option> <replaceable>username</></term> 171 <term><option>--username=</option><replaceable>username</></term> 172 <listitem><para>cluster's install user name; environment 173 variable <envar>PGUSER</></para></listitem> 174 </varlistentry> 175 176 <varlistentry> 177 <term><option>-v</option></term> 178 <term><option>--verbose</option></term> 179 <listitem><para>enable verbose internal logging</para></listitem> 180 </varlistentry> 181 182 <varlistentry> 183 <term><option>-V</option></term> 184 <term><option>--version</option></term> 185 <listitem><para>display version information, then exit</para></listitem> 186 </varlistentry> 187 188 <varlistentry> 189 <term><option>-?</option></term> 190 <term><option>--help</option></term> 191 <listitem><para>show help, then exit</para></listitem> 192 </varlistentry> 193 194 </variablelist> 195 </para> 196 197 </refsect1> 198 199 <refsect1> 200 <title>Usage</title> 201 202 <para> 203 These are the steps to perform an upgrade 204 with <application>pg_upgrade</application>: 205 </para> 206 207 <procedure> 208 <step performance="optional"> 209 <title>Optionally move the old cluster</title> 210 211 <para> 212 If you are using a version-specific installation directory, e.g., 213 <filename>/opt/PostgreSQL/&majorversion;</>, you do not need to move the old cluster. The 214 graphical installers all use version-specific installation directories. 215 </para> 216 217 <para> 218 If your installation directory is not version-specific, e.g., 219 <filename>/usr/local/pgsql</>, it is necessary to move the current PostgreSQL install 220 directory so it does not interfere with the new <productname>PostgreSQL</> installation. 221 Once the current <productname>PostgreSQL</> server is shut down, it is safe to rename the 222 PostgreSQL installation directory; assuming the old directory is 223 <filename>/usr/local/pgsql</>, you can do: 224 225<programlisting> 226mv /usr/local/pgsql /usr/local/pgsql.old 227</programlisting> 228 to rename the directory. 229 </para> 230 </step> 231 232 <step> 233 <title>For source installs, build the new version</title> 234 235 <para> 236 Build the new PostgreSQL source with <command>configure</> flags that are compatible 237 with the old cluster. <application>pg_upgrade</> will check <command>pg_controldata</> to make 238 sure all settings are compatible before starting the upgrade. 239 </para> 240 </step> 241 242 <step> 243 <title>Install the new PostgreSQL binaries</title> 244 245 <para> 246 Install the new server's binaries and support 247 files. <application>pg_upgrade</> is included in a default installation. 248 </para> 249 250 <para> 251 For source installs, if you wish to install the new server in a custom 252 location, use the <literal>prefix</literal> variable: 253 254<programlisting> 255make prefix=/usr/local/pgsql.new install 256</programlisting></para> 257 </step> 258 259 <step> 260 <title>Initialize the new PostgreSQL cluster</title> 261 262 <para> 263 Initialize the new cluster using <command>initdb</command>. 264 Again, use compatible <command>initdb</command> 265 flags that match the old cluster. Many 266 prebuilt installers do this step automatically. There is no need to 267 start the new cluster. 268 </para> 269 </step> 270 271 <step> 272 <title>Install extension shared object files</title> 273 274 <para> 275 Many extensions and custom modules, whether from 276 <filename>contrib</filename> or another source, use shared object 277 files (or DLLs), e.g., <filename>pgcrypto.so</filename>. If the old 278 cluster used these, shared object files matching the new server binary 279 must be installed in the new cluster, usually via operating system 280 commands. Do not load the schema definitions, e.g., <command>CREATE 281 EXTENSION pgcrypto</command>, because these will be duplicated from 282 the old cluster. If extension updates are available, 283 <application>pg_upgrade</application> will report this and create 284 a script that can be run later to update them. 285 </para> 286 </step> 287 288 <step> 289 <title>Copy custom full-text search files</title> 290 291 <para> 292 Copy any custom full text search files (dictionary, synonym, 293 thesaurus, stop words) from the old to the new cluster. 294 </para> 295 </step> 296 297 <step> 298 <title>Adjust authentication</title> 299 300 <para> 301 <command>pg_upgrade</> will connect to the old and new servers several 302 times, so you might want to set authentication to <literal>peer</> 303 in <filename>pg_hba.conf</> or use a <filename>~/.pgpass</> file 304 (see <xref linkend="libpq-pgpass">). 305 </para> 306 </step> 307 308 <step> 309 <title>Stop both servers</title> 310 311 <para> 312 Make sure both database servers are stopped using, on Unix, e.g.: 313 314<programlisting> 315pg_ctl -D /opt/PostgreSQL/9.6 stop 316pg_ctl -D /opt/PostgreSQL/&majorversion; stop 317</programlisting> 318 319 or on Windows, using the proper service names: 320 321<programlisting> 322NET STOP postgresql-9.6 323NET STOP postgresql-&majorversion; 324</programlisting> 325 </para> 326 327 <para> 328 Streaming replication and log-shipping standby servers can 329 remain running until a later step. 330 </para> 331 </step> 332 333 <step> 334 <title>Prepare for standby server upgrades</title> 335 336 <para> 337 If you are upgrading standby servers using methods outlined in section <xref 338 linkend="pgupgrade-step-replicas">, verify that the old standby 339 servers are caught up by running <application>pg_controldata</> 340 against the old primary and standby clusters. Verify that the 341 <quote>Latest checkpoint location</> values match in all clusters. 342 (There will be a mismatch if old standby servers were shut down 343 before the old primary or if the old standby servers are still running.) 344 Also, make sure <varname>wal_level</varname> is not set to 345 <literal>minimal</literal> in the <filename>postgresql.conf</filename> file on the 346 new primary cluster. 347 </para> 348 </step> 349 350 <step> 351 <title>Run <application>pg_upgrade</></title> 352 353 <para> 354 Always run the <application>pg_upgrade</> binary of the new server, not the old one. 355 <application>pg_upgrade</> requires the specification of the old and new cluster's 356 data and executable (<filename>bin</>) directories. You can also specify 357 user and port values, and whether you want the data files linked 358 instead of the default copy behavior. 359 </para> 360 361 <para> 362 If you use link mode, the upgrade will be much faster (no file 363 copying) and use less disk space, but you will not be able to access 364 your old cluster 365 once you start the new cluster after the upgrade. Link mode also 366 requires that the old and new cluster data directories be in the 367 same file system. (Tablespaces and <filename>pg_wal</> can be on 368 different file systems.) See <literal>pg_upgrade --help</> for a full 369 list of options. 370 </para> 371 372 <para> 373 The <option>--jobs</> option allows multiple CPU cores to be used 374 for copying/linking of files and to dump and reload database schemas 375 in parallel; a good place to start is the maximum of the number of 376 CPU cores and tablespaces. This option can dramatically reduce the 377 time to upgrade a multi-database server running on a multiprocessor 378 machine. 379 </para> 380 381 <para> 382 For Windows users, you must be logged into an administrative account, and 383 then start a shell as the <literal>postgres</> user and set the proper path: 384 385<programlisting> 386RUNAS /USER:postgres "CMD.EXE" 387SET PATH=%PATH%;C:\Program Files\PostgreSQL\&majorversion;\bin; 388</programlisting> 389 390 and then run <application>pg_upgrade</> with quoted directories, e.g.: 391 392<programlisting> 393pg_upgrade.exe 394 --old-datadir "C:/Program Files/PostgreSQL/9.6/data" 395 --new-datadir "C:/Program Files/PostgreSQL/&majorversion;/data" 396 --old-bindir "C:/Program Files/PostgreSQL/9.6/bin" 397 --new-bindir "C:/Program Files/PostgreSQL/&majorversion;/bin" 398</programlisting> 399 400 Once started, <command>pg_upgrade</> will verify the two clusters are compatible 401 and then do the upgrade. You can use <command>pg_upgrade --check</> 402 to perform only the checks, even if the old server is still 403 running. <command>pg_upgrade --check</> will also outline any 404 manual adjustments you will need to make after the upgrade. If you 405 are going to be using link mode, you should use the <option>--link</> 406 option with <option>--check</option> to enable link-mode-specific checks. 407 <command>pg_upgrade</> requires write permission in the current directory. 408 </para> 409 410 <para> 411 Obviously, no one should be accessing the clusters during the 412 upgrade. <application>pg_upgrade</> defaults to running servers 413 on port 50432 to avoid unintended client connections. 414 You can use the same port number for both clusters when doing an 415 upgrade because the old and new clusters will not be running at the 416 same time. However, when checking an old running server, the old 417 and new port numbers must be different. 418 </para> 419 420 <para> 421 If an error occurs while restoring the database schema, <command>pg_upgrade</> will 422 exit and you will have to revert to the old cluster as outlined in <xref linkend="pgupgrade-step-revert"> 423 below. To try <command>pg_upgrade</command> again, you will need to modify the old 424 cluster so the pg_upgrade schema restore succeeds. If the problem is a 425 <filename>contrib</filename> module, you might need to uninstall the <filename>contrib</filename> module from 426 the old cluster and install it in the new cluster after the upgrade, 427 assuming the module is not being used to store user data. 428 </para> 429 </step> 430 431 <step id="pgupgrade-step-replicas"> 432 <title>Upgrade Streaming Replication and Log-Shipping standby servers</title> 433 434 <para> 435 If you used link mode and have Streaming Replication (see <xref 436 linkend="streaming-replication">) or Log-Shipping (see <xref 437 linkend="warm-standby">) standby servers, you can follow these steps to 438 quickly upgrade them. You will not be running <application>pg_upgrade</> on 439 the standby servers, but rather <application>rsync</> on the primary. 440 Do not start any servers yet. 441 </para> 442 443 <para> 444 If you did <emphasis>not</> use link mode, do not have or do not 445 want to use <application>rsync</>, or want an easier solution, skip 446 the instructions in this section and simply recreate the standby 447 servers once <application>pg_upgrade</> completes and the new primary 448 is running. 449 </para> 450 451 <substeps> 452 453 <step> 454 <title>Install the new PostgreSQL binaries on standby servers</title> 455 456 <para> 457 Make sure the new binaries and support files are installed on all 458 standby servers. 459 </para> 460 </step> 461 462 <step> 463 <title>Make sure the new standby data directories do <emphasis>not</> exist</title> 464 465 <para> 466 Make sure the new standby data directories do <emphasis>not</> 467 exist or are empty. If <application>initdb</> was run, delete 468 the standby servers' new data directories. 469 </para> 470 </step> 471 472 <step> 473 <title>Install extension shared object files</title> 474 475 <para> 476 Install the same extension shared object files on the new standbys 477 that you installed in the new primary cluster. 478 </para> 479 </step> 480 481 <step> 482 <title>Stop standby servers</title> 483 484 <para> 485 If the standby servers are still running, stop them now using the 486 above instructions. 487 </para> 488 </step> 489 490 <step> 491 <title>Save configuration files</title> 492 493 <para> 494 Save any configuration files from the old standbys' configuration 495 directories you need to keep, e.g., <filename>postgresql.conf</filename> 496 (and any files included by it), <filename>postgresql.auto.conf</filename>, 497 <literal>recovery.conf</literal>, <literal>pg_hba.conf</literal>, 498 because these will be overwritten or removed in the next step. 499 </para> 500 </step> 501 502 <step> 503 <title>Run <application>rsync</></title> 504 505 <para> 506 When using link mode, standby servers can be quickly upgraded using 507 <application>rsync</>. To accomplish this, from a directory on 508 the primary server that is above the old and new database cluster 509 directories, run this on the <emphasis>primary</> for each standby 510 server: 511 512<programlisting> 513rsync --archive --delete --hard-links --size-only --no-inc-recursive old_cluster new_cluster remote_dir 514</programlisting> 515 516 where <option>old_cluster</> and <option>new_cluster</> are relative 517 to the current directory on the primary, and <option>remote_dir</> 518 is <emphasis>above</> the old and new cluster directories 519 on the standby. The directory structure under the specified 520 directories on the primary and standbys must match. Consult the 521 <application>rsync</> manual page for details on specifying the 522 remote directory, e.g., 523 524<programlisting> 525rsync --archive --delete --hard-links --size-only --no-inc-recursive /opt/PostgreSQL/9.5 \ 526 /opt/PostgreSQL/9.6 standby.example.com:/opt/PostgreSQL 527</programlisting> 528 529 You can verify what the command will do using 530 <application>rsync</>'s <option>--dry-run</> option. While 531 <application>rsync</> must be run on the primary for at least one 532 standby, it is possible to run <application>rsync</> on an upgraded 533 standby to upgrade other standbys, as long as the upgraded standby 534 has not been started. 535 </para> 536 537 <para> 538 What this does is to record the links created by 539 <application>pg_upgrade</>'s link mode that connect files in the 540 old and new clusters on the primary server. It then finds matching 541 files in the standby's old cluster and creates links for them in the 542 standby's new cluster. Files that were not linked on the primary 543 are copied from the primary to the standby. (They are usually 544 small.) This provides rapid standby upgrades. Unfortunately, 545 <application>rsync</> needlessly copies files associated with 546 temporary and unlogged tables because these files don't normally 547 exist on standby servers. 548 </para> 549 550 <para> 551 If you have tablespaces, you will need to run a similar 552 <application>rsync</> command for each tablespace directory, e.g.: 553 554<programlisting> 555rsync --archive --delete --hard-links --size-only --no-inc-recursive /vol1/pg_tblsp/PG_9.5_201510051 \ 556 /vol1/pg_tblsp/PG_9.6_201608131 standby.example.com:/vol1/pg_tblsp 557</programlisting> 558 559 If you have relocated <filename>pg_wal</> outside the data 560 directories, <application>rsync</> must be run on those directories 561 too. 562 </para> 563 </step> 564 565 <step> 566 <title>Configure streaming replication and log-shipping standby servers</title> 567 568 <para> 569 Configure the servers for log shipping. (You do not need to run 570 <function>pg_start_backup()</> and <function>pg_stop_backup()</> 571 or take a file system backup as the standbys are still synchronized 572 with the primary.) 573 </para> 574 </step> 575 576 </substeps> 577 578 </step> 579 580 <step> 581 <title>Restore <filename>pg_hba.conf</></title> 582 583 <para> 584 If you modified <filename>pg_hba.conf</>, restore its original settings. 585 It might also be necessary to adjust other configuration files in the new 586 cluster to match the old cluster, e.g., <filename>postgresql.conf</filename> 587 (and any files included by it), <filename>postgresql.auto.conf</filename>. 588 </para> 589 </step> 590 591 <step> 592 <title>Start the new server</title> 593 594 <para> 595 The new server can now be safely started, and then any 596 <application>rsync</>'ed standby servers. 597 </para> 598 </step> 599 600 <step> 601 <title>Post-Upgrade processing</title> 602 603 <para> 604 If any post-upgrade processing is required, pg_upgrade will issue 605 warnings as it completes. It will also generate script files that must 606 be run by the administrator. The script files will connect to each 607 database that needs post-upgrade processing. Each script should be 608 run using: 609 610<programlisting> 611psql --username=postgres --file=script.sql postgres 612</programlisting> 613 614 The scripts can be run in any order and can be deleted once they have 615 been run. 616 </para> 617 618 <caution> 619 <para> 620 In general it is unsafe to access tables referenced in rebuild scripts 621 until the rebuild scripts have run to completion; doing so could yield 622 incorrect results or poor performance. Tables not referenced in rebuild 623 scripts can be accessed immediately. 624 </para> 625 </caution> 626 </step> 627 628 <step> 629 <title>Statistics</title> 630 631 <para> 632 Because optimizer statistics are not transferred by <command>pg_upgrade</>, you will 633 be instructed to run a command to regenerate that information at the end 634 of the upgrade. You might need to set connection parameters to 635 match your new cluster. 636 </para> 637 </step> 638 639 <step> 640 <title>Delete old cluster</title> 641 642 <para> 643 Once you are satisfied with the upgrade, you can delete the old 644 cluster's data directories by running the script mentioned when 645 <command>pg_upgrade</command> completes. (Automatic deletion is not 646 possible if you have user-defined tablespaces inside the old data 647 directory.) You can also delete the old installation directories 648 (e.g., <filename>bin</>, <filename>share</>). 649 </para> 650 </step> 651 652 <step id="pgupgrade-step-revert" performance="optional"> 653 <title>Reverting to old cluster</title> 654 655 <para> 656 If, after running <command>pg_upgrade</command>, you wish to revert to the old cluster, 657 there are several options: 658 659 <itemizedlist> 660 <listitem> 661 <para> 662 If the <option>--check</option> option was used, the old cluster 663 was unmodified; it can be restarted. 664 </para> 665 </listitem> 666 667 <listitem> 668 <para> 669 If the <option>--link</option> option was <emphasis>not</emphasis> 670 used, the old cluster was unmodified; it can be restarted. 671 </para> 672 </listitem> 673 674 <listitem> 675 <para> 676 If the <option>--link</option> option was used, the data 677 files might be shared between the old and new cluster: 678 679 <itemizedlist> 680 <listitem> 681 <para> 682 If <command>pg_upgrade</command> aborted before linking started, 683 the old cluster was unmodified; it can be restarted. 684 </para> 685 </listitem> 686 687 <listitem> 688 <para> 689 If you did <emphasis>not</emphasis> start the new cluster, the old 690 cluster was unmodified except that, when linking started, a 691 <literal>.old</literal> suffix was appended to 692 <filename>$PGDATA/global/pg_control</filename>. To reuse the old 693 cluster, remove the <filename>.old</filename> suffix from 694 <filename>$PGDATA/global/pg_control</filename>; you can then restart 695 the old cluster. 696 </para> 697 </listitem> 698 699 <listitem> 700 <para> 701 If you did start the new cluster, it has written to shared files 702 and it is unsafe to use the old cluster. The old cluster will 703 need to be restored from backup in this case. 704 </para> 705 </listitem> 706 707 </itemizedlist> 708 </para> 709 </listitem> 710 </itemizedlist> 711 </para> 712 </step> 713 </procedure> 714 715 </refsect1> 716 717 <refsect1> 718 <title>Notes</title> 719 720 <para> 721 <application>pg_upgrade</> does not support upgrading of databases 722 containing these <type>reg*</> OID-referencing system data types: 723 <type>regproc</>, <type>regprocedure</>, <type>regoper</>, 724 <type>regoperator</>, <type>regconfig</>, and 725 <type>regdictionary</>. (<type>regtype</> can be upgraded.) 726 </para> 727 728 <para> 729 All failure, rebuild, and reindex cases will be reported by 730 <application>pg_upgrade</> if they affect your installation; 731 post-upgrade scripts to rebuild tables and indexes will be 732 generated automatically. If you are trying to automate the upgrade 733 of many clusters, you should find that clusters with identical database 734 schemas require the same post-upgrade steps for all cluster upgrades; 735 this is because the post-upgrade steps are based on the database 736 schemas, and not user data. 737 </para> 738 739 <para> 740 For deployment testing, create a schema-only copy of the old cluster, 741 insert dummy data, and upgrade that. 742 </para> 743 744 <para> 745 If you are upgrading a pre-<productname>PostgreSQL</> 9.2 cluster 746 that uses a configuration-file-only directory, you must pass the 747 real data directory location to <application>pg_upgrade</>, and 748 pass the configuration directory location to the server, e.g., 749 <literal>-d /real-data-directory -o '-D /configuration-directory'</>. 750 </para> 751 752 <para> 753 If using a pre-9.1 old server that is using a non-default Unix-domain 754 socket directory or a default that differs from the default of the 755 new cluster, set <envar>PGHOST</> to point to the old server's socket 756 location. (This is not relevant on Windows.) 757 </para> 758 759 <para> 760 If you want to use link mode and you do not want your old cluster 761 to be modified when the new cluster is started, make a copy of the 762 old cluster and upgrade that in link mode. To make a valid copy 763 of the old cluster, use <command>rsync</> to create a dirty 764 copy of the old cluster while the server is running, then shut down 765 the old server and run <command>rsync --checksum</> again to update the 766 copy with any changes to make it consistent. (<option>--checksum</> 767 is necessary because <command>rsync</> only has file modification-time 768 granularity of one second.) You might want to exclude some 769 files, e.g., <filename>postmaster.pid</>, as documented in <xref 770 linkend="backup-lowlevel-base-backup">. If your file system supports 771 file system snapshots or copy-on-write file copies, you can use that 772 to make a backup of the old cluster and tablespaces, though the snapshot 773 and copies must be created simultaneously or while the database server 774 is down. 775 </para> 776 777 </refsect1> 778 779 <refsect1> 780 <title>See Also</title> 781 782 <simplelist type="inline"> 783 <member><xref linkend="app-initdb"></member> 784 <member><xref linkend="app-pg-ctl"></member> 785 <member><xref linkend="app-pgdump"></member> 786 <member><xref linkend="app-postgres"></member> 787 </simplelist> 788 </refsect1> 789</refentry> 790