Database Configuration

Conncentric uses PostgreSQL to store everything: adapter configurations, artifacts, plugin files, and operational state. You provision the database before installing Conncentric, and the platform manages its own tables from there.

Conncentric supports PostgreSQL 15 and later. See Version Compatibility for the authoritative list of supported database versions.

Setting Up the Database

Create a dedicated database and user. Run this block while connected as a database administrator (the master or superuser account your provider issued when the instance was created), not as the application user:

CREATE USER conncentric WITH PASSWORD 'your-password';
CREATE DATABASE conncentric OWNER conncentric;
GRANT ALL PRIVILEGES ON DATABASE conncentric TO conncentric;

Because this block makes conncentric the owner of the database, that user can create and manage its own tables inside the database during normal operation. The administrative role is only needed to run the one-time setup above; the platform does not need it while running.

On a managed service the connecting administrator must hold the provider's administrative role:

Provider	Administrative role
AWS RDS / Aurora PostgreSQL	rds_superuser
Google Cloud SQL for PostgreSQL	cloudsqlsuperuser
Azure Database for PostgreSQL	azure_pg_admin

The master user each managed service creates with the instance is normally already a member of that role.

Automatic Schema Setup

The platform manages its own schema. You don't run any SQL scripts manually. Schema changes are applied by a dedicated migration Job that Helm runs before the application pods, not by the Orchestrator at startup. On a fresh install the Job creates the tables; on an upgrade it runs again and applies only what has changed since the last version. If the migration fails, the install or upgrade stops and the Orchestrator pods never start, so a broken schema change can never reach a running control plane.

New database versions are designed to be backward-compatible with the previous release, so you can roll out upgrades one pod at a time without taking anything offline.

Verifying the Connection

After you deploy, confirm both the migration Job and the Orchestrator reached the database:

• The schema migration Job completes. The pre-install (and pre-upgrade) migration Job applies the schema before the Orchestrator starts. If it fails, the release stops and the Orchestrator pods never start, so an install that hangs before any application pod is running points here first. Read the migrator logs (the Job is retained on failure; on success it is cleaned up):

  kubectl logs -l app.kubernetes.io/component=migrator -n conncentric

• The Orchestrator pod becomes 1/1 Ready. Its readiness check does not pass until the platform has connected to the database, so a Ready Orchestrator is a dependable signal that the connection succeeded.

• The Orchestrator logs show a successful database-connection line at startup. A repeated Connection refused or authentication error instead points to a wrong host, an endpoint the cluster cannot reach, or bad credentials:

  kubectl get pods -n conncentric
  kubectl logs deploy/conncentric-orchestrator -n conncentric --tail=200

See the Kubernetes Reference for the expected pod inventory and health checks, and Troubleshooting if the connection does not come up.

Helm Configuration

Database connection details are set under the shared database key at the root of your values file. Both the Orchestrator and Adapter read from this section.

database:
  host: "postgres.example.com"
  port: 5432
  name: "conncentric"
  auth:
    username: "conncentric"
    password: "your-password"

Using a Kubernetes Secret (Recommended for Production)

Don't put passwords directly in your values file. Reference a Kubernetes Secret instead:

database:
  host: "postgres.example.com"
  port: 5432
  name: "conncentric"
  auth:
    existingSecret: "conncentric-db-credentials"

Create the secret before deploying:

kubectl create secret generic conncentric-db-credentials \
  --from-literal=username=conncentric \
  --from-literal=password=your-password \
  -n conncentric

Managed Database Services

Conncentric requires a PostgreSQL 15+ endpoint. We support Amazon RDS for PostgreSQL; the other services below are not validated and are not supported by default (contact us to discuss). See Version Compatibility:

Provider	Service
AWS	RDS for PostgreSQL, Aurora PostgreSQL
Google Cloud	Cloud SQL for PostgreSQL
Azure	Azure Database for PostgreSQL – Flexible Server

When using a managed service, make sure the platform pods can reach the database endpoint from inside your cluster, and review Transport Security (TLS) below.

Sizing and capacity

Size the database for your deployment. The platform does not provision or enforce database capacity, and an undersized database surfaces as platform latency or connection errors rather than an obvious database fault, so treat sizing as your responsibility and validate it against your expected volume before production. As guidance:

• Connections: provision enough server connections for every pod that connects (the orchestrator and adapter replicas) times each pod's connection-pool size, plus headroom for the short-lived migration and installer Jobs and for rolling upgrades where old and new pods briefly overlap. A connection ceiling set too low shows up as pods failing to start or intermittent query failures under load.
• Storage and throughput: the database holds all configuration, artifacts, plugin files, and the event log, and the event log grows with traffic. The platform trims archive and event rows on a configurable retention schedule (archive.retention in the Helm values, enabled by default), so bounded growth depends on that retention staying enabled and sized to your volume. Provision storage headroom and disk throughput for your message and event volume, and monitor growth. Slow or exhausted disk shows up as pipeline and Portal latency.
• Compute: size CPU and memory for your concurrent connection and query load, following your database provider's guidance.

Transport Security (TLS)

The platform connects to PostgreSQL using the driver's default TLS negotiation against a TLS-enabled server. Whether a given connection is encrypted, and whether unencrypted connections are refused, is controlled on the database side rather than by the platform. Enable TLS on your database or managed service and enforce it there, for example by requiring SSL connections through the server configuration or parameter group. On most managed services TLS is enabled by default.

The chart exposes database.sslMode, appended to the JDBC URL as the sslmode parameter. It is empty by default, which uses the driver default (prefer), and prefer allows a silent plaintext fallback when the server does not require TLS. Set database.sslMode: require to force encryption. verify-ca and verify-full additionally verify the server certificate, which requires the certificate authority to be available to the pods; supply that (and any custom CA) at the database or managed-service layer, or mount it into the pods.

Data at rest

Data at rest lives in your PostgreSQL database, so encryption at rest is a property of that database and your responsibility to enable (an encrypted storage class, or your managed service's encryption option). The platform does not add a separate at-rest encryption layer.

Backup and Recovery

Conncentric doesn't manage database backups. Use your database provider's backup tools:

• RDS: Automated snapshots + point-in-time recovery
• Cloud SQL: Automated backups with configurable retention
• Self-managed: Regular pg_dump exports

All platform data (configurations, artifacts, plugins) lives in the database. A successful database restore is all you need to recover the platform.