# Run Postgres on Koo

A Postgres database on Koo is a service in your [environment](/docs/projects/projects-and-environments): 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](/docs/networking/private-networking), and each one wires itself in with a [connection variable](/docs/databases/connect-a-database).

## Create a Postgres database

1. 
2. 
3. 
4. 
5. 
6. 
7.

> **Note:**
>
> Your primary account includes one free-unit Postgres (0.5 vCPU / 1 GiB) in its permanent free allowance, alongside one free web service and one free Redis. On the Free plan the allowance is also the ceiling — one Postgres in total. See [the free tier](/docs/get-started/free-tier).

## 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.

| vCPU | Memory | Price |
| --- | --- | --- |
| 0.25 vCPU | 512 MiB | $5/mo |
| 0.5 vCPU | 1 GiB | $10/mo |
| 1 vCPU | 2 GiB | $20/mo |
| 2 vCPU | 4 GiB | $40/mo |
| 4 vCPU | 8 GiB | $80/mo |

Pick any CPU + memory (memory up to 8 GiB per vCPU).

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. 
2. 
3.

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](/docs/databases/connect-a-database) 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](/api/objects/service) in the API.

The full set, password included, is behind **Reveal connection** on the same card. Revealing requires the [editor role](/docs/collaboration/teams-and-roles) or higher, and every reveal is logged to the [audit trail](/docs/collaboration/audit-log).

`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:

```bash
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

- 
- 
- 
- 
-

## 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).

> **Warning:**
>
> Once the delete deploys, the database's data is destroyed permanently. Koo keeps no backups or snapshots of databases — export anything you need first, for example with `pg_dump` run from one of your own services, which can reach the database and send the dump onward. A dump made in the Console tab has no way out of the container.