Docs · Configure

Postgres databases

Open an environment’s Database tab and choose Add database. You get a Postgres database in the same region as your app, its connection details are set as variables, and the app restarts with them. There is nothing to install or run.

The variables it sets

Variables a database sets
Name	Value
`DATABASE_URL`	The connection string, through a connection pooler. Use this one by default.
`DATABASE_URL_UNPOOLED`	A direct connection, for migrations and anything that needs a session.

A Laravel app also gets the variables Laravel reads, so there is nothing to map:

Laravel

DB_CONNECTION=pgsql
DB_HOST=…          # the direct host, so migrations can take their locks
DB_PORT=5432
DB_DATABASE=…
DB_USERNAME=…
DB_PASSWORD=…
DB_SSLMODE=require

These are managed: they are marked on the Variables tab and cannot be edited by hand, and a database cannot be added while you already have a variable of one of its names. To point your app somewhere else, set your own variable under another name. A global variable cannot take one of these names either; see Global variables.

The Database tab shows the host, the pooled host, the port and the user, and copies the full connection string, so you can connect from your own machine with psql or a GUI. Reset password makes a new one and restarts the app with it.

A database belongs to the team. On an environment with no database, Attach existing database picks one the team already has: the data is the same, and the environment gets its own copy of the variables. Two apps can share one this way, or staging can read production’s data if you want that.

An environment has one database at a time.
Detach removes the variables from that environment alone and leaves the database running for the others.
Resetting the password updates every environment it is attached to.

Sleeping

A database’s compute stops after 5 minutes with no queries and starts again on the next one. While it is stopped, it costs nothing for compute. On a paid plan it grows with load, from a quarter of a compute unit (CU) up to 2 CU, and is billed for what it used.

When a budget puts the team’s apps to sleep, their databases stop too, and come back with them. The data is kept either way.

Deleting and restoring

Delete database asks you to type its name. Its variables go from every environment at once, but the data is kept for 7 days: until then it is listed under Deleted lately on the Database tab of any of the team’s environments, and Restore brings it back there. After 7 days it is gone for good.

Deleting an app or environment that shares a database only detaches it there. The database is deleted when the last environment using it goes.

Branches for previews

When an app has preview deployments on, each preview gets a branch of its environment’s database: a copy of its data that the preview can change without touching the original. A branch sleeps when idle, is billed as database compute and storage, and is deleted with its preview. A database made on Free is never branched.

What it costs

Postgres prices
	Free	Paid plans
Databases	1 per Free team	As many as you need
Compute	Up to 0.25 CU, 20 CU-hours a month	$0.14 per CU-hour, 0.25 to 2 CU
Data	Up to 0.5 GB	$0.45 per GB-month
Billed	Never	From your plan’s included usage first

A small app’s database usually costs a few dollars a month or less. At a quarter of a CU, awake 4 hours a day, it uses about 30 CU-hours a month: $4.20. Half a gigabyte of data adds about 23 cents. On Starter, both come out of the $5 your plan includes.

On Free

Each person has one Free team, and it can have one database. It can be attached to every environment of that team.
Past 20 CU-hours in a calendar month, it pauses until the 1st, and the team’s owners are emailed. The data is kept.
At 0.5 GB, writes fail; reading and deleting still work.
A paid plan lifts these limits at once.