Databases
Add Postgres to an app, what the app gets from it, how it is backed up, and how to restore it.
Name an app's databases in clusterz.yaml, add one when you create the app, or later:
cluz projects create --name shop --repo https://github.com/acme/shop --database # the app with a Supabase called main
cluz db add main --kind postgres # for an app that exists
cluz db add geo --kind postgres --version 18 --extension postgis
cluz db # each database, its state and what it gives
cluz db url reports # a connection string, password maskedAn app's databases are part of its project. Each runs beside the app on the same network under its own name, is deployed before the app on every release, and is billed by its size with the app and deleted with it. A project created with --database needs nothing more than cluz deploy, and cluz db add redeploys an app that runs.
The kinds
| Kind | What it is | What each service it is for gets |
|---|---|---|
postgres | Postgres 17 with pgvector | DATABASE_URL |
postgres, version: 16 or 18, extensions: [postgis] | Postgres 16 or 18 with PostGIS 3.6 | DATABASE_URL |
supabase | Postgres 17 with pgvector, and Supabase's sign-in, data API, file storage and live row changes | DATABASE_URL, SUPABASE_URL, SUPABASE_ANON_KEY, and each name your code reads them under in the browser, like NEXT_PUBLIC_SUPABASE_URL, which the build reads too |
Every login is the app's own, never the server's administrator, and every password is a generated secret. Extensions the app's login cannot create, such as PostGIS, are created by Clusterz before the app starts. A variable of the same name that you set yourself is replaced only once you say so, or with cluz db add --yes.
Supabase
A supabase database is a Supabase inside your own app, not one Clusterz shares. Its Postgres is the app's own, and its sign-in, data API, file storage and live row changes run in the app's project and answer at the app's address under /auth/v1, /rest/v1, /storage/v1 and /realtime/v1. Its files are kept in a bucket of the app's own. An app has one Supabase, and there is no Studio.
Migrations
Put the command that applies them in release_command. It runs after the build, against the database, before traffic moves.
Backups to the minute
Each database is backed up continuously with WAL-G, so it can be restored to a chosen minute. A Supabase's files are kept with every old version, and the app's volumes are copied every 15 minutes.
Restore
Open the app's Backups page. Each database and each volume has its own Restore: choose a time, and only that one's data is replaced. A Supabase comes back with its files, to the same moment. The app's services stop while the data is replaced and start again after. An app of one database and no volume restores it from the one Restore.
The connection string
cluz db url -p <project> [name] reads a database of any of the team's apps by its name, the only one without a name, or a database that runs on its own, such as one made with cluz catalog deploy block-postgres, for another of the team's apps. --show adds the password, for the team's owners alone, and is recorded.
cluz db url -p shop main --show | cluz env set -p worker DATABASE_URL --secret