PostgreSQL as Metadata Store

Starting with Ververica Platform 3.1.1, you can use PostgreSQL 15+ as the metadata persistence backend instead of MySQL or MariaDB. This page explains how to configure, operate, and troubleshoot a PostgreSQL-backed Ververica Platform installation.

Supported Versions

PostgreSQL wire-compatible databases such as EnterpriseDB are also supported. Set global.database.provider to postgresql for these deployments.

Helm Configuration

The following example shows a complete PostgreSQL database configuration. Only provider, host, port, user, and password are required. All other fields are optional.

1global:
2  database:
3    provider: postgresql          # mariadb | mysql | postgresql
4    host: my-postgres.example.com
5    port: 5432
6    user: vvp
7    password: "<your-password>"
8    createIfMissing: true         # requires CREATEDB privilege. Set to false to pre-create databases manually.
9    urlParams: "?ssl=true&sslmode=require"  # optional. Include the leading "?".
10    initContainer:
11      image: harbor.internal.example.com/library/postgres:15-alpine
12      imagePullPolicy: IfNotPresent

The following sections describe each configuration option in detail.

provider

Set to postgresql for PostgreSQL and PostgreSQL wire-compatible backends. The values mariadb and mysql are equivalent and represent the default behavior from previous releases. Existing MySQL and MariaDB deployments do not require any changes.

passwordSecret

passwordSecret and passwordSecretKey work the same way for every supported provider value: PostgreSQL, MySQL, and MariaDB. Set passwordSecret to the name of an existing Kubernetes Secret that holds the database password. When set, Ververica Platform reads the password from that Secret's passwordSecretKey field instead of the plaintext password field, and it skips creating its own database-credentials Secrets.

Create the Secret in the release namespace before you install or upgrade the chart. The chart doesn't check that the Secret exists, so a missing Secret makes the pod fail at startup instead of failing the install.

Use this option to source the password from an external secrets manager, such as Vault, AWS Secrets Manager, or the External Secrets Operator, without passing it as plaintext through --set or values.yaml.

1global:
2  database:
3    provider: postgresql   # or mysql / mariadb
4    passwordSecret: my-db-creds
5    passwordSecretKey: dbpass   # optional, defaults to "password"

Leave passwordSecret unset, the default, to keep using the plaintext password field. Existing installations are unaffected.

createIfMissing

Controls whether Ververica Platform automatically creates the required service databases on startup if they do not exist. When provider is set to postgresql, the configured database user must have the CREATEDB privilege for automatic creation to work.

If CREATEDB is unavailable, set createIfMissing: false and create the databases manually before installing the chart. See Manual Database Creation.

urlParams

A JDBC query string appended verbatim to the connection URL. Use this field to pass connection parameters such as TLS settings. See TLS/SSL Configuration for an example.

initContainer

Overrides the image used by the database-creation init container. This init container only runs when provider is set to postgresql and createIfMissing is true. Use this option in air-gapped or private-registry environments that cannot pull docker.io/postgres:15-alpine.

Registry authentication is handled by the pod's image pull secrets, configured once via the chart's imagePullSecretName. No separate field is needed. See Air-Gapped Environments for an example.

Manual Database Creation

If the database user does not have the CREATEDB privilege, set createIfMissing: false in your values.yaml file and create the following databases before installing the chart:

1CREATE DATABASE "vvp-appmanager"  OWNER vvp;
2CREATE DATABASE "vvp-autopilot"   OWNER vvp;
3CREATE DATABASE "vvp-meta"        OWNER vvp;
4CREATE DATABASE "vvp-gateway"     OWNER vvp;
5CREATE DATABASE "vvp-advisor"     OWNER vvp;
6CREATE DATABASE "vvp-premise"     OWNER vvp;
7CREATE DATABASE "vvp-k8soperator" OWNER vvp;
8CREATE DATABASE "accesscontrol"   OWNER vvp;

Replace vvp with the username configured in global.database.user.

TLS/SSL Configuration

To enable TLS for the PostgreSQL connection, use the urlParams field:

1global:
2  database:
3    provider: postgresql
4    urlParams: "?ssl=true&sslmode=require"

The query string is appended verbatim to the JDBC connection URL. Refer to your PostgreSQL provider's documentation for the full list of supported JDBC parameters.

Air-Gapped Environments

In environments that cannot pull images from docker.io, use initContainer.image to specify a mirrored image:

1global:
2  database:
3    provider: postgresql
4    createIfMissing: true
5    initContainer:
6      image: harbor.internal/library/postgres:15-alpine
7      imagePullPolicy: IfNotPresent

Registry authentication uses the pod's existing image pull secrets, configured via the chart's imagePullSecretName.

Alternatively, set createIfMissing: false and create the databases manually as described in Manual Database Creation.

Operational Guidelines

Backup and Restore

Use standard PostgreSQL backup tooling for your deployment:

• Self-managed instances: use pg_dump and pg_restore.
• Managed services (such as AWS RDS, Azure Database for PostgreSQL, or Google Cloud SQL): use the automated snapshot features provided by your cloud provider.

Back up all eight service databases listed in Manual Database Creation.

For what accumulates in these databases over time, how to control that growth, and how to reclaim disk space and monitor it, see Metadata Database Operations.

Troubleshooting

Connection Refused or Authentication Failure

Verify the following:

• global.database.host, global.database.port, global.database.user, and global.database.password are correct.
• global.database.provider is set to postgresql. Using the default value (mariadb or mysql) against a PostgreSQL server causes connection errors.
• The PostgreSQL server is configured to accept connections from the Kubernetes cluster. Check pg_hba.conf or your firewall rules.

Database Creation Fails at Startup

If Ververica Platform pods fail to start with errors indicating that service databases could not be created, check whether the database user has the CREATEDB privilege:

1SELECT rolcreatedb FROM pg_roles WHERE rolname = '{your-db-user}';

If the user lacks the privilege, either grant it or create the databases manually and set createIfMissing: false. See Manual Database Creation.

SSL/TLS Handshake Errors

If you see SSL-related errors in the application logs, check the following:

• The urlParams value is a valid JDBC query string starting with ?.
• The PostgreSQL server has SSL enabled.
• The server certificate is trusted by the Java runtime in the Ververica Platform containers. For self-signed certificates, you might need to add &sslmode=verify-ca and supply a trust store.