Deploy an app with a PostgreSQL database

On blitz.cloud, a database gets created for you while you put the app online. You switch on Needs a database, pick PostgreSQL, and blitz.cloud starts a PostgreSQL 17 database, fills in DATABASE_URL for your app, and copies the database off-site every night. The database has no public address; only your own apps can reach it.

This guide uses the node-api example, a small API that stores notes in PostgreSQL. The same steps apply to any image that reads a connection string from an environment variable.

How the app finds the database

For an image you bring yourself, blitz.cloud looks at the image to guess which settings it expects. When it recognises database variables, the wizard names them before anything is applied. When it doesn't, and you ask for a database, it sets a single DATABASE_URL:

postgresql://<user>:<password>@<host>:5432/<database>

The host is a short internal name that only resolves inside your own space on blitz.cloud. Your app code needs nothing more than this:

import pg from "pg";

const pool = process.env.DATABASE_URL
  ? new pg.Pool({ connectionString: process.env.DATABASE_URL, max: 5 })
  : null;

No TLS options are needed: the connection never leaves blitz.cloud's internal network, and network rules keep other accounts out of it.

Test with a local database first

docker network create notes-net
docker run -d --name notes-db --network notes-net \
  -e POSTGRES_USER=app -e POSTGRES_PASSWORD=secret -e POSTGRES_DB=app \
  postgres:17-alpine

docker build --platform linux/amd64 -t blitz-example-node-api .
docker run --rm --network notes-net --user 1000:1000 --cap-drop ALL \
  --security-opt no-new-privileges -p 8080:8080 \
  -e DATABASE_URL=postgresql://app:secret@notes-db:5432/app \
  blitz-example-node-api

curl -X POST -H 'content-type: application/json' -d '{"text":"first note"}' http://localhost:8080/notes
# {"id":1,"text":"first note","created_at":"..."}
curl http://localhost:8080/notes

In our test the POST returned 201 and the GET returned the note. The app creates its table on first start, which is the pattern to copy: run migrations when the process starts, because there is no separate step to run them on blitz.cloud.

Clean up with docker rm -f notes-db && docker network rm notes-net.

Deploy with the database

1. Push the image to Docker Hub as described in Deploy a Node.js API.
2. In the dashboard, click Host something new, choose "An app that is already packaged up", find your image and pick the version.
3. On the next screen, look at What this app needs. If the Database row already says PostgreSQL, blitz.cloud spotted it. If it says Not needed, open Advanced settings, switch on Needs a database and leave Which one on PostgreSQL.
4. Name the app, choose an address and click Put it online.

The database appears on the Databases page with the app it belongs to. Its connection string is masked there until you click to show it.

Things to know before you rely on it

One app, one database. A database belongs to exactly one app, so two apps can't share one. The free plan includes one database; it also takes 128 MB from your 2 GB memory pool and reserves 1 GB of your storage.

Nightly backups. Every night the database is dumped and copied to separate storage, outside the machines your apps run on. The free plan keeps 7 nights. Going back to a night is a button on the Databases page, and it replaces the whole database with that night's copy. Details in Backups.

No outside access. You can't connect to the database from your laptop with psql or a GUI client today. If you need to look inside, add a small admin tool as a second app, or build the query into your own app.

Deleting the app asks about the data. When you delete the app you are asked, with no default, whether to keep the database or delete it along with all its nightly copies.

MariaDB 11.4 and Redis (served by Valkey 8) are also available. MongoDB is not. More in Databases.