Run Postgres on Koo

A Postgres database on Koo is a service in your environment: you create it on the environment canvas, right next to the services that use it. Koo runs Postgres 18 — there is no version to pick and nothing to install or upgrade.

A database is never internet-reachable. It has no public URL, and its hostname only resolves inside Koo — your services reach it over Koo's private network, and each one wires itself in with a connection variable.

Create a Postgres database

1. Open the environment canvas and click New service (or right-click the canvas).
2. Choose Database, then PostgreSQL.
3. The database appears as a staged ghost node — nothing exists yet. Staged changes explains this model.
4. Optional: click the staged node and open its Settings to set Credentials — username, password, and database name. Leave them blank for secure defaults.
5. Optional: adjust CPU and memory in the same Settings pane.
6. Press Deploy (Shift+Enter) on the changes bar.
7. The node shows In progress while the database provisions, then Online. Your database is ready.

Credentials

Credentials are set at create time and can never be changed afterwards. Postgres takes three: a username, a password, and a database name — the defaults are koo, an auto-generated password, and koo.

A password you supply yourself must be 8–128 characters, using only letters, digits, and . _ ~ -. The restriction exists because the password is embedded verbatim in the connection URL — postgres://koo:<password>@<host>:5432/koo — so it must never need URL-encoding. Generate secure password fills in a compliant one for you.

Size and disk

You give a database explicit CPU and memory, like any service. Disk is included automatically and follows the memory you pick — you never choose a disk size.

A database always runs as exactly one instance in one location, on every plan.

Connect from your services

Nothing is wired automatically. Creating a database changes nothing about your other services — each consumer declares its own connection variable:

1. Click the consuming service on the canvas and open its Variables tab.
2. Click Reference, name the variable DATABASE_URL, and under From a database choose your database's DATABASE_URL entry — the full connection URL.
3. Click Add, then Deploy the staged change.

Your code then reads DATABASE_URL from its environment like any other variable.

A Postgres database publishes six connection keys — DATABASE_URL, HOST, PORT, USER, PASSWORD, DBNAME — and a consumer can wire any single one individually. The connection guide covers individual keys, sharing one database between services, and the API shape.

View connection details

The database's Settings tab shows a read-only Connection card with the non-secret details: HOST, PORT, USER, and DBNAME. The same card rides every read of the service object in the API.

The full set, password included, is behind Reveal connection on the same card. Revealing requires the editor role or higher, and every reveal is logged to the audit trail.

HOST is the database's internal hostname — the same value shown under Private networking in Settings. It only resolves inside Koo; there is no external address.

Run queries

The database's Console tab opens a shell in the running container, where psql is available:

psql -U koo koo

Substitute your own username and database name if you overrode the defaults at create time. The console requires the editor role or higher, and every session is audited.

There is no external access of any kind — not from your laptop, not from CI, not from a GUI client. The database's host only resolves inside Koo.

A SQL console in the browser will let you run queries without opening a shell. Coming soon

What a Postgres service doesn't do

• No public URL, ever — a database cannot be exposed.
• No builds, deployments, or logs tabs — a database has no deploy pipeline.
• No variables of its own — a database runs with its own connection settings; other services read it through a connection variable in their Variables tab.
• No version choice — every database runs Postgres 18.
• No replicas or extra locations — always exactly one instance in one location.

Delete a database

Deleting a database is staged like any other change: the node is marked for deletion, and you can undo freely until you confirm on the changes bar. The bar's button reads Delete when the deletion stands alone (Deploy when other staged changes ride along).