Upgrade instructions misses a couple of catalog tables

[thanodnl]

Why are we implementing it? (sales eng)

There have been some new catalog tables added to citus last year that are not in the upgrade description. Tables that come to mind that are missing

• pg_dist_poolinfo
• pg_dist_authinfo

What are the typical use cases?

keeping track of citus catalogs during upgrades.

Communication goals (e.g. detailed howto vs orientation)

Good locations for content in docs structure

https://docs.citusdata.com/en/v8.2/admin_guide/upgrading_citus.html?highlight=upgrade#on-every-node-coordinator-and-workers

How does this work? (devs)

pg_catalog is not preserved during upgrades, we have some instructions to keep the tables around, but not all tables are preserved.

Example sql

Corner cases, gotchas

Oid's are not preserved for all objects during upgrades, tables having oid's in them might need extra instructions.

Are there relevant blog posts or outside documentation about the concept/feature?

Link to relevant commits and regression tests if applicable

[jonels-msft]

Thanks for the note, will incorporate this into the next release.

[thanodnl]

@jonels-msft we are actually changing the upgrade to be easier on the user/documentation.

currently we have 2 functions added instead of the manual backup:

• citus_prepare_pg_upgrade() to be called before running pg_upgrade on the old postgres version
• citus_finish_pg_upgrade() to be called after pg_upgrade on the new postgres version

These routines can be extended by engineering to encapsulate any new requirements we put on upgrading and also give some freedom in moving some parts around.

PR for reference https://github.com/citusdata/citus/pull/2877

We might move the function to the citus namespace, function names would become sth like:

• citus.prepare_pg_upgrade()
• citus.finish_pg_upgrade()

I will let you know here when we release what the actual functions would have become. If you are testing now use the first functions.