Digest Release Notes into an Upgrade Risk Register

Tier: Foundation · Workflow area: Schema & Change Management · ~25 minutes

The information needed to de-risk an upgrade is public, complete and unread — thousands of lines of release notes, behavior changes and deprecations between your version and the target. This playbook turns that corpus plus an honest inventory of what your estate actually uses into a prioritized risk register with a test-focus list. The trick is the inventory: release notes only matter where they intersect what you run.

When to use

• Any major-version upgradePostgres 14→16, SQL Server 2019→2022, MySQL 5.7→8.0-class jumps where behavior changes hide among thousands of note lines.
• Patch triage across a fleetquarterly CU/PSU decisions where the question is "does anything in this patch touch what we run?" (pairs with pb-24's CVE view).
• Extension and driver upgradespgvector, PostGIS, JDBC/ODBC majors change behavior too, and their notes are even less read.

When NOT to use

• As the staging-test replacementthe register tells staging what to test hardest; it never replaces the full regression run.
• When you cannot build the feature inventorya risk register against a guessed inventory produces confident blind spots. Extract the inventory first; it is queryable.
• For same-day emergency patchinga critical CVE with active exploitation ships on the vendor's mitigation guidance; the register is for planned change.

The recipe

1. 1.

   Extract your feature inventory — from the databases, not from memory. What you actually use is queryable:

   Copy

   -- Extensions and versions in each database
   SELECT extname, extversion FROM pg_extension;
   
   -- Non-default settings that upgrades love to rename or re-default
   SELECT name, setting FROM pg_settings
   WHERE source NOT IN ('default', 'override');
   
   -- Features visible in the catalog: partitioning, replication,
   -- FDWs, custom types, procedural languages
   SELECT count(*) FILTER (WHERE relkind = 'p') AS partitioned_tables,
          (SELECT count(*) FROM pg_subscription)   AS log_rep_subs,
          (SELECT count(*) FROM pg_foreign_table)  AS foreign_tables,
          (SELECT count(*) FROM pg_language WHERE lanname NOT IN
             ('internal','c','sql'))               AS proc_languages
   FROM pg_class;
   

   Add the outside-the-catalog facts: client driver versions, connection poolers, backup tooling, monitoring agents, and any SQL constructs your apps are known to lean on (from pg_stat_statements exports).

2. 2.

   Feed notes plus inventory, demand traceability.

   Copy

   You are planning a PostgreSQL 14.11 -> 16.4 upgrade. Below:
   (a) our feature inventory (extensions, settings, features, drivers),
   (b) the release notes for 15.0 and 16.0 (and the incompatibilities
   sections of each), (c) our top-30 query digest.
   
   Build an UPGRADE RISK REGISTER. For each item:
   - risk_id, WHAT changes (quote or cite the exact release-note line),
   - WHERE it intersects our inventory (name the extension/setting/query),
   - IMPACT: breaks / behavior-change / performance-change / removal,
   - SEVERITY: high / medium / low for US specifically,
   - TEST: the specific staging test that would surface it.
   Then: DEPRECATIONS to fix before upgrading, and a NON-ISSUES list —
   scary-sounding notes that do NOT apply to us, with why.
   Do not include generic upgrade advice. Every row must cite a note line
   and an inventory line.
   

   The two-sided citation rule ("a note line AND an inventory line") is what keeps the register grounded — it makes hallucinated risks visible, because they cannot cite both sides.

3. 3.

   Verify the high-severity rows against the source. For every row marked high, find the cited line in the actual release notes and confirm it says what the register claims. LLMs summarizing release notes occasionally invert a change ("X is now the default" vs "X is no longer the default"). A verified high row looks like:

   Copy

   R-03 | HIGH | public schema no longer world-writable (PG15 notes,
   "Remove PUBLIC creation permission on the public schema")
   Intersects: legacy ETL role writes temp tables to public (inventory
   line 14; confirmed in pg_stat_statements digest)
   Test: run ETL nightly job against PG16 staging under the unchanged
   role; expect permission failure until GRANT CREATE applied.
   VERIFIED against notes ✓
   

4. 4.

   Turn the register into the staging test plan. Each high and medium row's TEST column becomes a staging task with an owner. Run the plan on a production-restored staging copy at the target version; record pass/fail per risk ID. Deprecation fixes (the "fix before upgrading" list) become normal change tickets sequenced ahead of the upgrade.

5. 5.

   File the register as the upgrade's decision record. Go/no-go review walks the register: highs all tested, mediums tested or accepted with a name attached, non-issues spot-checked. After the upgrade, annotate what actually bit — the register's accuracy record is your calibration data for trusting the next one.

Make it yours

• SQL Serverthe corpus is "breaking changes" + "behavior changes" docs per version plus database compatibility-level notes; add your compat level and any trace flags to the inventory, and have the register distinguish engine-upgrade risks from compat-level-bump risks (you can sequence them separately).
• MySQLmine the release notes and the "changes affecting upgrades" section of the reference manual; the inventory must include SQL modes and charset/collation reality (utf8mb3 remnants), which is where 5.7→8.0-class upgrades actually break.
• Oraclefeed the Upgrade Guide's behavior-changes appendix and Database Reference parameter-change tables against your init parameters and PL/SQL feature usage; add optimizer-feature changes to the register explicitly and plan optimizer_features_enable staging comparisons where flagged.

Quality check

• Every register row cites both sidesa release-note line and an inventory line. Rows that cite only one side get deleted or downgraded to "background reading."
• High-severity rows were verified against the raw notessummarization inversion is real; five minutes of source-checking on the highs is the price of trusting the register.
• The non-issues list exists and is non-emptya register with no dismissed items means the model did not engage with your inventory; it just filtered by scariness.
• Staging tests map one-to-one to risk IDsuntested highs are undone work, visible as such in the go/no-go review.