plausible-hosting/upgrade/postgres.md

Guide to upgrading PostgreSQL version >= 12 to version 14 using pg_dump and psql. Based on Upgrade a PostgreSQL database with docker.

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
2. replace old version PostgreSQL with new version PostgreSQL
3. load dump from the mounted volume into new version PostgreSQL

---

Steps

1. Add a backup volume to plausible_db in your docker-compose.yml

  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

> 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

> 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

> docker compose exec plausible_db sh -c "pg_dump -U postgres plausible_db > /backup/plausible_db.bak"

5. (Optional) verify backup went OK

> 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.

  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

> 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

> 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

> 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

> 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

> 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

> 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

  plausible_db:
    image: postgres:14-alpine
    restart: always
    volumes:
      - db-data:/var/lib/postgresql/data
-     - ./backup:/backup
    environment:
      - POSTGRES_PASSWORD=postgres

> rm -rf ./backup