Skip to content
OpenCharly

postgresql

Recipe card from the charly-infrastructure plugin (Images — the deployable catalog).

postgresql – PostgreSQL database server

Section titled “postgresql – PostgreSQL database server”

Candy Properties

Section titled “Candy Properties”
Property Value
Dependencies none
Ports 5432
Volumes pgdata -> ~/.postgresql/data
Service postgresql (supervisord, priority 10)
Install files plan:

Environment Variables

Section titled “Environment Variables”
Variable Value
PGDATA ~/.postgresql/data
POSTGRES_HOST_AUTH_METHOD scram-sha-256
POSTGRES_SHARED_PRELOAD_LIBRARIES (optional) — comma-separated .so names loaded at startup

The entrypoint also reads these variables (with defaults, not set in charly.yml):

  • POSTGRES_USER (default: postgres) — set by consuming candies (e.g., immich sets immich)
  • POSTGRES_DB (default: $POSTGRES_USER) — set by consuming candies
  • POSTGRES_PASSWORD — required unless POSTGRES_HOST_AUTH_METHOD=trust

Service Environment (injected into other containers)

Section titled “Service Environment (injected into other containers)”
Variable Template Value Resolved Example
PGHOST {{.ContainerName}} charly-postgresql
PGPORT 5432 5432

Pod-aware: same-container consumers receive PGHOST=localhost, cross-container consumers receive PGHOST=charly-postgresql. When charly config runs, these are automatically injected into the global charly.yml env for PostgreSQL service discovery.

See /charly-image:layer for env_provide field docs.

Packages

Section titled “Packages”

The candy is multi-distro:

  • RPM (Fedora): postgresql-server, postgresql-contrib, pgvector (vector similarity search extension)
  • PAC (Arch/CachyOS): postgresql, postgresql-libs — the Arch postgresql package ships the server + contrib tooling; pgvector on Arch is built from the AUR (see /charly-infrastructure:vectorchord).

Usage

Section titled “Usage”
# charly.yml — a box composes postgresql via an inline candy: list in its body
my-image:
  candy:
    base: fedora
    candy: [postgresql]

Used In Boxes

Section titled “Used In Boxes”

Entrypoint Features

Section titled “Entrypoint Features”

The custom entrypoint (/usr/local/bin/postgresql-entrypoint.sh) supports:

  • First-run initialization — initdb, database creation, and /docker-entrypoint-initdb.d/ scripts
  • Password management — POSTGRES_PASSWORD or POSTGRES_PASSWORD_FILE
  • POSTGRES_SHARED_PRELOAD_LIBRARIES — when set, adds -c shared_preload_libraries=... to both the init-phase temp server and the final exec. Used by the vectorchord candy to load vchord.so. Generic mechanism — any extension candy can use it.
Section titled “Related Candies”
Section titled “Related Commands”

When to Use This Skill

Section titled “When to Use This Skill”

Use when the user asks about:

  • PostgreSQL database setup in containers
  • pgvector extension
  • Database volume or PGDATA configuration
  • Port 5432 service
  • Database initialization
Section titled “Related”
  • /charly-check:check — declarative testing (check: block, charly check box, charly check live)