Create a PostgreSQL database and connect to it

A managed PostgreSQL database gives you a place for your data without a server to look after. You order it in the panel, copy the connection details and connect from your own computer or from your application. This guide shows each step.

What you need

• A Headpat Space account with a verified email address and your billing details filled in.
• A PostgreSQL client. This guide uses psql, which ships with PostgreSQL.

1. Order the database

1. Sign in to the panel, open Apps in the sidebar and click Create App.
2. Under Template, search for PostgreSQL and select it.
3. Under Package, choose a package. A single node is fine for a side project or a test. The high availability packages run a primary with replicas and switch over automatically if the primary fails.
4. Under Details, fill in a Display name. Under Version, pick the PostgreSQL version your application needs, or leave it on Latest (recommended).
5. Tick the box confirming that provisioning may start right away, click Deploy app and complete the payment.

The database is created automatically. Wait until the app page shows it as running.

2. Find your connection details

Open the database under Apps. The card Database Connection has everything you need.

Field	What it is
Host	The hostname of your database
Port	The port of your database. It is a port of its own, not the usual 5432
Kind	The database type, here postgres

The login is hidden at first. Click Reveal next to Credentials to show:

• Username: the database user, app
• Password: a random password created for your database
• Database: the name of the database, app
• Connection string: all of the above in one line, ready to paste

Every field has a copy button. Click Hide when you are done. Treat the password like any other secret: do not put it in a public repository, a screenshot or a chat.

3. Connect with psql

Copy the Connection string, add ?sslmode=require to the end and paste it between quotes:

psql "postgres://app:YOUR_PASSWORD@YOUR_HOST:YOUR_PORT/app?sslmode=require"

Or pass the parts one by one. psql then asks for the password:

psql -h YOUR_HOST -p YOUR_PORT -U app -d app

You are connected when you see the prompt app=>.

Type \q to leave.

4. Connect from your application

Most frameworks and libraries read a single connection string, usually from an environment variable called DATABASE_URL:

DATABASE_URL=postgres://app:YOUR_PASSWORD@YOUR_HOST:YOUR_PORT/app?sslmode=require

A minimal example in Python with the psycopg package:

import os
import psycopg

with psycopg.connect(os.environ["DATABASE_URL"]) as conn:
    print(conn.execute("SELECT now()").fetchone())

Keep the password in an environment variable or a secret store, not in your code.

A note on TLS

Your database is reachable from the internet on the host and port shown in the panel, so encryption matters.

• The database server supports TLS. psql and most current clients use it automatically when the server offers it.
• The connection string in the panel does not contain an sslmode setting. Add ?sslmode=require at the end, as in the examples above. The client then refuses to connect without encryption.
• The server certificate is not issued by a public certificate authority. The modes verify-ca and verify-full therefore fail. Use require.
• Not every library reads sslmode the way psql does. If yours reports a certificate error with require, look for its option that encrypts without checking the certificate. In node-postgres that is sslmode=no-verify.

Limit who can connect

By default the database accepts connections from any IP address that knows the password. You can narrow that down.

1. On the app page, find the card IP Allowlist. It shows Open to all while the list is empty.
2. Enter an IP address or a CIDR range, for example 203.0.113.4 or 203.0.113.0/24, and add it.
3. Click Save. The card now shows Restricted.

Only the listed addresses can connect from then on. If your application runs on a server with a fixed IP address, add that address. Allow all empties the list again after you save.

Backups

The panel backs up your database automatically on a schedule. How often and how long backups are kept depends on your package.

• The card Backups lists all backups, marked Scheduled or Manual.
• Click Create backup before a risky change, such as a large migration.
• Restore overwrites the current data with the backup. The database is offline until the restore is finished, which can take 10 minutes or longer.

The full procedure is in Back up and restore your app.

Want a copy on your own computer as well? Use pg_dump:

pg_dump "postgres://app:YOUR_PASSWORD@YOUR_HOST:YOUR_PORT/app?sslmode=require" > backup.sql

If something does not work

• Connection times out or is closed right away: check host and port, and check whether your IP address is on the IP Allowlist.
• Password authentication failed: copy the password again with the copy button. Extra spaces are a common cause.