PostgreSQL

Koldan requires a durable PostgreSQL database. The Helm chart can install PostgreSQL for a self-contained deployment, or connect Koldan to an operator-managed PostgreSQL service.

Choose the deployment model

Set postgresql.install: true to install the chart dependency. Review its credentials, persistent-volume size and storage class, backup settings, and availability characteristics before using it for persistent environments.

Set postgresql.install: false for an external service. Disabling the dependency does not configure Koldan automatically: you must supply the datasource properties and provision the database first.

For either model, define recovery point and recovery time objectives, an upgrade owner, maintenance windows, monitoring, and a tested restore procedure. A PersistentVolume protects against a pod replacement; it is not a database backup.

Provision an external database

Create a dedicated database and login for Koldan. The login must be able to connect and perform the schema changes required by the installed release. Do not grant PostgreSQL superuser or cluster-administration privileges. If Keycloak or bundled Temporal uses the same PostgreSQL service, create separate databases and credentials for each.

Configure the supported datasource properties through the chart:

postgresql:
  install: false

config: |
  spring:
    datasource:
      url: jdbc:postgresql://postgresql.example.net:5432/koldan?sslmode=verify-full
      username: <database-user>
      password: <injected-database-password>

The password placeholder must be populated through the controlled secret-delivery process described in Configuration and secrets. Because config is rendered into a ConfigMap, do not commit or persist a populated example as an ordinary values file.

For sslmode=verify-full, the certificate must be trusted and contain the PostgreSQL hostname in its SAN. Add a private issuing CA through TLS and custom CAs. Do not use sslmode=disable or hostname-bypassing modes for an external production database.

Install pgvector

The Koldan database requires the PostgreSQL vector extension supplied by pgvector. The PostgreSQL image selected by the bundled chart includes pgvector. For an external or managed PostgreSQL service, confirm that the service and selected PostgreSQL version support pgvector before installation.

Koldan's database migration attempts to run CREATE EXTENSION IF NOT EXISTS vector, but the application login should not be granted superuser or service-administration privileges solely for extension installation. Have a database administrator install the extension in the Koldan database before the first Koldan startup:

CREATE EXTENSION IF NOT EXISTS vector;

Verify the extension in the target database:

SELECT extname, extversion
FROM pg_extension
WHERE extname = 'vector';

The query must return one row. Run it while connected to the Koldan database, not only to the PostgreSQL service's default administration database.

For self-managed PostgreSQL, install a pgvector package compatible with the PostgreSQL major version on every database server before creating or restoring the extension. For a managed service, enable the provider-supported extension and record its version with the deployment. Before upgrading PostgreSQL or pgvector, test the Koldan schema migration and representative database operations on a restored copy.

Size connection capacity

Budget connections before increasing replicas or concurrency. The chart exposes these per-pod Hikari limits:

• web.hikari.maximumPoolSize and web.hikari.minimumIdle
• grpc.hikari.maximumPoolSize and grpc.hikari.minimumIdle
• workerPools.<pool>.hikari.maximum-pool-size and workerPools.<pool>.hikari.minimum-idle
• The corresponding Hikari values for other enabled chart workloads

Use the rendered chart to inventory every enabled replica and pool. A conservative upper bound is:

Koldan maximum connections = sum(replica count × maximum pool size)
required max_connections   = Koldan maximum
                           + Keycloak and Temporal pools
                           + migration and administration sessions
                           + monitoring and backup sessions
                           + failover headroom

Do not calculate from minimumIdle; a pool can grow to its maximum. Ensure the database connection limit, CPU, memory, and I/O can sustain the resulting concurrency. A connection pooler does not remove the need to budget backend transactions and locks.

Apply and verify

Before a connection or credential change, take a restorable backup and confirm the rollback credential remains valid. Render and review the chart, apply the Helm upgrade, and then verify:

• DNS and TCP reachability from the Koldan namespace.
• TLS chain and hostname validation.
• Authentication and database selection.
• Successful application startup and schema validation or migration.
• Ready replicas, stable connection count, acceptable query latency, and no unexpected lock growth.
• A representative read and write operation through Koldan.

Rotate credentials with an overlap period where PostgreSQL policy permits: create or change the credential, update and roll Koldan, verify every replica, then revoke the previous credential.

Operate and recover

Monitor active and waiting connections, saturation, transaction latency, locks, deadlocks, disk and WAL growth, replication lag, failed backups, and backup age. Test restoration into an isolated environment on a schedule and record the PostgreSQL and pgvector versions required by the restore. The target database servers must have compatible pgvector software available before restoring a database that uses the vector extension.

Restore PostgreSQL consistently with object storage and Temporal persistence when recovering the complete deployment to a point in time. Stop or isolate writers during a coordinated restore. After recovery, run the same startup and representative read/write checks used after installation.