citusdata / citusdata/citus_docs
Citus upgrade instructions on Docker
- Dominant language
- CSS
- Stars
- 58
- Forks
- 60
- PR merge metrics
- No merged PRs in 30d
Description
## 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
Contributor guide
Assessment
This issue has not been assessed yet.