PostgreSQL-database aanmaken en ermee verbinden

Een beheerde PostgreSQL-database geeft je een plek voor je gegevens zonder dat je een server hoeft te onderhouden. Je bestelt hem in het paneel, kopieert de verbindingsgegevens en verbindt vanaf je eigen computer of vanuit je applicatie. Deze handleiding laat elke stap zien.

Wat je nodig hebt

Een Headpat Space-account met een geverifieerd e-mailadres en ingevulde factuurgegevens.
Een PostgreSQL-client. Deze handleiding gebruikt psql, dat bij PostgreSQL wordt meegeleverd.

1. Bestel de database

Log in op het paneel, open Apps in de zijbalk en klik op App aanmaken.
Zoek onder Template naar PostgreSQL en selecteer het.
Kies onder Pakket een pakket. Eén node is prima voor een zijproject of een test. De hoogbeschikbare pakketten draaien een primaire node met replica's en schakelen automatisch over als de primaire uitvalt.
Vul onder Details een Weergavenaam in. Kies onder Versie de PostgreSQL-versie die je applicatie nodig heeft, of laat het op Laatste (aanbevolen) staan.
Vink het vakje aan waarmee je bevestigt dat de levering direct mag beginnen, klik op App deployen en rond de betaling af.

De database wordt automatisch aangemaakt. Wacht tot de app-pagina aangeeft dat hij draait.

2. Vind je verbindingsgegevens

Open de database onder Apps. Op de kaart Database-verbinding staat alles wat je nodig hebt.

Veld	Wat het is
Host	De hostnaam van je database
Poort	De poort van je database. Het is een eigen poort, niet de gebruikelijke 5432
Soort	Het databasetype, hier `postgres`

De login is eerst verborgen. Klik naast Inloggegevens op Tonen om dit te zien:

Gebruikersnaam: de databasegebruiker, app
Wachtwoord: een willekeurig wachtwoord dat voor jouw database is aangemaakt
Database: de naam van de database, app
Connection string: alles hierboven in één regel, klaar om te plakken

Elk veld heeft een kopieerknop. Klik op Verbergen als je klaar bent. Behandel het wachtwoord als elk ander geheim: zet het niet in een openbare repository, een screenshot of een chat.

3. Verbinden met psql

Kopieer de Connection string, zet ?sslmode=require aan het einde en plak hem tussen aanhalingstekens:

psql "postgres://app:JOUW_WACHTWOORD@JOUW_HOST:JOUW_POORT/app?sslmode=require"

Of geef de onderdelen los op. psql vraagt dan om het wachtwoord:

psql -h JOUW_HOST -p JOUW_POORT -U app -d app

Je bent verbonden als je de prompt app=> ziet.

Typ \q om af te sluiten.

4. Verbinden vanuit je applicatie

De meeste frameworks en libraries lezen één connection string, meestal uit een omgevingsvariabele met de naam DATABASE_URL:

DATABASE_URL=postgres://app:JOUW_WACHTWOORD@JOUW_HOST:JOUW_POORT/app?sslmode=require

Een minimaal voorbeeld in Python met het pakket psycopg:

import os
import psycopg

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

Bewaar het wachtwoord in een omgevingsvariabele of een secret store, niet in je code.

Een opmerking over TLS

Je database is vanaf het internet bereikbaar op de host en poort die het paneel toont. Versleuteling is dus belangrijk.

De databaseserver ondersteunt TLS. psql en de meeste actuele clients gebruiken het automatisch als de server het aanbiedt.
De connection string in het paneel bevat geen instelling sslmode. Zet ?sslmode=require aan het einde, zoals in de voorbeelden hierboven. De client weigert dan te verbinden zonder versleuteling.
Het servercertificaat is niet uitgegeven door een openbare certificaatautoriteit. De modi verify-ca en verify-full mislukken daarom. Gebruik require.
Niet elke library leest sslmode zoals psql dat doet. Geeft die van jou met require een certificaatfout, zoek dan naar de optie die versleutelt zonder het certificaat te controleren. Bij node-postgres is dat sslmode=no-verify.

Beperk wie mag verbinden

Standaard accepteert de database verbindingen vanaf elk IP-adres dat het wachtwoord kent. Dat kun je inperken.

Zoek op de app-pagina de kaart IP-toegangslijst. Die toont Open voor iedereen zolang de lijst leeg is.
Vul een IP-adres of een CIDR-reeks in, bijvoorbeeld 203.0.113.4 of 203.0.113.0/24, en voeg het toe.
Klik op Opslaan. De kaart toont nu Beperkt.

Vanaf dat moment kunnen alleen de adressen op de lijst verbinden. Draait je applicatie op een server met een vast IP-adres, zet dat adres er dan op. Alles toestaan maakt de lijst weer leeg nadat je hebt opgeslagen.

Back-ups

Het paneel maakt automatisch volgens schema back-ups van je database. Hoe vaak dat gebeurt en hoe lang back-ups bewaard blijven, hangt af van je pakket.

De kaart Back-ups toont alle back-ups, gemarkeerd als Gepland of Handmatig.
Klik op Back-up maken voor een riskante wijziging, zoals een grote migratie.
Herstellen overschrijft de huidige gegevens met de back-up. De database is offline tot het herstel klaar is. Dat kan 10 minuten of langer duren.

De hele procedure staat in Een back-up van je app maken en herstellen.

Wil je ook een kopie op je eigen computer? Gebruik pg_dump:

pg_dump "postgres://app:JOUW_WACHTWOORD@JOUW_HOST:JOUW_POORT/app?sslmode=require" > backup.sql

Als iets niet werkt

De verbinding loopt in een time-out of wordt direct verbroken: controleer host en poort, en kijk of je IP-adres op de IP-toegangslijst staat.
Wachtwoordauthenticatie mislukt: kopieer het wachtwoord opnieuw met de kopieerknop. Extra spaties zijn een veelvoorkomende oorzaak.