Upgrade PostgreSQL 17.8 to 18.2

[krusche]

Summary

• Upgrade PostgreSQL from 17.8-alpine to 18.2-alpine across all environments (dev, prod, integration tests)
• Add PGDATA=/var/lib/postgresql/data to production compose file to handle PG 18's changed default data directory path
• Add major version upgrade documentation (pg_dump/pg_restore procedure, rollback steps) to docs/DATABASE.md
• Simplify Keycloak setup instructions in docs/DEVELOPMENT.md (realm, users, and roles are auto-imported)

Motivation

PostgreSQL 18 is the latest stable major release. All dependencies (JDBC 42.7.10, Hibernate 7, Liquibase 5, TestContainers 2.0.3) are compatible. The upgrade brings performance improvements and continued security support.

Breaking Change: PGDATA Path

PG 18's Docker image changed the default PGDATA from /var/lib/postgresql/data to /var/lib/postgresql/18/docker. The prod compose file explicitly sets PGDATA=/var/lib/postgresql/data to preserve existing volume mounts.

Changes

File	Change
docker-compose.yml	postgres:17.8-alpine → postgres:18.2-alpine
docker-compose.prod.yml	Image upgrade + PGDATA env var
BaseIntegrationTest.java	TestContainers image → 18.2-alpine
BaseKeycloakIntegrationTest.java	TestContainers image → 18.2-alpine
docs/DATABASE.md	Added major version upgrade guide with step-by-step procedure and rollback
docs/DEVELOPMENT.md	Simplified Keycloak section (auto-import)

Test plan

• CI integration tests pass against PG 18 via TestContainers
• Deploy to thesis-dev.aet.cit.tum.de using the manual pg_dump/pg_restore procedure
• Verify server starts, Liquibase reports 0 pending changesets
• Verify search, filtering, and CRUD operations work correctly

Summary by CodeRabbit

• Documentation

  • Added comprehensive PostgreSQL major version upgrade guide, including step-by-step migration procedures, data recovery strategies, and rollback instructions.
  • Simplified developer setup documentation with automatic Keycloak realm configuration on startup.

• Chores

  • Updated PostgreSQL from version 17.8 to 18.2 (Alpine Linux) across production and test environments.

[coderabbitai]

Warning

Rate limit exceeded

@krusche has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 11 minutes and 59 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

Walkthrough

PostgreSQL upgraded from version 17.8 to 18.2 across Docker Compose configurations and test containers. PostgreSQL data directory path added to production environment. Database migration documentation added with step-by-step procedures. Keycloak development setup simplified to reflect automatic realm import on startup.

Changes

Cohort / File(s)	Summary
PostgreSQL Version Upgrade docker-compose.yml, docker-compose.prod.yml, server/src/test/java/de/tum/cit/aet/thesis/keycloak/BaseKeycloakIntegrationTest.java, server/src/test/java/de/tum/cit/aet/thesis/mock/BaseIntegrationTest.java	Updated PostgreSQL image tag from 17.8-alpine to 18.2-alpine across all Docker and test configurations. Added PGDATA environment variable to production compose file.
Documentation Updates docs/DATABASE.md, docs/DEVELOPMENT.md	Added comprehensive PostgreSQL major version upgrade guidance with step-by-step procedures to DATABASE.md. Simplified Keycloak setup instructions in DEVELOPMENT.md, removing manual configuration steps in favor of automatic realm import note.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'Upgrade PostgreSQL 17.8 to 18.2' directly and clearly summarizes the main change across the entire changeset, which is upgrading PostgreSQL from version 17.8 to 18.2 across all environments and test files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch chore/upgrade-postgres-18.2

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

docker-compose.prod.yml (1)

117-124: PGDATA override works for Alpine, but the official PG 18+ recommendation is to mount at /var/lib/postgresql.

The PG 18 Docker image changed the default PGDATA to be version-specific — for PG 18, it is /var/lib/postgresql/18/docker. The declared VOLUME also moved to /var/lib/postgresql, and mounts/volumes are meant to target that updated location.

The current setup (PGDATA=/var/lib/postgresql/data + mount at ./postgres_data:/var/lib/postgresql/data) is safe for now because Alpine images include a compatibility symlink that creates /var/lib/postgresql/data -> . to support legacy mount paths, so postgres will initialize correctly.

However, the suggested container configuration for 18+ is to place a single mount at /var/lib/postgresql, which would position future major-version upgrades to use pg_upgrade --link efficiently. If that migration is acceptable, the recommended setup would be:

-      - PGDATA=/var/lib/postgresql/data
+      - PGDATA=/var/lib/postgresql/18/docker
   volumes:
-      - ./postgres_data:/var/lib/postgresql/data
+      - ./postgres_data:/var/lib/postgresql

(This would require a data directory migration step — moving files from ./postgres_data/ into ./postgres_data/18/docker/ before restarting — so keeping the override is the lower-risk path for this PR.)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docker-compose.prod.yml` around lines 117 - 124, Update the postgres service
using image "postgres:18.2-alpine" (container_name thesis-management-db) to
mount the canonical Postgres 18 volume: change the volumes entry from
./postgres_data:/var/lib/postgresql/data to ./postgres_data:/var/lib/postgresql
and remove or update the PGDATA environment override (PGDATA currently set to
/var/lib/postgresql/data) — either remove PGDATA so the image uses its default,
or set PGDATA to the versioned path (/var/lib/postgresql/18/docker) if you plan
to migrate data into that layout; perform any on-disk data migration beforehand
if you switch to the new mount layout.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/DATABASE.md`:
- Around line 102-103: The pg_restore invocation currently used ("docker exec
thesis-management-db pg_restore -U \"$DB_USER\" -d \"$DB_NAME\" --no-owner
--no-acl /tmp/thesis_dump.dump") should be updated to include the
--exit-on-error flag so the command fails non-zero on any restore error and the
script won't proceed with a partial restore; locate the pg_restore call in
docs/DATABASE.md and add the --exit-on-error option to the existing argument
list.

In `@docs/DEVELOPMENT.md`:
- Around line 11-13: The fenced code block containing the command "docker
compose up keycloak -d" in DEVELOPMENT.md is missing a language specifier and
triggers the MD040 linter; update the opening fence to include a shell language
(e.g., change the triple backticks before the command to "```shell" or
"```bash") so the block reads as a shell code block and the linter warning is
resolved.

---

Nitpick comments:
In `@docker-compose.prod.yml`:
- Around line 117-124: Update the postgres service using image
"postgres:18.2-alpine" (container_name thesis-management-db) to mount the
canonical Postgres 18 volume: change the volumes entry from
./postgres_data:/var/lib/postgresql/data to ./postgres_data:/var/lib/postgresql
and remove or update the PGDATA environment override (PGDATA currently set to
/var/lib/postgresql/data) — either remove PGDATA so the image uses its default,
or set PGDATA to the versioned path (/var/lib/postgresql/18/docker) if you plan
to migrate data into that layout; perform any on-disk data migration beforehand
if you switch to the new mount layout.