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