Guides

Connecting a database

Managed Postgres beyond the basics — how apps reach it, TLS that actually verifies, backups, and access from your laptop.

Query your data is the tour version. This page covers what you need once an app depends on the database in production.

How an app reaches it

Databases belong to the organisation, not to an app. Creating one also creates the secret carrying its connection string, and that secret is how apps connect:

# org-wide: secret DATABASE_URL_ORDERS, visible to every app
$dibbla db create orders
 
# scoped to one app
$dibbla db create orders --deployment my-app

The secret is not called DATABASE_URL

It is DATABASE_URL_<NAME> — DATABASE_URL_ORDERS for a database named orders. Application code has to read the suffixed variable. This is the single most common first-hour mistake with Dibbla databases.

TLS

The public proxy at db.dibbla.com:30432 presents a publicly trusted certificate (CN=*.dibbla.com, Let’s Encrypt), and the chain verifies. Use sslmode=require, or verify-full if your client supports it. Verify it yourself with:

openssl s_client -connect db.dibbla.com:30432 -starttls postgres

Internal and local endpoints are different: dibbla db connect emits sslmode=disable for db.dibbla.net and for localhost, because there is no public certificate to verify there. That is a property of those environments, not advice for production clients.

From your laptop

The same DSN works off-cluster through the proxy. The CLI asks the platform where the proxy is before falling back to deriving it, so the command is the same wherever you run it:

$psql $(dibbla db connect orders -q)
 
# for tools that want it in the environment
$export DATABASE_URL=$(dibbla db connect orders -q)

That string carries your API token — pass it, never pipe it

The password slot is your token. Keep it inside a $( … ) so it goes straight into the client. Do not pipe it: psql reads standard input as SQL, so dibbla db connect … | psql tries to execute your connection string as a statement and echoes it — token included — back into the terminal inside the error.

Backups and moving data

# take one before you try something irreversible
$dibbla db dump orders -o orders-$(date +%F).dump
 
# seed another database from it
$dibbla db restore orders-staging -f orders-2026-08-14.dump

A dump is an ordinary file: treat it as production data, because it is. It belongs somewhere access-controlled, not in the repository.

Something other than Postgres

Managed databases are Postgres. For Redis, Mongo or anything else, run it as a service in your dibbla.yaml with stateful: true — the console’s Databases tab says as much in its empty state. You then own its backups and upgrades, which is the trade you are making.

stateful: true on its own is rejected: it needs at least one volumes: entry, or validation fails with STATEFUL_NO_VOLUME. Stateful without storage would silently lose data on every restart, so the manifest refuses the combination rather than letting you find out later.

services:
  cache:
    build: ./cache
    port: 6379
    stateful: true
    volumes:
      - path: /data
        size: 1Gi
        # access: rwo   # default; rwx for shared read-write

One more thing to know before you reach for replicas here: more than one replica gives you N independent pods, each with its own volume. The platform does not bootstrap a Mongo replica set or a Redis cluster for you — if you want clustering, your image has to arrange it.

← Previous

Environment & secrets

Custom domains