# PostgreSQL

Add `"postgres": true` at the top level of `leilani.json`, commit, and push. Leilani starts a dedicated PostgreSQL 18 instance for the workspace before starting its packages.

```json
{
  "postgres": true,
  "packages": { "my-app": {} },
  "http": { "binds": { "WORKSPACE-ID.aloha.leilani.dev": 3000 } }
}
```

Connect through the Unix socket directory `/run/postgresql` on port 5432. A new cluster has a `postgres` database and superuser with local trust authentication: no password or TLS is required. There is no public or private TCP database endpoint. Your driver must support Unix sockets.

For clients that read libpq-style variables, add these values in Environment, then redeploy. Leilani does not inject them into application processes; other drivers need equivalent connection options in application code.

```dotenv
PGHOST=/run/postgresql
PGPORT=5432
PGUSER=postgres
PGDATABASE=postgres
PGSSLMODE=disable
```

Open Terminal and run `psql` to connect. Terminal supplies the initial host, port, user, and database defaults; shared environment variables or explicit command options can override them. You can create databases, roles, and schemas. If you change authentication or remove the initial role or database, update your connection settings too.

PostgreSQL has a separate 512 MiB memory limit and one shared CPU quota. It allows 20 connections and defaults to 30-second statement and idle-in-transaction timeouts. Use a connection pool within that limit. Database storage counts toward the workspace’s shared 20 GiB quota.

Data survives redeployment and disabling PostgreSQL. Setting `postgres` to false stops the database on deployment but retains its data; enabling it again reuses the cluster. Stopping all packages leaves PostgreSQL running while the VM remains alive. A database startup failure after handoff leaves the workspace offline.

Read database output in Logs using `{kind="PostgresLog"}`. PostgreSQL metrics, automatic major-version upgrades, and automated backups are not provided. Use database tools to take consistent backups before migrations.
