Your own database

Use your own PostgreSQL or a Supabase project instead of the built-in database.

Waterflow runs its own PostgreSQL 17 by default. To use yours instead (PostgreSQL 15 or newer, or a Supabase project), set it in .env, as the database’s owner:

ADMIN_DATABASE_URL=postgresql://postgres:PASSWORD@HOST:5432/postgres?sslmode=require

and start without the built-in one:

docker compose up -d --scale db=0

The server applies its migrations and creates its own limited logins (api_login, purge_login, fx_login) in that database, with passwords it keeps in its secrets volume. The web app and API only ever use those logins; the owner’s login is used for migrations and backups. Percent-encode a password containing @, /, ? or #.

Supabase

Use the project’s Session pooler address (Connect in Supabase), with ?sslmode=require added:

ADMIN_DATABASE_URL=postgresql://postgres.PROJECTREF:PASSWORD@aws-1-REGION.pooler.supabase.com:5432/postgres?sslmode=require

• Not the direct connection: it’s IPv6-only, which Docker’s default network and Cloud Run can’t reach (unless you buy Supabase’s IPv4 add-on).
• Not the transaction pooler (port 6543): the migrations need a whole session.
• The pooler tells projects apart by the part after the dot in postgres.PROJECTREF. Waterflow gives its own logins the same suffix (api_login.PROJECTREF, …): an owner login with a dot in its name always means that, so on your own PostgreSQL use an owner whose name has no dot.

Waterflow takes away everything Supabase grants its browser roles, and never uses Supabase’s Data API or Auth: sign-in is Waterflow’s own. A free Supabase project is paused after a week without database activity; the daily jobs keep it active as long as the server runs.

Running the server itself on Google Cloud Run too: Run it on Google Cloud Run.