update with latest build versions, includes custom build for postgres and migrating from v16 to v18
This commit is contained in:
184
build/postgresql-postgis/Migration_Plan.md
Normal file
184
build/postgresql-postgis/Migration_Plan.md
Normal file
@@ -0,0 +1,184 @@
|
||||
# PostgreSQL 18 + PostGIS 3.6 for CloudNativePG (ARM64 Source Build)
|
||||
|
||||
## Overview
|
||||
|
||||
Upgrade from PostgreSQL 16 to PostgreSQL 18 with PostGIS 3.6 for ARM64 CloudNativePG deployment.
|
||||
|
||||
**Why build from source?**
|
||||
- The official `postgis/postgis:18-3.6` image only supports AMD64, not ARM64
|
||||
- `imresamu/postgis` hasn't released PG18 ARM64 images yet
|
||||
- Building from source ensures ARM64 compatibility for your cluster
|
||||
|
||||
**Current Setup:**
|
||||
- Image: `registry.keyboardvagabond.com/library/cnpg-postgis:16.6-3.4-v2`
|
||||
- Base: `imresamu/postgis:16-3.4`
|
||||
- PostgreSQL: 16.6
|
||||
- PostGIS: 3.4
|
||||
|
||||
**Target Setup:**
|
||||
- Image: `registry.keyboardvagabond.com/library/cnpg-postgis:18-3.6`
|
||||
- Base: `postgres:18-bookworm` (official, ARM64 supported)
|
||||
- PostgreSQL: 18.1
|
||||
- PostGIS: 3.6.1 (compiled from source)
|
||||
- GEOS: 3.13.0
|
||||
- PROJ: 9.4.1
|
||||
- GDAL: 3.10.1
|
||||
|
||||
## Extensions Included
|
||||
|
||||
| Extension | Description | Status |
|
||||
|-----------|-------------|--------|
|
||||
| postgis | Core GIS functionality | ✓ Compiled |
|
||||
| postgis_topology | Topology support | ✓ Compiled |
|
||||
| postgis_raster | Raster support | ✓ Compiled |
|
||||
| fuzzystrmatch | Fuzzy string matching | ✓ Compiled |
|
||||
| postgis_tiger_geocoder | US Census TIGER geocoder | ✓ Compiled |
|
||||
|
||||
## Build Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Stage 1: Builder │
|
||||
│ - Base: postgres:18-bookworm (ARM64) │
|
||||
│ - Compile GEOS 3.13.0 │
|
||||
│ - Compile PROJ 9.5.1 │
|
||||
│ - Compile GDAL 3.10.1 │
|
||||
│ - Compile PostGIS 3.6.1 │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ Stage 2: CNPG Tools │
|
||||
│ - ghcr.io/cloudnative-pg/postgresql:18 │
|
||||
│ - Extract barman-cloud tools for backup/restore │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ Stage 3: Final Image (minimal) │
|
||||
│ - Base: postgres:18-bookworm (ARM64) │
|
||||
│ - Copy compiled libs from Stage 1 │
|
||||
│ - Copy barman tools from Stage 2 │
|
||||
│ - Fix postgres UID to 26 (CNPG requirement) │
|
||||
│ - Runtime dependencies only │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## ⚠️ Important: PG18 Data Directory Change
|
||||
|
||||
PostgreSQL 18 changed the default data directory path:
|
||||
|
||||
| Version | Data Directory |
|
||||
|---------|----------------|
|
||||
| PG 13-17 | `/var/lib/postgresql/data` |
|
||||
| PG 18+ | `/var/lib/postgresql` |
|
||||
|
||||
This affects volume mounts in docker-compose and may require CNPG configuration changes.
|
||||
|
||||
## Migration Steps
|
||||
|
||||
### Phase 1: Build and Test Locally
|
||||
|
||||
1. **Build the image (takes 15-30 minutes):**
|
||||
```bash
|
||||
cd build/postgresql-postgis
|
||||
chmod +x build.sh initdb-postgis.sh update-postgis.sh
|
||||
./build.sh
|
||||
```
|
||||
|
||||
2. **Test with docker-compose:**
|
||||
```bash
|
||||
docker-compose -f docker-compose.test.yaml up -d
|
||||
docker-compose -f docker-compose.test.yaml exec postgres psql -U postgres
|
||||
|
||||
# In psql, verify:
|
||||
SELECT postgis_full_version();
|
||||
SELECT ST_AsText(ST_Point(0, 0));
|
||||
\dx -- list extensions
|
||||
|
||||
# Cleanup
|
||||
docker-compose -f docker-compose.test.yaml down -v
|
||||
```
|
||||
|
||||
3. **Interactive testing:**
|
||||
```bash
|
||||
docker run -it --rm -e POSTGRES_PASSWORD=test cnpg-postgis:18-3.6 bash
|
||||
```
|
||||
|
||||
### Phase 2: Push to Registry
|
||||
|
||||
```bash
|
||||
docker push registry.keyboardvagabond.com/library/cnpg-postgis:18-3.6
|
||||
```
|
||||
|
||||
### Phase 3: CNPG Upgrade
|
||||
|
||||
**Option A: In-place upgrade (for testing)**
|
||||
|
||||
1. Update `manifests/infrastructure/postgresql/cluster-shared.yaml`:
|
||||
```yaml
|
||||
spec:
|
||||
imageName: registry.keyboardvagabond.com/library/cnpg-postgis:18-3.6
|
||||
```
|
||||
|
||||
2. CNPG will handle the rolling upgrade automatically.
|
||||
|
||||
**Option B: Create new cluster and migrate (safer for production)**
|
||||
|
||||
1. Create a new cluster with PG18 image
|
||||
2. Use pg_dump/pg_restore or CNPG backup/restore
|
||||
3. Switch applications to new cluster
|
||||
4. Decommission old cluster
|
||||
|
||||
## CNPG Operator Compatibility
|
||||
|
||||
- Current operator: `>=0.20.0` (Helm chart)
|
||||
- PostgreSQL 18 support: Requires CNPG operator 1.24+
|
||||
- Check current version:
|
||||
```bash
|
||||
kubectl get deployment -n postgresql-system -l app.kubernetes.io/name=cloudnative-pg \
|
||||
-o jsonpath='{.items[0].spec.template.spec.containers[0].image}'
|
||||
```
|
||||
|
||||
If upgrade needed, update `manifests/infrastructure/postgresql/operator.yaml`:
|
||||
```yaml
|
||||
spec:
|
||||
chart:
|
||||
spec:
|
||||
version: ">=0.23.0" # or specific version with PG18 support
|
||||
```
|
||||
|
||||
## Rollback Plan
|
||||
|
||||
If issues occur:
|
||||
1. Change imageName back to `registry.keyboardvagabond.com/library/cnpg-postgis:16.6-3.4-v2`
|
||||
2. CNPG will roll back to previous version
|
||||
3. Restore from backup if data issues
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
- [ ] Image builds successfully on M1 Mac (~15-30 min)
|
||||
- [ ] postgres user has UID 26
|
||||
- [ ] GEOS, PROJ, GDAL compiled correctly
|
||||
- [ ] PostGIS extensions install correctly
|
||||
- [ ] barman-cloud tools are present
|
||||
- [ ] Local docker-compose test passes
|
||||
- [ ] Spatial queries work (`ST_Point`, `ST_AsText`, etc.)
|
||||
- [ ] Image pushed to Harbor registry
|
||||
- [ ] CNPG operator compatible with PG18
|
||||
- [ ] Test cluster upgrade in staging (if available)
|
||||
- [ ] Production cluster upgrade successful
|
||||
- [ ] All fediverse apps functioning correctly
|
||||
|
||||
## Build Dependencies (compiled from source)
|
||||
|
||||
| Library | Version | Purpose |
|
||||
|---------|---------|---------|
|
||||
| GEOS | 3.13.0 | Geometry operations |
|
||||
| PROJ | 9.4.1 | Coordinate transformations |
|
||||
| GDAL | 3.10.1 | Raster/vector data access |
|
||||
| PostGIS | 3.6.1 | PostgreSQL spatial extension |
|
||||
|
||||
## References
|
||||
|
||||
- [PostgreSQL 18 Release Notes](https://www.postgresql.org/docs/18/release-18.html)
|
||||
- [PostGIS 3.6 Release Notes](https://postgis.net/documentation/getting_started/)
|
||||
- [docker-postgis GitHub](https://github.com/postgis/docker-postgis)
|
||||
- [CloudNativePG Documentation](https://cloudnative-pg.io/documentation/)
|
||||
- [GEOS Downloads](https://download.osgeo.org/geos/)
|
||||
- [PROJ Downloads](https://download.osgeo.org/proj/)
|
||||
- [GDAL Downloads](https://github.com/OSGeo/gdal/releases)
|
||||
Reference in New Issue
Block a user