feat(docker): upgrade to PostgreSQL 18 and PostGIS 3.6.2

- Updated base image to `postgres:18.2-alpine3.23` for PostgreSQL 18.
- Upgraded PostGIS version to 3.6.2 for enhanced spatial features.
- Adjusted `PGDATA` default path to include versioning
  (`/var/lib/postgresql/18/docker`).
- Updated README with migration instructions for PostgreSQL 18 and new
  data directory structure.

Author: joggienl

Dockerfile

@@ -1,13 +1,13 @@
 
 # === VARIABLES (defined once) ===
-# Using the latest PostgreSQL 17 Alpine image for minimal size
-ARG BASE_IMAGE=postgres:17.5-alpine3.22
+# Using the latest PostgreSQL 18 Alpine image for minimal size
+ARG BASE_IMAGE=postgres:18.2-alpine3.23
 # PostgreSQL version for the base image and compatibility checks
-ARG PG_VERSION=17.5
-# PostGIS 3.5.3 provides the spatial features we need while maintaining compatibility
-ARG POSTGIS_VERSION=3.5.3
+ARG PG_VERSION=18.2
+# PostGIS 3.6.2 provides the spatial features we need while maintaining compatibility
+ARG POSTGIS_VERSION=3.6.2
 # SHA256 checksum ensures we're getting the exact source code we expect
-ARG POSTGIS_SHA256=44222ed2b8f742ffc1ceb429b09ebb484c7880f9ba27bf7b6b197346cdd25437
+ARG POSTGIS_SHA256=607a4d21c017e5283e15d2d977c9b7f575ddfc672afdee81fc84a2d823db4ba5
 
 # === BUILD STAGE ===
 # Multi-stage build keeps the final image lean by excluding build tools

README.md

@@ -15,7 +15,7 @@ Alpine Linux for minimal size while maintaining full spatial database functional
 - 🔄 **Multi-Architecture**: Native support for both ARM64 and AMD64 platforms
 - 🧪 **Thoroughly Tested**: Comprehensive test suite ensures reliability
 - 🔒 **Secure Base**: Built on official PostgreSQL Alpine images
-- 📦 **Latest Versions**: PostgreSQL 17 + PostGIS 3.5.3
+- 📦 **Latest Versions**: PostgreSQL 18 + PostGIS 3.6.2
 
 ### What's Included
 
@@ -66,35 +66,88 @@ platform (AMD64 or ARM64).
 
 ### Environment Variables
 
-| Variable            | Description                    | Default                    |
-|---------------------|--------------------------------|----------------------------|
-| `POSTGRES_PASSWORD` | PostgreSQL password (required) | -                          |
-| `POSTGRES_USER`     | PostgreSQL username            | `postgres`                 |
-| `POSTGRES_DB`       | Database name                  | `postgres`                 |
-| `PGDATA`            | Data directory                 | `/var/lib/postgresql/data` |
+| Variable            | Description                    | Default                         |
+|---------------------|--------------------------------|---------------------------------|
+| `POSTGRES_PASSWORD` | PostgreSQL password (required) | -                               |
+| `POSTGRES_USER`     | PostgreSQL username            | `postgres`                      |
+| `POSTGRES_DB`       | Database name                  | `postgres`                      |
+| `PGDATA`            | Data directory                 | `/var/lib/postgresql/18/docker` |
 
 All standard PostgreSQL environment variables are supported. See
 the [official PostgreSQL Docker documentation](https://hub.docker.com/_/postgres) for more details.
 
+> **Note:** Starting with PostgreSQL 18, the PGDATA path is now version-specific to enable easier
+> major version upgrades using `pg_upgrade --link`.
+
 ### Using with Docker Compose
 
 ```yaml
-version: '3'
+services:
+   postgis:
+      image: ghcr.io/clevercactus-dev/docker-lean-postgis:latest
+      environment:
+         POSTGRES_PASSWORD: mysecretpassword
+         POSTGRES_DB: mydb
+      ports:
+         - "5432:5432"
+      volumes:
+         - postgis-data:/var/lib/postgresql
+
+volumes:
+   postgis-data:
+```
+
+## 🔄 Migrating from PostgreSQL 17 to 18
+
+PostgreSQL 18 introduces a breaking change in the data directory structure. If you're upgrading from
+a previous version of this image (PostgreSQL 17), you have two options:
+
+### Option 1: Use the Old PGDATA Path (Backwards Compatible)
+
+Keep using your existing volumes by explicitly setting the PGDATA environment variable:
+
+```yaml
 services:
   postgis:
     image: ghcr.io/clevercactus-dev/docker-lean-postgis:latest
     environment:
       POSTGRES_PASSWORD: mysecretpassword
       POSTGRES_DB: mydb
+      PGDATA: /var/lib/postgresql/data  # Use old location
     ports:
       - "5432:5432"
     volumes:
-      - postgis-data:/var/lib/postgresql/data
+      - postgis-data:/var/lib/postgresql/data  # Old mount point
 
 volumes:
   postgis-data:
 ```
 
+### Option 2: Migrate to the New Structure (Recommended)
+
+For new deployments or when you want to benefit from easier future upgrades:
+
+1. **Backup your existing data:**
+   ```bash
+   docker exec your-container pg_dumpall -U postgres > backup.sql
+   ```
+
+2. **Update your docker-compose.yml to use the new volume mount:**
+   ```yaml
+   volumes:
+     - postgis-data:/var/lib/postgresql  # New mount point
+   ```
+
+3. **Start the new container and restore:**
+   ```bash
+   docker-compose up -d
+   docker exec -i your-container psql -U postgres < backup.sql
+   ```
+
+> **Why this change?** The new versioned PGDATA path (`/var/lib/postgresql/18/docker`) enables
+> faster major version upgrades using `pg_upgrade --link` by keeping data directories separate per
+> version.
+
 ## 🔨 Building
 
 To build the image locally: