> ## Documentation Index
> Fetch the complete documentation index at: https://controlplanecorporation-majid-docs-content-expansion.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# DBeaver

> Deploy DBeaver CloudBeaver on Control Plane using the Template Catalog. A browser-based SQL client and database administration console with a persistent workspace, an admin password held in a prerequisite secret, and no public access by default.

## Overview

DBeaver is a web-based database administration tool that provides a modern interface for managing multiple database connections. This template deploys the self-hosted [CloudBeaver](https://github.com/dbeaver/cloudbeaver) web application — the browser-based edition of DBeaver — giving you a full-featured SQL editor, connection manager, and data browser for PostgreSQL, MySQL, MariaDB, MongoDB, Redis, SQLite, Oracle, SQL Server, and more.

The admin account is bootstrapped from an [opaque secret](/guides/create-secret/opaque) you create before installing, and the console is reachable only from inside the GVC unless you deliberately publish it.

<Warning>
  **Version 1.3.0 is a security fix. Read [Upgrading From 1.2.1 or Earlier](#upgrading-from-1-2-1-or-earlier) before you upgrade.** Versions up to 1.2.1 shipped a working admin password (`Password123`) as a `values.yaml` default and hardcoded the workload's inbound firewall to `0.0.0.0/0` with no way to turn it off, so a default install published a database administration console to the internet behind a password published in a public repository. In 1.3.0 the password moved to a prerequisite secret and public access became an opt-in knob that defaults to off — **which changes the behavior of an existing install when you upgrade.**
</Warning>

### What Gets Created

* **Stateful CloudBeaver Workload** (`RELEASE_NAME-dbeaver`) — a single CloudBeaver instance serving the web UI and API on port `8978`.
* **Volume Set** (`RELEASE_NAME-dbeaver-vs`) — a 10 GiB `ext4` volume mounted at `/opt/cloudbeaver/workspace`, holding the server configuration, saved connections, and user accounts. A final snapshot is taken when the volume set is deleted and kept for 7 days; there are no scheduled snapshots.
* **Identity & Policy** — an identity bound to the workload and a policy granting it `reveal` on exactly the admin-password secret you created, and nothing else.
* **No template-created secret** — the only credential lives in the prerequisite secret you own.

<Note>
  This template does not create a GVC. You must deploy it into an existing GVC.
</Note>

## Prerequisites

**One [opaque secret](/guides/create-secret/opaque) must exist before you install.** The admin password guards a database administration console, and whoever holds it can query every database that console is connected to — so it is never a Helm value and never lands in the release.

<Steps>
  <Step title="Create the admin password secret">
    Choose your own strong password — use at least 8 characters — and store it as the secret's payload:

    ```bash theme={null}
    printf '%s' 'YOUR-STRONG-PASSWORD' | cpln secret create-opaque --name my-dbeaver-admin-password --encoding plain -f -
    ```

    Set `admin.passwordSecretName` to the name you used. The default in `values.yaml` is `my-dbeaver-admin-password`.
  </Step>

  <Step title="Pick an admin login name">
    Set `admin.name` to the login name you want. It is not sensitive and stays a plain value; the default is `cbadmin`.
  </Step>
</Steps>

<Warning>
  **A missing prerequisite secret wedges the install rather than failing it.** `cpln helm install` still exits 0 and reports success, all four resources are created, and the workload then never starts — it sits at zero replicas with the message `The secret <name> no longer exists. Workload updates are paused until the secret is added or the reference to the secret removed.` There are no container logs to diagnose from, because the container never ran. Create the secret first, and after installing confirm with `cpln workload get-deployments RELEASE_NAME-dbeaver --gvc GVC_NAME` rather than trusting the Helm output.
</Warning>

Nothing else is required for a default install.

## Installation

To install, follow the instructions for your preferred method:

<CardGroup cols={2}>
  <Card title="UI" href="/template-catalog/install-manage/ui" icon="laptop">
    Browse, install, and manage templates visually
  </Card>

  <Card title="CLI" href="/template-catalog/install-manage/cli" icon="terminal">
    Manage templates from your terminal
  </Card>

  <Card title="Terraform" href="/template-catalog/install-manage/terraform" icon={<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128"><g fill-rule="evenodd"><path d="M77.941 44.5v36.836L46.324 62.918V26.082zm0 0" fill="#5c4ee5"/><path d="M81.41 81.336l31.633-18.418V26.082L81.41 44.5zm0 0" fill="#4040b2"/><path d="M11.242 42.36L42.86 60.776V23.941L11.242 5.523zm0 0M77.941 85.375L46.324 66.957v36.82l31.617 18.418zm0 0" fill="#5c4ee5"/></g></svg>}>
    Declare templates in your Terraform configurations
  </Card>

  <Card
    title="Pulumi"
    href="/template-catalog/install-manage/pulumi"
    icon={<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" id="Pulumi-Icon--Streamline-Svg-Logos" height="24" width="24">
    <desc>
        Pulumi Icon Streamline Icon: https://streamlinehq.com
    </desc>
    <path fill="#f26e7e" d="M4.683025 13.3318c0.869125 -0.5018 0.870575 -2.1264 0.003225 -3.62865s-2.27504 -2.313275 -3.1441725 -1.811475C0.672945 8.3935 0.6715 10.0181 1.53885 11.52035c0.86735 1.502275 2.27505 2.313275 3.144175 1.81145Zm0.0052 3.2167c0.86735 1.502275 0.865925 3.126875 -0.003225 3.628675 -0.86915 0.5018 -2.2768275 -0.309225 -3.144175 -1.81145 -0.8673525 -1.50225 -0.8659075 -3.126875 0.003225 -3.628675 0.8691325 -0.5018 2.276825 0.309225 3.144175 1.81145Zm5.922875 3.4243c0.86735 1.50225 0.8659 3.126775 -0.003225 3.62875 -0.869125 0.501775 -2.27685 -0.309325 -3.1442 -1.81155 -0.867325 -1.50225 -0.865875 -3.12685 0.00325 -3.628675 0.869125 -0.5018 2.276825 0.309225 3.144175 1.811475Zm-0.001925 -6.845275c0.86735 1.50225 0.8659 3.12685 -0.003225 3.628675 -0.869125 0.5018 -2.276825 -0.309225 -3.144175 -1.811475 -0.86735 -1.50225 -0.8659 -3.12685 0.003225 -3.62865 0.869125 -0.501825 2.276825 0.3092 3.144175 1.81145Z" stroke-width="0.25"></path>
    <path fill="#8a3391" d="M22.45775 11.524125c0.86725 -1.502225 0.865925 -3.12685 -0.003225 -3.62865 -0.869125 -0.501825 -2.276825 0.3092 -3.144175 1.811475 -0.86735 1.50225 -0.8659 3.126825 0.003225 3.62865 0.869125 0.501825 2.276825 -0.3092 3.144175 -1.811475Zm0.000175 3.2151c0.869075 0.5018 0.870625 2.1264 0.003225 3.62865 -0.86735 1.50225 -2.27505 2.313275 -3.144175 1.81145 -0.869125 -0.5018 -0.870575 -2.126425 -0.003225 -3.62865 0.86735 -1.50225 2.27505 -2.313275 3.144175 -1.81145ZM16.536225 18.157875c0.86915 0.501825 0.8706 2.126425 0.00325 3.628675 -0.86735 1.502125 -2.275075 2.313225 -3.1442 1.81145 -0.869125 -0.50175 -0.870575 -2.126425 -0.003225 -3.62865 0.867375 -1.502275 2.27505 -2.3133 3.144175 -1.811475Zm-0.003325 -6.843775c0.869125 0.5018 0.870575 2.126425 0.003225 3.628675s-2.27505 2.313275 -3.1442 1.811475c-0.869125 -0.501825 -0.870575 -2.126425 -0.003225 -3.628675 0.86735 -1.502275 2.27505 -2.313275 3.1442 -1.811475Z" stroke-width="0.25"></path>
    <path fill="#f7bf2a" d="M15.138225 2.06721c0 1.003615 -1.40625 1.817215 -3.14095 1.817215 -1.7347 0 -3.14095 -0.8136 -3.14095 -1.817215C8.856325 1.06359 10.262575 0.25 11.997275 0.25c1.7347 0 3.14095 0.81359 3.14095 1.81721ZM9.2166 5.482375c0 1.003625 -1.40625 1.8172 -3.14095 1.8172 -1.7347 0 -3.14095 -0.813575 -3.14095 -1.8172s1.40625 -1.817225 3.14095 -1.817225c1.7347 0 3.14095 0.8136 3.14095 1.817225Zm8.71005 1.8172c1.7347 0 3.14095 -0.813575 3.14095 -1.8172s-1.40625 -1.817225 -3.14095 -1.817225c-1.7347 0 -3.14095 0.8136 -3.14095 1.817225s1.40625 1.8172 3.14095 1.8172Zm-2.788425 1.605625c0 1.003625 -1.40625 1.8172 -3.14095 1.8172 -1.7347 0 -3.14095 -0.813575 -3.14095 -1.8172 0 -1.0036 1.40625 -1.8172 3.14095 -1.8172 1.7347 0 3.14095 0.8136 3.14095 1.8172Z" stroke-width="0.25"></path>
    </svg>}
  >
    Declare templates in your Pulumi programs
  </Card>
</CardGroup>

## Configuration

The default `values.yaml` for this template:

```yaml theme={null}
image: dbeaver/cloudbeaver:25.2.0

# ─── Admin Login (prerequisite secret) ────────────────────────────────────────
# The admin password guards the CloudBeaver web login, and whoever holds it can
# reach every database this console is connected to — so it never transits
# values or the Helm release. Create the opaque secret (encoding: plain) BEFORE
# install; see README Prerequisites.
admin:
  name: cbadmin # admin login name (not sensitive)
  passwordSecretName: my-dbeaver-admin-password # opaque secret holding the admin password; must EXIST BEFORE INSTALL

# ─── Access ───────────────────────────────────────────────────────────────────
publicAccess:
  # false = not reachable from the internet. Setting this true publishes a
  # database administration console, and its login form, to the whole internet.
  enabled: false

internalAccess:
  type: same-gvc # options: none, same-gvc, same-org, workload-list
  workloads: [] # used with workload-list
  # workloads:
  #   - //gvc/GVC_NAME/workload/WORKLOAD_NAME

resources:
  cpu: 500m
  memory: 512Mi

volumeset:
  capacity: 10 # initial capacity in GiB (minimum is 10)
```

### Admin Credentials

* `admin.name` — the admin login name, created when the workspace is first initialized. Not sensitive, so it stays a plain value. Default `cbadmin`.
* `admin.passwordSecretName` — the name of the opaque secret holding the admin password. The chart references it as `cpln://secret/NAME.payload`, so the password itself never appears in the workload spec or the Helm release.

<Warning>
  **The admin password cannot be rotated by changing the secret.** Both credentials are consumed only when an empty workspace is initialized on the volume set. On every later boot CloudBeaver reads the account it already stored in its workspace database and ignores the environment. This was measured: after rewriting the secret's payload and restarting the workload, the container held the **new** value while the **old password still logged in** and the new one was rejected with `Invalid user credentials`.

  To change the password, use the CloudBeaver UI (**Administration → Users**), or uninstall — which deletes the volume set and every saved connection with it — and reinstall.
</Warning>

<Warning>
  **CloudBeaver logs the submitted password hash, and its API accepts that hash in place of the password.** At the image's default log level, login requests appear in `cpln logs` with the credential included, and replaying that value against the API authenticates successfully — so anyone who can read this workload's logs can log in as the admin. This is upstream CloudBeaver behavior, not something the chart configures; the move to a prerequisite secret does not close it. Treat log access to this workload as equivalent to admin access to every database it is connected to.
</Warning>

### Access

* `publicAccess.enabled` — when `true`, the workload's external inbound firewall opens to `0.0.0.0/0` and Control Plane assigns a `*.cpln.app` canonical endpoint. **Defaults to `false`.** With it off, requests to the canonical endpoint return `403 RBAC: access denied`.
* `internalAccess.type` — which workloads inside Control Plane may reach the console. **Defaults to `same-gvc`.**
* `internalAccess.workloads` — list of workload links, used only when `type` is `workload-list`.

| Type            | Description                                                               |
| --------------- | ------------------------------------------------------------------------- |
| `none`          | No internal access allowed                                                |
| `same-gvc`      | Allow access from all workloads in the same GVC                           |
| `same-org`      | Allow access from all workloads in the same organization                  |
| `workload-list` | Allow access only from the workloads listed in `internalAccess.workloads` |

<Note>
  **An access change takes up to a couple of minutes to take effect.** Firewall changes propagate asynchronously: enabling public access was measured at 107 seconds from upgrade to the first `200`, passing through `504` on the way, and disabling it at about 120 seconds, passing through `503` and `504` before settling on `403`. Re-poll before concluding the knob did nothing.

  A request blocked by `internalAccess.type: none` **hangs until your client times out** rather than being refused — the TCP connection is accepted by the local sidecar and no bytes are ever returned. "Connected, but no response" is what a correctly closed internal firewall looks like here.
</Note>

### Outbound Connectivity

The workload ships with an empty outbound firewall (`outboundAllowCIDR: []`), and there is no value to change it.

<Warning>
  **CloudBeaver can only reach databases inside its own GVC.** Outbound TLS connections to the public internet do not complete — measured as a connection reset during the TLS handshake (`curl` exit code 35) from the CloudBeaver container, while a control workload in the same GVC with open egress reached the same hosts normally. In practice this means **managed databases such as Amazon RDS, Google Cloud SQL, and MongoDB Atlas cannot be connected**. Point connections at in-GVC hosts over internal DNS instead, e.g. `my-postgres.GVC_NAME.cpln.local:5432`.

  Note that DNS still resolves and a bare TCP connect can appear to succeed, because the sidecar accepts the socket before the connection is reset — do not infer working egress from either.
</Warning>

### Resources and Storage

* `resources.cpu` / `resources.memory` — CPU and memory allocated to the CloudBeaver workload.
* `volumeset.capacity` — persistent volume size in GiB for workspace data, saved connections, and user accounts (minimum 10).

## Connecting

| Path                | Address                                                                                           | Notes                                                                                                                                                             |
| ------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Public UI           | `https://CANONICAL_ENDPOINT`                                                                      | Only when `publicAccess.enabled` is `true`. Read the endpoint from `status.canonicalEndpoint` in `cpln workload get RELEASE_NAME-dbeaver --gvc GVC_NAME -o yaml`. |
| Internal UI and API | `http://RELEASE_NAME-dbeaver.GVC_NAME.cpln.local:8978`                                            | Subject to `internalAccess.type`.                                                                                                                                 |
| Admin credentials   | `admin.name` from your values, plus the payload of the secret named in `admin.passwordSecretName` | Reveal it with `cpln secret reveal my-dbeaver-admin-password`.                                                                                                    |

Add database connections from the UI after logging in, pointing them at in-GVC hosts over internal DNS.

## Upgrading From 1.2.1 or Earlier

<Warning>
  **After upgrading, the console is no longer reachable from the internet, and your existing admin login is unchanged — both the name and the password stay whatever the workspace was first bootstrapped with.** In particular, keep logging in as your old admin name (`adminusername` if you never changed it); the new `cbadmin` default never applies to an existing workspace. Both behaviors are expected. Plan the upgrade rather than discovering it.
</Warning>

| Behavior             | 1.2.1 and earlier                                   | 1.3.0                                                                                                                                                                        |
| -------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Admin password       | `admin.password` value, defaulting to `Password123` | `admin.passwordSecretName`, naming an opaque secret you create                                                                                                               |
| Admin login name     | `admin.name`, defaulting to `adminusername`         | `admin.name`, defaulting to `cbadmin` — still a plain value, and the new default applies to new installs only; an existing workspace keeps the name it was bootstrapped with |
| Public access        | Hardcoded `0.0.0.0/0` inbound, no knob              | `publicAccess.enabled`, defaulting to `false`                                                                                                                                |
| Internal access      | Hardcoded `none`                                    | `internalAccess.type`, defaulting to `same-gvc`                                                                                                                              |
| Chart-created secret | A secret holding the admin name and password        | None — the chart creates no secret                                                                                                                                           |

What to do before upgrading:

<Steps>
  <Step title="Create the admin password secret">
    Even though it will not change the account you already log in with, the workload will not start without it. Use the same password your install currently uses so nothing is ambiguous later:

    ```bash theme={null}
    printf '%s' 'YOUR-EXISTING-PASSWORD' | cpln secret create-opaque --name my-dbeaver-admin-password --encoding plain -f -
    ```

    Then set `admin.passwordSecretName` to that name, and remove `admin.password` from your values — it no longer exists in the chart.
  </Step>

  <Step title="Decide whether you still want public access">
    If you were relying on the internet-facing URL, set `publicAccess.enabled: true` explicitly. If you were not, do nothing and the console becomes internal-only. Either way, allow a couple of minutes for the firewall change to propagate.
  </Step>

  <Step title="Expect your old login name and password to keep working">
    The account already exists in the workspace database, so the upgrade does not re-bootstrap it — neither `admin.name` nor the password secret is applied to a workspace that is already initialized (see [Admin Credentials](#admin-credentials)). Keep signing in with the name and password the workspace was bootstrapped with — typically `adminusername`, not the new `cbadmin` default. If either is one you would rather not keep, change it in the CloudBeaver UI after the upgrade.
  </Step>
</Steps>

## Important Notes

* **Create the admin-password secret before installing.** A missing secret does not fail the install — `cpln helm install` reports success and the workload then sits at zero replicas waiting on it, with no container logs to diagnose from.
* **The admin name and password are read only when the workspace is first initialized.** Rotating the secret or changing `admin.name` afterwards changes what the container sees and changes nothing about who can log in. Change the password in the CloudBeaver UI instead.
* **Anyone who can read this workload's logs can authenticate as the admin**, because CloudBeaver logs the submitted password hash and its API accepts that hash as a credential.
* **`publicAccess.enabled: true` puts a database administration console on the public internet.** Anyone who reaches it needs only the admin password to query every connected database. Prefer leaving it off and reaching the UI from inside the GVC.
* **Egress is closed and there is no knob for it** — only databases inside the same GVC can be connected. Managed services such as RDS, Cloud SQL, and Atlas are unreachable.
* **Access changes take up to a couple of minutes to propagate.** A `publicAccess` or `internalAccess` change that appears to do nothing has usually just not settled yet.
* **The first `helm upgrade` after an install restarts the workload**, taking the UI down for roughly 30 to 60 seconds even when nothing about the values changed. This template runs a single replica, so there is no other instance to serve during the restart. Later no-op upgrades do not restart it.
* **Saved connections and users live on the volume set** and survive redeploys and upgrades. `cpln helm uninstall` deletes the volume set, taking every saved connection with it.
* **There is no scheduled-backup feature.** The volume set takes no scheduled snapshots — the only one is the final snapshot taken when it is deleted, kept for 7 days. Export anything you cannot lose from the CloudBeaver UI before uninstalling.
* **The prerequisite secret is not owned by the release** — it survives `cpln helm uninstall` and must be deleted manually if you no longer need it.

## External References

<CardGroup cols={2}>
  <Card title="CloudBeaver Documentation" icon="book" href="https://dbeaver.com/docs/cloudbeaver/">
    Official DBeaver CloudBeaver documentation
  </Card>

  <Card title="Server Configuration" icon="gear" href="https://dbeaver.com/docs/cloudbeaver/Server-configuration/">
    Reference for CloudBeaver server settings
  </Card>

  <Card title="Admin Password Recovery" icon="key" href="https://dbeaver.com/docs/cloudbeaver/Admin-Password-Recovery/">
    Upstream procedure for regaining admin access
  </Card>

  <Card title="DBeaver GitHub" icon="github" href="https://github.com/dbeaver/cloudbeaver">
    CloudBeaver open-source repository
  </Card>

  <Card title="DBeaver Template" icon="github" href="https://github.com/controlplane-com/templates/tree/main/dbeaver">
    View the source files, default values, and chart definition
  </Card>
</CardGroup>