In PostgreSQL 18's pg_upgrade, how do the copy, link, clone, copy-file-range and swap modes differ in speed, disk use and the way back?
answer
- what happens to the old files
- hard links need one file system
- reflinks leave the old cluster intact
- swap is 18-only and destructive
- pg_control.old as the escape hatch
basics
~20 sCopy, the default, duplicates files and keeps the old cluster intact; link hard-links them, fast, but the old cluster dies once the new starts; clone and copy-file-range share blocks where supported; 18's swap moves directories, destroying the old cluster.
solid answer
~50 s`--copy` (default) writes a full second copy: slowest, double the disk, old cluster untouched. `--link` (`-k`) hard-links the data files: minutes and almost no disk, but both clusters then share files, so once the new cluster starts the old one is unsafe; before that, renaming `global/pg_control.old` back revives it. `--clone` uses reflinks (Linux 4.5+ on Btrfs or reflink XFS, macOS APFS): link-like speed with the old cluster untouched, and the run errors if unsupported. `--copy-file-range` (17+) uses the `copy_file_range` system call on Linux and FreeBSD, which may share blocks. `--swap` (new in 18) moves the data directories and replaces the catalog files; it can beat every other mode on clusters with many relations, but once file transfer begins the old cluster is destroyed. Link, clone and swap need old and new data directories on one file system.
code
bash · 7 lines# 3 TB e-learning cluster, 14 -> 18, both data directories on one XFS volume
/usr/lib/postgresql/18/bin/pg_upgrade \
--old-bindir=/usr/lib/postgresql/14/bin \
--new-bindir=/usr/lib/postgresql/18/bin \
--old-datadir=/srv/pg/14/main \
--new-datadir=/srv/pg/18/main \
--link --jobs=8go deeper
Remember that pg_upgrade copies files by default and that --link is the fast option which costs you the old cluster once the new one runs.
Explain hard links versus reflinks versus swap, the same-file-system rule, and when the old cluster can still be started.
Choose a mode from the file system, the outage budget and the rollback plan, and know the rsync recipe for standbys after link mode.
Weigh rollback guarantees against outage: clone or copy keep a standing fallback, link or swap trade it for minutes, which shifts the risk onto the backup.
## What pg_upgrade actually transfers `pg_upgrade` builds the new cluster's **system catalogs** by restoring a schema-only dump taken with the new version's `pg_dump --binary-upgrade`. The user data (the heap and index files of every table and index) is **not** reloaded row by row. Instead the existing relation files are handed to the new cluster, and the **transfer mode** decides how. Both clusters are stopped during the real run. The mode is the main lever on downtime, disk space and, most importantly, on whether the old cluster is still there if you need to go back. ## The five modes | Flag | How files reach the new cluster | Speed | Extra disk | Old cluster afterwards | Constraint | |---|---|---|---|---|---| | `--copy` (default) | Full copy | Slowest, grows with data | A full second copy | Untouched | None | | `--link` / `-k` | Hard links | Fast | Almost none | Unsafe once the new cluster starts | Same file system | | `--clone` | Reflinks (copy-on-write) | Near-instant | Only for later changes | Untouched | Btrfs, reflink XFS on Linux 4.5+, APFS; errors if unsupported | | `--copy-file-range` | `copy_file_range` system call | Fast where blocks are shared | Depends on file system | Untouched | Linux and FreeBSD; added in 17 | | `--swap` | Moves directories, replaces catalog files | Can be fastest with many relations | Almost none | Destroyed once transfer starts | Same file system; old cluster 10 or later; added in 18 | ## Link mode in detail A **hard link** is a second directory entry for the same file. After a link-mode run the old and new data directories literally point at the same relation files, so: - the run takes minutes even for terabytes, and needs almost no extra space; - the old and new data directories must be on the **same file system** (tablespaces and `pg_wal` may live elsewhere); otherwise `pg_upgrade` stops with a same-file-system error; - as soon as the **new** cluster starts and writes, the shared files no longer match the old catalogs, and the old cluster must be restored from backup if you need it. There is one escape hatch: when linking starts, `pg_upgrade` renames the old cluster's `global/pg_control` to `pg_control.old`. If you have **not** started the new cluster, removing that `.old` suffix lets the old cluster start again. Link mode also enables the fast way to upgrade streaming standbys: with every server stopped, `rsync --archive --delete --hard-links --size-only --no-inc-recursive` run from the primary recreates the same links on each standby instead of copying terabytes. ## Swap mode, new in 18 `--swap` moves the old cluster's data directories into the new cluster and then replaces the catalog files with the ones generated for the new version. It skips per-file linking, which is why it can win when there are many relations. The costs: - once `pg_upgrade` reports that the old cluster is no longer safe to start, it has been destructively modified, and the only way back is a backup; - it leaves many garbage files in the old cluster, so the manual recommends `--sync-method=fsync` rather than `syncfs`; - it refuses old clusters older than PostgreSQL 10. ## Clone and copy-file-range `--clone` asks the file system for a **copy-on-write** copy: the new file shares the old one's blocks until either side writes. You get link-mode speed while the old cluster stays fully usable. It works on Linux 4.5 or later with Btrfs or XFS created with reflink support, and on macOS with APFS; on anything else the run errors rather than silently copying. `--copy-file-range` (17+) uses the `copy_file_range` system call, which on some file systems shares blocks like a clone and on others performs an optimised copy. ## Choosing a mode 1. Take a backup first; link and swap modes make it your only way back. 2. If the file system supports reflinks, prefer `--clone`: fast, and the old cluster stays a fallback. 3. Otherwise use `--link` for a short outage, accepting that rollback after start-up means restoring a backup. 4. Consider `--swap` on 18 when there are a very large number of relations and the backup plan is solid. 5. Use `--copy` when you have the disk and the outage budget and want the simplest rollback. 6. Pass the chosen flag to `--check` too, and set `--jobs` to process databases and tablespaces in parallel.
- How do you upgrade the streaming standbys after a link-mode pg_upgrade without re-cloning 3 TB to each?Before starting any server, confirm with `pg_controldata` that each standby's `Latest checkpoint location` matches the old primary. Then, from the primary, run `rsync --archive --delete --hard-links --size-only --no-inc-recursive` over the old and new cluster directories to each standby; it recreates the links and copies only the small unlinked files. Replication slots that lived on the old standbys must be recreated by hand.
- Why does the manual recommend --sync-method=fsync when using --swap?Swap mode leaves many garbage files in the old cluster. With `--sync-method=syncfs`, `pg_upgrade` asks the operating system to sync the entire file systems involved, which can make the synchronisation step much longer. `fsync`, the default, opens and syncs only the files of the upgraded cluster.
Copy mode photocopies a library into a new building; link mode hangs new catalogue cards on the same shelves, so once readers start borrowing from the new catalogue the old one no longer matches; swap mode drives the shelves themselves to the new building, so the old building is left empty.
- Link mode leaves the old cluster usable as a fallback even after the new cluster has run.
- --clone silently falls back to copying on file systems without reflink support.
- Link mode works across two file systems as long as both are mounted on the same host.
- After a failed --swap, renaming global/pg_control.old back revives the old cluster.
- Copy mode needs no extra disk because pg_upgrade deletes each old file once it is copied.
Assumes PostgreSQL 18: --copy-file-range arrived in 17 and --swap in 18, so a 16 pg_upgrade offers only copy, link and clone.