Skip to content
Documentation
  • There are no suggestions because the search field is empty.

How to Access the PostgreSQL Database Behind Your ZITADEL Helm Deployment

Port-forward or run an in-cluster client to open a psql prompt—without breaking best-practice safety rules

Nothing in the Helm chart prevents you from talking directly to the PostgreSQL server that backs your ZITADEL instance. All the chart does is pass a connection string to ZITADEL; the database itself is just another Kubernetes workload (or an external service you pointed ZITADEL at).

Below is the typical way to get a psql prompt when you use the Bitnami PostgreSQL example or any other in-cluster Postgres release; adjust names/namespaces to your setup.

1. Identify the Postgres Service and Secret

# List services in the namespace where you installed Postgres

kubectl get svc -n zitadel

# Get the autogenerated postgres password (Bitnami chart)

kubectl get secret db-postgresql -n zitadel \

  -o jsonpath='{.data.postgresql-password}' | base64 -d

In the “secure-Postgres” example the Helm chart explicitly sets auth.postgresPassword: "abc"; that same value is stored in the db-postgresql secret created by the Bitnami sub-chart. (GitHub)

2. Port-forward or Exec into a psql Pod

Option A – Port-forward from your laptop

kubectl port-forward svc/db-postgresql 5432:5432 -n zitadel

PGPASSWORD=<password-from-secret> psql -h 127.0.0.1 -U postgres -d zitadel

Option B – Temporary psql client inside the cluster

kubectl run -i --rm psql \

  --env PGPASSWORD="$(kubectl get secret db-postgresql -n zitadel \

                        -o jsonpath='{.data.postgresql-password}' | base64 -d)" \

  --image postgres:15 --restart=Never -- \

  psql -h db-postgresql -U postgres -d zitadel

Whether to port-forward or to exec into the pod will depend on your use case. If you just want to execute a command or run a query from time to time, you can exec into the pod and use the already installed and authenticated psql there.

If you want full IDE support, probably it's better to connect via port-forward or even an exposed service.

3. Safety & Support Caveats

  • Read-only is fine. Manually changing data in ZITADEL tables is not recommended, this can corrupt projections or event sequences. We won't provide support for issues caused by these changes.

  • Back up first. If you do need to touch the schema for any reason, take a snapshot and test in a staging cluster.

4. External Postgres

If your Helm values point to an external RDS/Aurora/Cloud SQL instance instead of the Bitnami chart, just connect with any Postgres client using the hostname/port you supplied in Database.postgres.* (the steps are the same; you simply skip the kubectl port-forward).