PostgreSQL Database

Every App Platform plan includes a managed PostgreSQL 16 database. Your app receives the database's connection address in the DATABASE_URL environment variable, so there is no host, user or password to configure by hand. This guide shows how to connect from common frameworks, how backups and restores work, and how to run migrations.

1. How your app connects

The platform sets DATABASE_URL on your app. It is a standard PostgreSQL connection string in this form:

postgresql://user:password@host:5432/dbname

Read it from the environment rather than copying the value into your code or a config file. The Overview tab shows your database's name.

Node.js with Prisma

// prisma/schema.prisma
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

Node.js with node-postgres

const { Pool } = require('pg');
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

Python with SQLAlchemy

import os
from sqlalchemy import create_engine
engine = create_engine(os.environ['DATABASE_URL'])

Go

import (
    "database/sql"
    "os"
    _ "github.com/lib/pq"
)

db, err := sql.Open("postgres", os.Getenv("DATABASE_URL"))

Python, Go and other non-Node.js apps are built from a Dockerfile in your project; only Node.js is detected automatically. See the App Platform overview.

2. DATABASE_URL is a system variable

DATABASE_URL appears in the Env Vars tab as a system variable. You can't change or delete it; trying gives "Cannot modify system variable". That protects your app from losing its database connection.

To use a database you host elsewhere, add your own variable under a different name, for example EXTERNAL_DATABASE_URL, and read that in your code. See Environment variables.

3. Backups

Your database is backed up automatically every night, and about a week of backups is kept. You can also take a backup yourself at any time.

Take a manual backup immediately before a schema migration, a bulk delete or a major release. That way your recovery point is exactly where you want it, not last night.

4. Restoring a backup

1. In Data › Backups, find the backup you want.
2. Click Restore on its row and confirm.

5. Running migrations

Run your migrations as part of the app's start command, so each new version brings the schema up to date before it serves traffic. With Prisma, in a Procfile:

web: npx prisma migrate deploy && node server.js

Or in package.json:

{
  "scripts": {
    "start": "prisma migrate deploy && node server.js"
  }
}

For a Dockerfile app, put the same two steps in the CMD. Use migrations that are safe to run more than once: most migration tools, including Prisma, skip anything already applied.

6. Limits and what isn't included

• No direct connection from your own computer. Your app reaches its database internally; tools like pgAdmin or psql on your laptop can't connect. To inspect data, add a small admin route or a scheduled job to your app.
• The managed database is PostgreSQL. To use a different database engine, host it elsewhere and connect through your own environment variable.
• Files aren't in the database backup. Files your app writes to a persistent folder (Data › Storage) are separate from database backups.

7. If your app can't reach its database

Don't change DATABASE_URL; the value the platform sets is the right one. Check the Logs tab for the exact error. Common causes on your side are a library expecting a different variable name, or code that reads the address before the environment is loaded.

If the logs show a connection failure while your code reads DATABASE_URL correctly, open a ticket with your app name. That is something for us to fix, not you.

Ready to build on PostgreSQL? Open your App Platform apps, compare App Platform plans, or ask us in a support ticket.