Documentation
Database
One tick gives an app a Postgres database, living inside the app itself rather than beside it.
It lives inside the app
The database runs in the same isolated app as your services, on port 5432. Your services reach it over localhost; nothing outside the app can, and there is no public address to expose or firewall.
Because it is part of the app, it is included when the app goes back to an earlier snapshot — your code and your data return together. That is on Snapshots.
You can add one later
Ticking the box when you create the app is the usual way, but it is not the only one. An app that started without a database can be given one from its Database tab, and it keeps everything it already has — the same URL, the same address, the same history.
- The app restarts to attach it. It is unreachable for a few seconds while it comes back up.
- The connection string is shown once. Your services are given it automatically, so you only need to copy it if you want to connect from somewhere else — and nothing can retrieve it afterwards.
- Two things change permanently. The app stops pausing when idle, and it can no longer be copied into a new app. Both are covered below.
Connecting
You do not write connection details. The database sets the variable your framework actually reads, chosen from what was detected in your repository:
| Framework | Variable it is given |
|---|---|
| Node, Python, Rails, Go, Rust, Elixir — and every image source | DATABASE_URL |
| Laravel | DB_CONNECTION, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD |
| Spring Boot | SPRING_DATASOURCE_URL, SPRING_DATASOURCE_USERNAME, SPRING_DATASOURCE_PASSWORD |
The distinction is not cosmetic: a Laravel application does not read DATABASE_URL, it reads six DB_* variables, and giving it the wrong one is a database the app cannot see with nothing on screen explaining why.
The password is not retrievable
The credential is composed inside the app and is returned by nothing. There is no reveal control, and that is the design rather than a gap: your services are handed the connection variable, and the console below opens a session that is already authenticated — so nobody needs to read it.
The reason to keep it that way: a password rendered on a page is a password in a screenshot, in a bug report's network log, and in the browser's accessibility tree.
The console is psql
The app's database tab opens a real psql session against it — run queries, inspect schemas, load a fixture.
- psql is the process itself, not a program launched inside a shell.
- \q ends the session, and there is nothing behind it — no prompt, no filesystem.
That boundary is enforced where the app actually runs, not by the page you are typing into, so it holds regardless of what the browser sends.
An app with a database is always on
Two behaviours change structurally once an app has a database, and neither is a temporary limitation:
- It never pauses when idle. The pause-when-idle setting is accepted and then ignored for an app with a database — see Limits.
- It cannot be forked. Branching a new app from a snapshot is refused when the app has a database — see Snapshots.