add postgres upgrade guide

This commit is contained in:
ruslandoga 2022-09-24 12:35:33 +04:00
parent cbc35f7e5c
commit a220fd2d08
4 changed files with 193 additions and 0 deletions

View File

@ -10,3 +10,7 @@ Find instructions on how to run Plausible Analytics Self Hosted [in our docs](ht
We are always looking to expand on the options and setups provided here. Feel free to open an issue or PR if you feel
something could be improved.
### Upgrade guides
- [Upgrading `plausible_db` (PostgreSQL)](upgrade/postgres.md)

View File

@ -5,6 +5,7 @@ services:
restart: always
plausible_db:
# supported versions are 12, 13, and 14
image: postgres:14-alpine
restart: always
volumes:

View File

@ -49,6 +49,7 @@ spec:
fsGroup: 999
containers:
- name: plausible-db
# supported versions are 12, 13, and 14
image: postgres:latest
imagePullPolicy: Always
ports:

187
upgrade/postgres.md Normal file
View File

@ -0,0 +1,187 @@
Guide to upgrading PostgreSQL version `>= 12` to version `14` using `pg_dump` and `psql`. Based on [Upgrade a PostgreSQL database with docker.](https://hollo.me/devops/upgrade-postgresql-database-with-docker.html)
**Note:** following this guide you'd need to stop some containers and it would make your plausible instance temporarily unavailable.
---
### Plan
1. dump contents of the old version PostgreSQL to a file in a mounted volume
1. replace old version PostgreSQL with new version PostgreSQL
1. load dump from the mounted volume into new version PostgreSQL
---
### Steps
1. Add a backup volume to `plausible_db` in your `docker-compose.yml`
```diff
plausible_db:
image: postgres:12
restart: always
volumes:
- db-data:/var/lib/postgresql/data
+ - ./backup:/backup
environment:
- POSTGRES_PASSWORD=postgres
```
2. Stop relevant containers to avoid writing to old `plausible_db`
```console
> docker compose stop plausible plausible_db
[+] Running 2/2
⠿ Container hosting-plausible-1 Stopped 6.5s
⠿ Container hosting-plausible_db-1 Stopped 0.2s
```
3. Restart `plausible_db` container to attach volume
```console
> docker compose up plausible_db -d
[+] Running 1/1
⠿ Container hosting-plausible_db-1 Started 0.3s
```
4. Dump old `plausible_db` contents to a backup file
```console
> docker compose exec plausible_db sh -c "pg_dump -U postgres plausible_db > /backup/plausible_db.bak"
```
5. (Optional) verify backup went OK
```console
> ls backup
plausible_db.bak
> head backup/plausible_db.bak
--
-- PostgreSQL database dump
--
-- Dumped from database version 12.12 (Debian 12.12-1.pgdg110+1)
-- Dumped by pg_dump version 12.12 (Debian 12.12-1.pgdg110+1)
SET statement_timeout = 0;
SET lock_timeout = 0;
SET idle_in_transaction_session_timeout = 0;
```
6. Edit `docker-compose.yml` to use new PostgreSQL version, here we update from `v12` to `v14`, alpine flavour.
```diff
plausible_db:
- image: postgres:12
+ image: postgres:14-alpine
restart: always
volumes:
- db-data:/var/lib/postgresql/data
- ./backup:/backup
environment:
- POSTGRES_PASSWORD=postgres
```
7. Ensure relevant containers are stopped
```console
> docker compose stop plausible plausible_db
[+] Running 2/2
⠿ Container hosting-plausible-1 Stopped 0.0s
⠿ Container hosting-plausible_db-1 Stopped 0.2s
```
8. Remove old `plausible_db` container to be able to nuke its volume in the next step
```console
> docker compose rm plausible_db
? Going to remove hosting-plausible_db-1 Yes
[+] Running 1/0
⠿ Container hosting-plausible_db-1 Removed 0.0s
```
9. Remove old `plausible_db` volume, mine is named `hosting_db-data`
```console
> docker volume ls
DRIVER VOLUME NAME
<...snip...>
local hosting_db-data
local hosting_event-data
<...snip...>
> docker volume rm hosting_db-data
hosting_db-data
```
10. Start new version `plausible_db` container
```console
> docker compose up plausible_db -d
[+] Running 9/9
⠿ plausible_db Pulled 9.3s
⠿ 9b18e9b68314 Already exists 0.0s
⠿ 75aada9edfc5 Pull complete 1.2s
⠿ 820773693750 Pull complete 1.2s
⠿ 8812bb04ef2e Pull complete 5.2s
⠿ 2ccec0f7805c Pull complete 5.2s
⠿ 833f9b98598e Pull complete 5.3s
⠿ 1eb578dc04e6 Pull complete 5.4s
⠿ c873bf6204df Pull complete 5.4s
[+] Running 2/2
⠿ Volume "hosting_db-data" Created 0.0s
⠿ Container hosting-plausible_db-1 Started 0.5s
```
11. Create new DB and load data into it
```console
> docker compose exec plausible_db createdb -U postgres plausible_db
> docker compose exec plausible_db sh -c "psql -U postgres -d plausible_db < /backup/plausible_db.bak"
SET
SET
SET
SET
SET
set_config
------------
(1 row)
SET
SET
SET
SET
CREATE EXTENSION
<...snip...>
```
12. Start all other containers
```console
> docker compose up -d
[+] Running 4/4
⠿ Container hosting-plausible_events_db-1 Running 0.0s
⠿ Container hosting-mail-1 Running 0.0s
⠿ Container hosting-plausible_db-1 Started 0.5s
⠿ Container hosting-plausible-1 Started 0.5s
```
13. (Optional) Remove backups from `docker-compose.yml` and your filesystem
```diff
plausible_db:
image: postgres:14-alpine
restart: always
volumes:
- db-data:/var/lib/postgresql/data
- - ./backup:/backup
environment:
- POSTGRES_PASSWORD=postgres
```
```
> rm -rf ./backup
```