Document Central v2023.2 upgrade to Postgres 14 #1577
Conversation
lognaturel
force-pushed
the
pg-upgrade
branch
from
ffd1d1b
to
35d05a7
Compare
|
For some reason I don't get a finger mouse-pointer 👆 when mouse is hovering over these tabs. Tested in both Firefox & Chrome. Works fine on the example at https://sphinx-tabs.readthedocs.io/en/latest/. |
lognaturel
changed the title
There was a problem hiding this comment.
I've successfully gone through the basic upgrade steps! 🎉🎉🎉 I kind of want to try again and see what happens if I don't follow the rules, don't touch the right file, etc.
Left some comments about how the docs could give a little bit more context.
I went ahead and made these changes in a branch somewhere. I could do a PR on the PR, or just add them to this branch, but I wanted someone to see them first. They're here in this commit: 66a5a47
|
Thanks, @ktuite, I have incorporated your commit! |
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as outdated.
This comment was marked as outdated.
docs/central-upgrade.rst
Outdated
|
|
||
| touch ./files/allow-postgres14-upgrade | ||
|
|
||
| #. **Stop Central.** Central needs to be stopped in order to make a clean copy of the database. |
There was a problem hiding this comment.
You should be able to build, then stop. That will minimize your downtime. That's what we've done historically, but this should be tested.
There was a problem hiding this comment.
I'm now wondering whether this is a good idea. That means things can happen between backup and stop. Maybe our standard recommendation should be to stop everything, back up, then do what needs to be done. Folks who are more advanced can do whatever they want.
|
|
||
| .. tab:: Custom database | ||
|
|
||
| #. **Find instructions for upgrading your database server to PostgreSQL 14**. Here are instructions for some popular fully-managed options: |
There was a problem hiding this comment.
Nothing has to change in the instructions, I was just thinking about folks that have a newer than 9.6 Postgres. How badly do they need to upgrade? Or what if they're on v15?
|
|
||
| .. code-block:: console | ||
|
|
||
| $ git status |
There was a problem hiding this comment.
Was just wondering what some of these instructions would look like if they did the git pull step first. How different would cleaning up the config files be? In other words, how important is it that you migrate the custom config options before pulling the new code changes?
There was a problem hiding this comment.
I have a hard time making sense of how to fix the merge conflicts myself, even after doing it a few times. I was not able to come up with a good way to explain it.
There was a problem hiding this comment.
To be clear, the process I've documented is what I ended up finding the easiest for myself.
There was a problem hiding this comment.
They way I finally wrapped my head around this section:
- Make backups for files/service/config.json.template and docker-compose.yml
- Reset the git contents of those files
- Things from those two files specifically are moving to
.env(i'd prefer if i could put them back into .env after i git pull) - git stash any other changes you have so you can apply those changes after the upgrade
There was a problem hiding this comment.
Cool! That looks about like what we have now but we've broken it down a bit more? Most folks will only have changes to either files/service/config.json.template or docker-compose.yml, hence the separation. I think copying to the local machine is much easier because of having multiple windows at once.
i'd prefer if i could put them back into .env after i git pull
Why?
|
|
||
| .. code-block:: console | ||
|
|
||
| $ git diff files/service/config.json.template |
There was a problem hiding this comment.
As I'm going through the steps, I feel very nervous about this step of copying values into another file and deleting my changes to this file long before I know if it will actually work. I think there should be a recommendation to make a copy/backup of this file to refer to just in case.
There was a problem hiding this comment.
It is also awkward to check my diff and then enter new values into .env. I also wish I had the .env.template already.
There was a problem hiding this comment.
Adding a backup step.
awkward to check my diff and then enter new values into .env
Can you say more about that? Did you use the recommended process of copying the diff lines with + to a file on your computer?
wish I had the .env.template already.
Did you copy the blocks from the docs and paste them in?
There was a problem hiding this comment.
I did copy from the blocks, I just felt like I was doing this kind of blindly, not knowing where I'd end up.
I did go seek out the template, and seeing it made me think, "Oh, that's what i'm aiming for, that's not scary". I also used it to copy over the sentry values.
There was a problem hiding this comment.
I think maybe this is because Cloud customizes everything? For most people only one or maybe two of these blocks will be relevant. Most common will be just email, I think.
|
|
||
| .. code-block:: console | ||
|
|
||
| $ git status |
There was a problem hiding this comment.
They way I finally wrapped my head around this section:
- Make backups for files/service/config.json.template and docker-compose.yml
- Reset the git contents of those files
- Things from those two files specifically are moving to
.env(i'd prefer if i could put them back into .env after i git pull) - git stash any other changes you have so you can apply those changes after the upgrade
Alternative to #1573
TODO:
I rebased the commits from #1573 on master to get sidebar updates (clean rebase). Then I separated out default and custom db instructions into tabs and added instructions on how to determine which one is being used.
I tried to identify points at which something could go wrong and provide some guidance.
The part I'm least happy with is the part about dealing with the
docker-compose.ymlconflicts in the custom db case. Unfortunately I don't think we can assume that everyone following these instructions would know how to resolve merge conflicts. We've seen organizations have high turnover and folks with very little IT experience suddenly becoming admins. I want to make sure folks like that have the best shot possible at getting this right.Archive.zip
@alxndrsn feel free to push to this branch and/or cherry pick my commits onto yours.