External database

To point Cobblr at a Postgres you already run instead of the bundled one, set two connection strings in .env. They override the values the stack otherwise derives from POSTGRES_PASSWORD, so when they are present they win.

DATABASE_URL=postgres://cobblr:password@your-db-host:5432/cobblr_meta
SUPERUSER_DATABASE_URL=postgres://admin:password@your-db-host:5432/postgres

What the server needs

• A role that can create databases and roles for the superuser connection. On a managed Postgres, a role with the CREATEDB and CREATEROLE privileges is enough. It does not have to be the cluster superuser.
• Connections accepted from the box (network access and pg_hba.conf / firewall rules).
• pgvector available if you use the AI embedding features.

Why there are two connection strings

Cobblr gives each workspace its own database, created on the fly when the workspace is created. That needs two levels of access:

• DATABASE_URL is the everyday connection, to the instance's own cobblr_meta database.
• SUPERUSER_DATABASE_URL is used only to provision a new workspace. It connects to the cluster's maintenance database and runs CREATE DATABASE and CREATE USER, then hands the new database off to that new user.

The bundled Postgres

Setting these two URLs is all the api needs to talk to your database.

• The bundled db service is still defined in the docker-compose.yml. It starts alongside the others and then sits idle, since nothing connects to it. Leaving it running is harmless. It just uses a little memory.
• To stop it running at all, add a Compose override file next to your docker-compose.yml that removes the db service and the api's dependency on it.

Backups

• Back up your own Postgres with whatever you already use for it. With an external database, the Operating backup step that dumps the bundled Postgres no longer covers your data.
• Keep copying the ./data/ tree on the box too. It still holds uploaded files, installed modules, and certificates.