---
title: How to Access the PostgreSQL Database Behind Your ZITADEL Helm Deployment
description: Learn how to get direct admin access to the PostgreSQL database powering your ZITADEL Helm installation, locate credentials, connect with psql, and avoid common pitfalls.
---

[Skip to content](https://help.zitadel.com/how-to-access-the-postgresql-database-behind-your-zitadel-helm-deployment#main-content)

[![zitadel-logo\_text-dark (1)](https://help.zitadel.com/hs-fs/hubfs/zitadel-logo_text-dark%20(1).png?width=210&height=60&name=zitadel-logo_text-dark%20(1).png)](https://help.zitadel.com/?hsLang=en)

Open main navigation

Close main navigation

- [Documentation](https://zitadel.com/docs)

[Documentation](https://zitadel.com/docs)

 How can we help you?

- There are no suggestions because the search field is empty.

1. [ZITADEL Knowledge Base](https://help.zitadel.com/?hsLang=en)
2. [Self-Hosting](https://help.zitadel.com/self-hosting?hsLang=en)

August 5, 2025

# 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 Postgreskubectl 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](https://raw.githubusercontent.com/zitadel/zitadel-charts/main/examples/2-postgres-secure/postgres-values.yaml))

### 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 zitadelPGPASSWORD=<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`).

- [Getting Started](https://help.zitadel.com/getting-started?hsLang=en)
- [User Management](https://help.zitadel.com/user-management?hsLang=en)
- [Authentication & Login](https://help.zitadel.com/authentication-login?hsLang=en)
- [Security & Compliance](https://help.zitadel.com/security-compliance?hsLang=en)
- [Troubleshooting](https://help.zitadel.com/troubleshooting?hsLang=en)
- [Account & Subscription](https://help.zitadel.com/account-subscription?hsLang=en#main-content)

    - [Support](https://help.zitadel.com/account-subscription?hsLang=en#support)
    - [Billing (Pro)](https://help.zitadel.com/account-subscription?hsLang=en#billing-pro)
    - [Billing (Enterprise)](https://help.zitadel.com/account-subscription?hsLang=en#billing-enterprise)
    - [Zitadel Cloud Account](https://help.zitadel.com/account-subscription?hsLang=en#zitadel-cloud-account)
    - [Service Description](https://help.zitadel.com/account-subscription?hsLang=en#service-description)
- [Default Settings](https://help.zitadel.com/default-settings?hsLang=en#main-content)

    - [Web Keys](https://help.zitadel.com/default-settings?hsLang=en#web-keys)
- [Self-Hosting](https://help.zitadel.com/self-hosting?hsLang=en)

[![zitadel-logo\_text-dark](https://help.zitadel.com/hs-fs/hubfs/zitadel-logo_text-dark.png?width=210&height=60&name=zitadel-logo_text-dark.png "zitadel-logo_text-dark")](http://zitadel.com)

1 Embarcadero Center, Suite 1200  
San Francisco, CA 94111

<https://github.com/zitadel/zitadel> <https://x.com/zitadel> <https://www.facebook.com/zitadel.social> <https://www.linkedin.com/company/zitadel/> <https://zitadel.com/chat> <https://www.youtube.com/@zitadel>

Copyright © 2025 All rights reserved.