Question: Upgrades
Is pg_upgrade --link safe?
Answered in the first paragraph. Last updated .
Safe in the sense that it does not corrupt anything, and unsafe in the sense that it takes away the rollback. Link mode hard-links the data files into the new cluster instead of copying them, so both clusters point at the same bytes. The documentation is blunt about the consequence: once you start the new cluster, you cannot go back to the old one. What you gain is an upgrade measured in minutes rather than hours.
What you are actually trading
Speed and space. Nothing is copied, so the time no longer scales with the size of the database and the filesystem does not need room for a second copy. On a cluster of any size that is the difference between a short maintenance window and an all-night one.
The constraint is that both data directories must live on the same filesystem, which rules the mode out whenever the upgrade is also a move to new storage.
The rollback exists only until the new cluster is first started. Before that point the old one can be brought back by undoing the marker the tool leaves behind. After it, the only route back is a restore from backup, which makes taking and verifying that backup a precondition rather than good practice.
The option most people should take instead
If the filesystem supports cloning, that mode gives near-instant copies that share physical blocks while leaving the old cluster completely intact and startable. It is the speed of link mode without the one-way door, and it is available on the common modern filesystems. There is a third variant using an efficient copy call that behaves similarly on some filesystems and falls back to a real copy on others.
In every mode the same two follow-ups apply. Statistics need attention, and what that means depends on the version, which is do I need to run ANALYZE after pg_upgrade. Extensions must be present and compatible before the tool will proceed at all, covered in pg_upgrade and extensions.
One last thing to be clear about, because the mode’s name invites the confusion: none of this changes the durability of the data itself. The new cluster writes its own write-ahead log from the moment it starts, and the files it shares with the old cluster are ordinary files. The risk in link mode is entirely about what you can undo, not about what you can lose to a crash.