PostgreSQL bootstrap scripts and custom configuration — synthesized helm
core/datastore/postgres exposes two optional developer values that shape the
database’s first start: init_scripts (SQL or shell run once on initialization)
and custom_config (a postgresql.conf fragment). On the synthesized helm
target, the Recipe carries them into the container as mounted ConfigMaps. This
example shows the feature is additive: an Aggregate that sets neither value
renders exactly as a minimal database does, and an Aggregate that sets them gains
the ConfigMaps, volumes, and mounts with nothing else disturbed.
Two Releases of the same Component, same Manifest, differing only in the developer values:
release-bare.yaml(aggregate-bare.yaml) —init_scriptsandcustom_configunset.release-config.yaml(aggregate-config.yaml) — both set.
Scaffold the example
You can build this example with the commands below, or have your AI assistant build it for you.
Write the example into a new folder named after it:
aggrega scaffold --example postgres-init-configIt then prints the commands to run next. The first changes into the new folder:
cd postgres-init-configBuild
aggrega build --release release-bare.yaml --auto-pullaggrega build --release release-config.yaml --auto-pullThe catalog resolves from the hub registry named in .aggrega-config.yaml,
so no --catalog flag is needed, and --auto-pull writes the lockfile a fresh
clone lacks during the build. The bare release writes three files under
dist/helm/helm/; the configured release writes those three plus two more under
dist/helm/helm/db/.
With an AI assistant
An AI assistant set up with Aggrega’s tools can do the same: paste this prompt into it.
Use the Aggrega tools only, and create no folder yourself. If the Workspace folder holds no `postgres-init-config` folder yet, call the `scaffold` tool once with `example` set to `postgres-init-config` and no `dir`: it writes the example into a new `postgres-init-config` folder. Then call the `build` tool once for each Release, in this order — `release-bare.yaml` and `release-config.yaml` — each time with `workspace_root` set to `postgres-init-config`, `release` set to that file, `auto_pull` set to true and `write` set to true. Tell me which files each build wrote; they are under `postgres-init-config/dist/`.Bare — the additive baseline
aggregate-bare.yaml leaves both values unset. The rendered output is a
StatefulSet, a ClusterIP Service, and a Headless Service — no ConfigMap, no
configmap volume, no volume mount into the init directory, and no config-file
argument on the container. This is the ordinary shape of a minimal PostgreSQL
database:
dist/helm/helm/db-statefulset.yamldist/helm/helm/db-default-service.yamldist/helm/helm/db-headless-service.yamlBecause both values are presence-guarded in the Recipe, an unset value emits nothing — the ConfigMap body renders empty and is skipped, and the volume, mount, and server-argument lines are guarded out. An Aggregate that never touches these values is unchanged by their existence.
Configured — scripts and configuration mounted
aggregate-config.yaml sets both values:
values: init_scripts: 01-schema.sql: | CREATE TABLE app_users ( ... ); 02-seed.sql: | INSERT INTO app_users (email) VALUES ('founder@example.com'); custom_config: | max_connections = 200 shared_buffers = 256MBThe build now writes two additional ConfigMaps and wires them into the StatefulSet:
dist/helm/helm/db/initdb-configmap.yamldist/helm/helm/db/config-configmap.yamlBoth sit under db/, the component’s own name. The Recipe names them in its
artifacts: block, and a file named there carries the key its author wrote
rather than anything identifying the component — so the build writes it under the
component that declared it, and two components sharing one Recipe cannot land on
one path. The StatefulSet and the two Services are named by the target from the
component they belong to, so they stay at the boundary’s own directory.
The two values ride in separate ConfigMaps because each mounts whole into a different container path:
init_scripts→ ConfigMapdb-initdb, one data key per script (01-schema.sql,02-seed.sql). Aconfigmapvolume mounts it at/docker-entrypoint-initdb.d, where PostgreSQL runs the files once on first initialization, in alphabetical key order.custom_config→ ConfigMapdb-config, one data keypostgresql.conf. A secondconfigmapvolume mounts it at/etc/postgresql, and the container’sargs:point the server at it:postgres -c config_file=/etc/postgresql/postgresql.conf. Settings the fragment omits keep their built-in defaults.
# db-statefulset.yaml (container)containers: - name: main image: postgres:16 args: - postgres - -c - config_file=/etc/postgresql/postgresql.conf [… omitted: the container's port, environment and resources] volumeMounts: - name: data mountPath: /var/lib/postgresql/data - name: initdb mountPath: /docker-entrypoint-initdb.d - name: pgconf mountPath: /etc/postgresql [… omitted: the liveness and readiness probes]volumes: - name: initdb configMap: name: db-initdb - name: pgconf configMap: name: db-configThose server arguments arrive as args: rather than as command:, and the
difference decides whether the database comes up populated: args: supplies
arguments to the image’s entrypoint, while command: replaces it. That
entrypoint is the startup script that creates the database on an empty data
directory, reads the POSTGRES_* environment, and runs the files under
/docker-entrypoint-initdb.d. Replacing it would start the server against the
mounted postgresql.conf and skip both the initialization and the bootstrap
scripts — the values the Aggregate set would render into the manifest and never
run.
Setting only one of the two values is equally valid — the other’s ConfigMap,
volume, and mount are simply absent, and the config-file argument appears only
when custom_config is set.
Compose
The Compose Recipe for core/datastore/postgres reads the same Component and
realizes both values through compose’s own primitive: it renders top-level
configs: entries, and the service mounts each one as a file.
init_scripts→ one config per key, each mounted at its own filename under/docker-entrypoint-initdb.d. The image runs the files it finds there once, in filename order, and only when the data directory is empty — a database that already holds data is left untouched.custom_config→ one config, mounted as the single file/etc/postgresql/postgresql.conf, with the samepostgres -c config_file=…arguments pointing the server at it. Settings the fragment omits keep their built-in defaults.
Each half is presence-guarded here too, so an Aggregate that leaves one value unset renders as though that key did not exist.
One setting is worth naming when writing a custom_config block for a compose
deployment: listen_addresses accepts local connections only by default, so a
block that omits it leaves the database unreachable from the other services on
the compose network.
The Manifest in this example routes core/datastore/postgres to the helm Recipe.
Building the same Aggregate on compose means a Manifest that routes it to
compose/postgres instead; the developer values are untouched.