PostgreSQL

Production-ready PostgreSQL deployment with support for standalone and streaming replication architectures.

Key Features

• Standalone and replication — Single instance or primary with streaming replicas
• Automatic initialization — Init scripts, extensions, and custom configuration
• S3 backup — Scheduled backups to S3-compatible storage via CronJob
• Metrics — Prometheus exporter with ServiceMonitor
• Security — Non-root containers, network policies, TLS support
• Persistent storage — Configurable PVCs with storage class selection

Architecture

Installation

HTTPS repository:

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install my-pg helmforge/postgresql

OCI registry:

helm install my-pg oci://ghcr.io/helmforgedev/helm/postgresql

Deployment Examples

# values.yaml
architecture: standalone

auth:
  postgresPassword: 'my-secret-password'
  database: myapp
  username: myuser
  password: 'user-password'

standalone:
  persistence:
    enabled: true
    size: 20Gi

metrics:
  enabled: true
  serviceMonitor:
    enabled: true

# values.yaml
architecture: replication

auth:
  postgresPassword: 'my-secret-password'
  database: myapp
  username: myuser
  password: 'user-password'
  replicationPassword: 'repl-password'

replication:
  primary:
    persistence:
      enabled: true
      size: 20Gi
  readReplicas:
    replicaCount: 2
    persistence:
      enabled: true
      size: 20Gi

# values.yaml
architecture: standalone

auth:
  postgresPassword: 'my-secret-password'
  database: myapp

standalone:
  persistence:
    enabled: true
    size: 20Gi

backup:
  enabled: true
  schedule: '0 3 * * *'
  s3:
    endpoint: https://s3.amazonaws.com
    bucket: my-pg-backups
    accessKey: '<set-me>'
    secretKey: '<set-me>'

# values.yaml
architecture: standalone

auth:
  postgresPassword: 'my-secret-password'
  database: myapp

standalone:
  persistence:
    enabled: true
    size: 20Gi

tls:
  enabled: true
  existingSecret: postgresql-tls
  sslMode: require

Operational Notes

• The chart keeps internal health checks, metrics, and built-in backup on PostgreSQL’s standard postgres database.
• If a reused PVC contains a valid data directory but is missing the default postgres database, the primary pod repairs that database during startup before normal readiness checks rely on it.
• auth.database remains the application bootstrap database. It is created only on first initialization of a fresh data directory.
• docker-entrypoint-initdb.d scripts only run when the data directory is empty. Existing PVCs keep their current roles and databases during upgrades.

Dual-stack Networking

PostgreSQL Services accept Kubernetes dual-stack configuration. By default, both service.ipFamilyPolicy and service.ipFamilies are unset and the chart inherits whatever the cluster advertises (matching prior behavior). Setting them propagates to every chart-managed Service: client, primary, replicas, metrics, and the headless StatefulSet services.

service:
  ipFamilyPolicy: PreferDualStack
  ipFamilies:
    - IPv4
    - IPv6

PreferDualStack is the safer choice for clusters that may be single- or dual-stack: omit ipFamilies and the cluster auto-populates whatever it supports. Set ipFamilies explicitly only when the cluster is configured for both families — the Kubernetes API rejects an explicit family the cluster does not advertise. RequireDualStack enforces both.

Configuration Reference

This reference covers the complete values.yaml surface for the PostgreSQL chart.

Core

Image

Authentication

PostgreSQL Configuration

TLS

Initialization

Standalone

Replication - Primary

Replication - Read Replicas

Replication - WAL, PDB, and Scheduling

Service

Metrics

Backup

NetworkPolicy

Pod Disruption Budget

Service Account

Probes

Scheduling and Security

Extra

Upgrade Notes

• When switching from standalone to replication, set auth.replicationPassword before upgrading
• PVC resize requires the storage class to support volume expansion (allowVolumeExpansion: true)
• Metrics sidecar changes may cause a pod restart during upgrade

Common Issues

More Information

• Blog guide: Deploy Production-Ready PostgreSQL on Kubernetes
• PostgreSQL Official Website
• PostgreSQL Official Documentation
• PostgreSQL Docker Official Image
• HelmForge PostgreSQL Chart Source