Skip to main content

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

Why there are two​

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.

So the superuser connection needs a role that can create databases and roles. On a managed Postgres, a role with the CREATEDB and CREATEROLE privileges is enough; it does not have to be the cluster superuser. Make sure the server accepts connections from the box (network access and pg_hba.conf / firewall rules), and that pgvector is available if you use the AI embedding features.

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, and it will start alongside the others and then sit idle, since nothing connects to it. If you would rather it not run 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. Leaving it running is harmless; it just uses a little memory.

Backups​

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