Citus upgrade instructions on Docker

[ozgune]

Why are we implementing it? (sales eng)

I upgraded my Docker image yesterday and restarted a local Citus cluster. I then connected to the coordinator node using the instructions on our website and ran a query. I observed the following error message:

postgres=# ALTER TABLE campaigns ADD CONSTRAINT testfk FOREIGN KEY (company_id) REFERENCES companies (id);

ERROR:  loaded Citus library version differs from installed extension version
DETAIL:  Loaded library requires 6.2, but the installed extension version is 6.1-17.
HINT:  Run ALTER EXTENSION citus UPDATE and try again.

I realized that I had to run the update command, and followed the steps to upgrade.

postgres=# ALTER EXTENSION citus UPDATE;

postgres=# ALTER TABLE campaigns ADD CONSTRAINT testfk FOREIGN KEY (company_id) REFERENCES companies (id);

ERROR:  loaded Citus library version differs from installed extension version
DETAIL:  Loaded library requires 6.2, but the installed extension version is 6.1-17.
HINT:  Run ALTER EXTENSION citus UPDATE and try again.
CONTEXT:  while executing command on citus_worker_1

I was at first confused about seeing the same error message again. I tried to mimic a standard user's behavior and browsed around our documentation for this error message.

I also found the upgrade instructions in our docs, but we didn't talk about running the update command on the coordinator and worker nodes: https://docs.citusdata.com/en/v6.2/admin_guide/upgrading_citus.html#step-2-apply-update-in-db

What are the typical use cases?

Minor version upgrades - Docker (I'll test these steps on other platforms). One challenge with Docker is that we don't tell users how to access worker nodes.

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

Avoid confusion if the user sees the same error message multiple times after running ALTER EXTENSION citus UPDATE; on the coordinator node

Good locations for content in docs structure

Upgrade steps for minor version upgrades or FAQ

Link to relevant commits and regression tests if applicable

https://github.com/citusdata/citus/issues/907 https://github.com/citusdata/citus/issues/907#issuecomment-277106059 (related comment on major / minor version upgrades) https://github.com/citusdata/citus/issues/1422 https://github.com/citusdata/citus_docs/issues/281

[begriffs]

Thanks for the report. I renamed this to highlight that it's about Docker. We can consider it in the prioritization meeting.

[jonels-msft]

Docker changes frequently, and I wonder whether our instructions for installing docker are still even valid.

@jasonmp85 what's the story with upgrading citus inside a docker container? Is this something we even recommend, or should people consider docker instances to be more ephemeral?