fix(helm): add pgdata init container and PGDATA env for PostgreSQL StatefulSet

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- **Helm (Chart 0.1.1): PostgreSQL PGDATA subdirectory pattern** — new `postgresql.usePgdataSubdirectory` value (default `false`) enables PGDATA subdirectory to avoid PVC metadata conflicts. Required for PostgreSQL 18+. **BREAKING if enabled on existing deployments** — see chart NOTES.txt for manual migration steps.
+
 ## [0.3.1] - 2026-04-20
 
 ### Fixed

helm/optio/Chart.yaml

@@ -3,8 +3,8 @@ name: optio
 description: AI Agent Workflow Orchestration
 kubeVersion: ">=1.33.0"
 type: application
-version: 0.1.0
-appVersion: "0.1.0"
+version: 0.1.1
+appVersion: "0.3.1"
 home: https://github.com/jonwiggins/optio
 sources:
   - https://github.com/jonwiggins/optio

helm/optio/templates/NOTES.txt

@@ -60,3 +60,22 @@ For Docker Desktop / kind / minikube, also patch with --kubelet-insecure-tls:
     -p '[{"op":"add","path":"/spec/template/spec/containers/0/args/-","value":"--kubelet-insecure-tls"}]'
 
 Without metrics-server, CPU and memory usage will show as "N/A".
+
+{{- if and .Values.postgresql.enabled (not .Values.postgresql.usePgdataSubdirectory) }}
+
+---
+
+POSTGRESQL DATA DIRECTORY
+
+PostgreSQL is using the PVC mount root as the data directory.
+
+For PostgreSQL 18+ or to avoid conflicts with PVC metadata (lost+found),
+consider enabling the subdirectory pattern in values.yaml:
+
+  postgresql:
+    usePgdataSubdirectory: true
+
+⚠️  WARNING: This is a BREAKING CHANGE for existing deployments.
+Enabling this on an existing database will cause data loss unless you
+manually migrate first. See CHANGELOG for migration instructions.
+{{- end }}

helm/optio/templates/postgres.yaml

@@ -50,8 +50,27 @@ spec:
         runAsUser: 999
         runAsGroup: 999
         fsGroup: 999
-      {{- if .Values.postgresql.tls.enabled }}
+        fsGroupChangePolicy: OnRootMismatch
       initContainers:
+        - name: init-pgdata
+          image: busybox:1.36
+          command: ["sh", "-c"]
+          args:
+            - |
+              chown -R 999:999 /var/lib/postgresql/data
+              chmod 700 /var/lib/postgresql/data
+              {{- if .Values.postgresql.usePgdataSubdirectory }}
+              mkdir -p /var/lib/postgresql/data/pgdata
+              chmod 700 /var/lib/postgresql/data/pgdata
+              chown 999:999 /var/lib/postgresql/data/pgdata
+              {{- end }}
+          securityContext:
+            runAsUser: 0
+            runAsNonRoot: false
+          volumeMounts:
+            - name: data
+              mountPath: /var/lib/postgresql/data
+        {{- if .Values.postgresql.tls.enabled }}
         - name: init-tls
           image: busybox:1.36
           securityContext:
@@ -72,7 +91,7 @@ spec:
               readOnly: true
             - name: postgres-tls
               mountPath: /etc/postgres-tls
-      {{- end }}
+        {{- end }}
       containers:
         - name: postgres
           image: "{{ .Values.postgresql.image.repository }}:{{ .Values.postgresql.image.tag }}"
@@ -93,6 +112,10 @@ spec:
             - "ssl_min_protocol_version=TLSv1.3"
           {{- end }}
           env:
+            {{- if .Values.postgresql.usePgdataSubdirectory }}
+            - name: PGDATA
+              value: /var/lib/postgresql/data/pgdata
+            {{- end }}
             - name: POSTGRES_DB
               value: {{ .Values.postgresql.auth.database }}
             - name: POSTGRES_USER

helm/optio/values.yaml

@@ -196,6 +196,12 @@ postgresql:
   image:
     repository: postgres
     tag: "16"
+  # Use PGDATA subdirectory pattern (recommended for PostgreSQL 18+).
+  # When true, creates /var/lib/postgresql/data/pgdata subdirectory to avoid
+  # conflicts with PVC metadata (lost+found). Required for fresh PostgreSQL 18+
+  # deployments. BREAKING: Defaults to false for existing deployments to preserve data.
+  # Set to true for new installs or after manual migration (see chart NOTES).
+  usePgdataSubdirectory: false
   resources:
     requests:
       cpu: 100m