From e974a184c6f5106ba50988697caaea2704719299 Mon Sep 17 00:00:00 2001
From: jbranchaud <jbranchaud@gmail.com>
Date: Thu, 25 Apr 2024 20:25:48 -0500
Subject: [PATCH] Add Check If Clusters Are Upgrade Compatible as a Postgres
 TIL

---
 README.md                                     |  3 +-
 ...heck-if-clusters-are-upgrade-compatible.md | 42 +++++++++++++++++++
 2 files changed, 44 insertions(+), 1 deletion(-)
 create mode 100644 postgres/check-if-clusters-are-upgrade-compatible.md

diff --git a/README.md b/README.md
index 3e63163..322b2c9 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@ pairing with smart people at Hashrocket.
 
 For a steady stream of TILs, [sign up for my newsletter](https://crafty-builder-6996.ck.page/e169c61186).
 
-_1419 TILs and counting..._
+_1420 TILs and counting..._
 
 ---
 
@@ -672,6 +672,7 @@ _1419 TILs and counting..._
 - [Capitalize All The Words](postgres/capitalize-all-the-words.md)
 - [Change The Current Directory For psql](postgres/change-the-current-directory-for-psql.md)
 - [Change The Owner Of A Sequence](postgres/change-the-owner-of-a-sequence.md)
+- [Check If Clusters Are Upgrade Compatible](postgres/check-if-clusters-are-upgrade-compatible.md)
 - [Check If The Local Server Is Running](postgres/check-if-the-local-server-is-running.md)
 - [Check If User Role Exists For Database](postgres/check-if-user-role-exists-for-database.md)
 - [Check Table For Any Oprhaned Records](postgres/check-table-for-any-orphaned-records.md)
diff --git a/postgres/check-if-clusters-are-upgrade-compatible.md b/postgres/check-if-clusters-are-upgrade-compatible.md
new file mode 100644
index 0000000..fed3248
--- /dev/null
+++ b/postgres/check-if-clusters-are-upgrade-compatible.md
@@ -0,0 +1,42 @@
+# Check If Clusters Are Upgrade Compatible
+
+One of the ways to upgrade a PostgreSQL database from one server version to
+another is to use the built-in `pg_upgrade` command. This can be faster and
+require fewer manual steps than something like a `pg_dump` and `pg_restore`.
+
+However, before you run the `pg_upgrade` command for real, you should check
+that the target database is compatible with the current database. To do this,
+write your `pg_update` command with all the flags you need and then tack on
+`--check` at the end. This does a dry-run reporting the results of a series of
+consistency checks.
+
+Here is what a successful _check_ looks like:
+
+```bash
+$ /usr/local/opt/postgresql@13/bin/pg_upgrade \
+  --old-bindir $HOME/.asdf/installs/postgres/12.3/bin \
+  --new-bindir /usr/local/opt/postgresql@13/bin \
+  --old-datadir $HOME/.asdf/installs/postgres/12.3/data \
+  --new-datadir ./postgres/data \
+  --check
+
+Performing Consistency Checks
+-----------------------------
+Checking cluster versions                                   ok
+Checking database user is the install user                  ok
+Checking database connection settings                       ok
+Checking for prepared transactions                          ok
+Checking for system-defined composite types in user tables  ok
+Checking for reg* data types in user tables                 ok
+Checking for contrib/isn with bigint-passing mismatch       ok
+Checking for presence of required libraries                 ok
+Checking database user is the install user                  ok
+Checking for prepared transactions                          ok
+Checking for new cluster tablespace directories             ok
+
+*Clusters are compatible*
+```
+
+If there is an issue, such as mismatched collation settings, the output will
+report the issue. You'll have to decide how to resolve those on a case-by-case
+basis.