add postgres upgrade guide

README.md

@@ -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)

docker-compose.yml

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

kubernetes/plausible-db.yaml

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

upgrade/postgres.md

@@ -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
+```