Zum Hauptinhalt springen
Version: Weekly Build

PostgreSQL

PostgreSQL ist eine universelle relationale Datenbank für transaktionale Workloads, Anwendungszustände und strukturierte Analysen. In den aktuellen Provider-Definitionen ist dieser Provider GA.

EigenschaftWertHinweise
Provider-NamepostgresWird in Landscape-Provider-Definitionen verwendet.
Versionv1Aktuell vom Provider bereitgestellte Schema-Version.
KategorieDatabaseWird im Managed Services-Katalog angezeigt.
GeltungsbereichglobalVerfügbar auf Resource Group-Ebene, nicht an eine einzelne Workspace-Runtime gebunden.
Resource Group SingletonfalseResource Groups können mehrere PostgreSQL-Serviceinstanzen erstellen.
Pause-UnterstützungtrueDieser Provider unterstützt das Pausieren.

Funktionen​

FunktionUnterstütztHinweise
Backups✅Backups der Datenbank werden unterstützt.
Point-in-Time Recovery✅Die Datenbank kann auf einen bestimmten Zeitpunkt wiederhergestellt werden.
Gut zu wissen
  • Upgrades werden nie automatisch angewendet. Manuelle Minor-Version-Upgrades werden über das Konfigurationsfeld version unterstützt.
  • Speicher wächst nicht automatisch, der storage-Planparameter kann aber jederzeit manuell erhöht werden.

Architektur​

Jeder PostgreSQL-Service ist ein dedizierter PostgreSQL-Server, der auf Codespheres Kubernetes-Infrastruktur läuft und vom CloudNativePG-Operator betrieben wird. Codesphere übernimmt den gesamten Lebenszyklus: Provisionierung, Konfigurationsänderungen, Minor-Version-Updates, Volume-Resizing und Wiederherstellung aus Backups.

  • Dedizierte Instanz: Die Datenbank läuft in einem eigenen Pod mit eigenem persistentem Volume. Es wird nichts mit anderen Services oder Resource Groups geteilt.
  • Speicher: Daten werden auf Ceph-Block-Storage (RBD) gespeichert, der auf der Storage-Ebene repliziert wird.
  • Backups: Backups werden kontinuierlich in einem Object Storage archiviert, was sowohl die Wiederherstellung eines bestimmten Backups als auch Point-in-Time Recovery ermöglicht.
  • Container-Image: Codesphere stellt eigene PostgreSQL-Images bereit, die auf den CloudNativePG-Images basieren und die unten aufgeführten Erweiterungen vorinstalliert haben.
  • Einzelinstanz: Ein Service mit einer einzelnen Instanz hat keine Replikate, sodass Konfigurationsänderungen, Versions-Upgrades und Plattform-Updates eine kurze Downtime verursachen. Siehe Shutdown-Verhalten.
  • Hochverfügbarkeit: Mit drei Instanzen verursachen Neustarts nur eine kurze Unterbrechung. Siehe Shutdown-Verhalten.

Schema​

Config​

FeldTypBei Erstellung erforderlichHinweise
versionstringNeinPostgreSQL-Engine-Version. Standard: 17.9. Erlaubte Werte: 17.9, 17.6, 16.13, 16.10, 15.17, 15.14, 14.22, 14.19. Nur Minor-Upgrades.
userNamestringNeinStandard: app. Nach der Erstellung unveränderlich. Darf nicht postgres sein.
databaseNamestringNeinStandard: app. Nach der Erstellung unveränderlich.

Secrets​

FeldTypBei Erstellung erforderlichHinweise
userPasswordstringJaPasswort für den durch userName definierten Anwendungsbenutzer.
superuserPasswordstringJaPasswort für den postgres-Superuser.

Details / Output​

FeldTypVerfügbarkeitHinweise
hostnamestringNach Provisionierung verfügbarInterner Service-Hostname.
portintegerNach Provisionierung verfügbarPostgreSQL-Port.
dsnstringNach Provisionierung verfügbarVom Provider zurückgegebener Connection String.
readybooleanNach Provisionierung verfügbarZeigt an, ob die Instanz für Verbindungen bereit ist.

Plan​

Der Provider bietet einen Plan, Small (id: 0). Beispielplan: Small (id: 0).

ParameterTypStandardMinimumMaximumStatischHinweise
cpunumber1--JaAbgerechnet als cpu-tenths.
memoryinteger128--JaAbgerechnet als ram-mib.
storageinteger1024512-NeinAbgerechnet als storage-mib.

Beispiel in einer Landscape​

schemaVersion: v0.2

run:
app-db:
provider:
name: postgres
version: v1
plan:
id: 0
parameters:
storage: 2048
config:
version: "17.9"
userName: "${{ workspace.env.PGUSER }}"
databaseName: "${{ workspace.env.PGDATABASE }}"
secrets:
userPassword: "${{ vault.pgUserPassword }}"
superuserPassword: "${{ vault.pgSuperuserPassword }}"

Hostnamen konstruieren​

Von Landscapes verwaltete Service-Hostnamen sind deterministisch und folgen dieser Struktur:

ms-{providerName}-{providerVersion}-{resourceGroupId}-landscape-{workspaceId}-{serviceName}.rg-{resourceGroupId}

Der Hostname wird in Kleinbuchstaben umgewandelt, und ungültige Zeichen werden durch Bindestriche ersetzt.

Ältere Services verwenden stattdessen das Suffix ms-postgres, zum Beispiel ms-postgres-v1-42-landscape-100-db.ms-postgres.

Diese Änderung ist nicht breaking: Neue Services sind zusätzlich über einen Alias mit dem Suffix ms-postgres erreichbar, sodass bestehende Konfigurationen und Skripte, die .ms-postgres-Hostnamen verwenden, weiterhin funktionieren.

Wenn der PostgreSQL-Service db heißt, kann der Hostname in Shell-Befehlen als ms-postgres-v1-$TEAM_ID-landscape-$WORKSPACE_ID-db.rg-$TEAM_ID oder in Landscape-Templates als ms-postgres-v1-${{ resourceGroup.id }}-landscape-${{ workspace.id }}-db.rg-${{ resourceGroup.id }} konstruiert werden.

ProviderVersionResource Group-IDWorkspace-IDServicenameHostname
postgresv142100dbms-postgres-v1-42-landscape-100-db.rg-42

Beispiel-ci.yml, die den konstruierten Hostnamen direkt in einem Befehl verwendet:

schemaVersion: v0.2

run:
db:
provider:
name: postgres
version: v1
plan:
id: 0
parameters:
storage: 2048
config:
version: "17.9"
secrets:
userPassword: "${{ vault.pgUserPassword }}"
superuserPassword: "${{ vault.pgSuperuserPassword }}"

api:
steps:
- command: >
psql "postgres://app:${PG_PASSWORD}@ms-postgres-v1-$TEAM_ID-landscape-$WORKSPACE_ID-db.rg-$TEAM_ID:5432/app" -c "select 1"
env:
PG_PASSWORD: "${{ vault.pgUserPassword }}"

Beispiel-ci.yml, die den konstruierten Hostnamen über eine Umgebungsvariable verwendet:

schemaVersion: v0.2

run:
db:
provider:
name: postgres
version: v1
plan:
id: 0
parameters:
storage: 2048
config:
version: "17.9"
secrets:
userPassword: "${{ vault.pgUserPassword }}"
superuserPassword: "${{ vault.pgSuperuserPassword }}"

api:
steps:
- command: >
psql "postgres://app:${PG_PASSWORD}@${PG_HOST}:5432/app" -c "select 1"
env:
PG_HOST: ms-postgres-v1-${{ resourceGroup.id }}-landscape-${{ workspace.id }}-db.rg-${{ resourceGroup.id }}
PG_PASSWORD: "${{ vault.pgUserPassword }}"

Innerhalb von Application Runtimes erfolgt die Verbindung über den zurückgegebenen dsn oder über hostname, port, den konfigurierten Benutzernamen und das gespeicherte Passwort. Derselbe interne Endpunkt kann auch von anderen Codesphere-Runtimes verwendet werden, einschließlich Reactives, Managed Containers und Workloads, die innerhalb eines Virtual Cluster laufen.

Verbindung zu einer Postgres-DB herstellen​

Voraussetzungen​

Sobald die Postgres-DB bereitgestellt ist, kann von Codesphere-Workspaces aus eine Verbindung hergestellt werden. Jeder Service listet seine nicht-sensiblen Verbindungsdetails auf seiner Einstellungsseite im Übersichts-Tab (oder in der details-Eigenschaft des öffentlichen API-Payloads).

info

Vor dem Verbinden sicherstellen, dass der Service synchronisiert ist und läuft: In den Service-Einstellungen muss ready auf true stehen.

Verbindung über Terminal (psql)​

Das Kommandozeilentool psql kann direkt im Workspace-Terminal verwendet werden.

# psql installieren
nix-env -iA nixpkgs.postgresql

# Allgemeine Syntax
psql "postgres://<username>@<hostname>:5432/<database>" -W

# Beispiel
psql "postgres://[email protected]:5432/mydb" -W

Verbindung über Node.js​

Mit der pg-Bibliothek:

const { Client } = require('pg');

const client = new Client({
connectionString: 'postgres://admin:[email protected]:5432/mydb'
});

await client.connect();
const res = await client.query('SELECT $1::text as message', ['Hello Codesphere!']);
console.log(res.rows[0].message); // Hello Codesphere!
await client.end();

Backups​

Der PostgreSQL-Provider unterstützt automatisierte Backups und Point-in-Time Recovery zu jedem S3-kompatiblen Backup-Store. Dieser Abschnitt beschreibt die PostgreSQL-spezifische Konfiguration; die allgemeinen Konzepte werden unter Managed Service Backups behandelt.

Im Hintergrund werden Backups mit dem CloudNativePG-Barman Cloud-Plugin umgesetzt: Es erstellt regelmäßig physische Basis-Backups der Datenbank und archiviert kontinuierlich das Write-Ahead Log (WAL) im konfigurierten Backup-Store. Eine Wiederherstellung stellt ein Basis-Backup wieder her und spielt das archivierte WAL darauf ab — dies ermöglicht Point-in-Time Recovery zwischen zwei Backups.

Backups aktivieren​

Das folgende Beispiel aktiviert Backups für einen bestehenden PostgreSQL-Service. Derselbe backups-Block funktioniert auch beim Erstellen eines neuen Services mit POST /managed-services.

curl -X PATCH "https://api.codesphere.com/managed-services/YOUR_SERVICE_ID" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"backups": {
"enabled": true,
"intervalH": 12,
"deleteRetentionDays": 30,
"config": {
"endpointUrl": "https://s3.eu-central-1.amazonaws.com",
"destinationPath": "s3://my-codesphere-backups/",
"accessKey": "YOUR_S3_ACCESS_KEY"
},
"secrets": {
"secretKey": "YOUR_S3_SECRET_KEY"
}
}
}'
warnung

endpointUrl muss der regionale S3-Endpunkt sein, kein Bucket-spezifischer Hostname. Zum Beispiel https://s3.eu-central-1.amazonaws.com statt https://my-bucket.s3.eu-central-1.amazonaws.com.

Erforderliche S3-Berechtigungen​

Die für den Zugriff auf den S3-kompatiblen Backup-Store verwendeten Zugangsdaten (Access Key und Secret Key) müssen ausreichende Berechtigungen zum Erstellen, Lesen, Aktualisieren und Löschen von Objekten haben. Bei AWS S3 bedeutet dies, dass der dem Access Key zugeordnete IAM-Benutzer oder die Rolle mindestens die folgenden Berechtigungen haben muss.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "BucketLevelOperations",
"Effect": "Allow",
"Action": [
"s3:GetBucketLocation",
"s3:ListBucket",
"s3:ListBucketMultipartUploads"
],
"Resource": "arn:aws:s3:::YOUR_BUCKET_NAME"
},
{
"Sid": "ObjectLevelOperations",
"Effect": "Allow",
"Action": [
"s3:AbortMultipartUpload",
"s3:DeleteObject",
"s3:GetObject",
"s3:ListMultipartUploadParts",
"s3:PutObject",
"s3:PutObjectTagging"
],
"Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/*"
}
]
}

Beispiele für die Wiederherstellung​

Das Wiederherstellen eines Backups erstellt immer einen neuen Managed Service; der bestehende Service bleibt unberührt.

Point-in-Time Recovery​

Die vorherige Managed Service-ID (msId) zusammen mit einem Wiederherstellungszeitpunkt (time) angeben:

curl -X POST "https://api.codesphere.com/managed-services" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"resourceGroupId": 123,
"name": "my-postgres-recovered",
"provider": {
"name": "postgres",
"version": "v1"
},
"plan": {
"id": 0,
"parameters": { "storage": 2048 }
},
"config": {
"version": "17.9"
},
"secrets": {
"userPassword": "secure-password",
"superuserPassword": "secure-superuser-password"
},
"recoverFrom": {
"msId": "OLD_MANAGED_SERVICE_ID",
"time": "2026-04-10T12:00:00Z",
"config": {
"endpointUrl": "https://s3.eu-central-1.amazonaws.com",
"destinationPath": "s3://my-codesphere-backups/",
"accessKey": "YOUR_S3_ACCESS_KEY"
},
"secrets": {
"secretKey": "YOUR_S3_SECRET_KEY"
}
}
}'

Wiederherstellung aus einem bestimmten Backup​

Alternativ kann aus einer bestimmten backupId wiederhergestellt werden:

curl -X POST "https://api.codesphere.com/managed-services" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"resourceGroupId": 123,
"name": "my-postgres-recovered",
"provider": {
"name": "postgres",
"version": "v1"
},
"plan": {
"id": 0,
"parameters": { "storage": 2048 }
},
"config": {
"version": "17.9"
},
"secrets": {
"userPassword": "secure-password",
"superuserPassword": "secure-superuser-password"
},
"recoverFrom": {
"id": "BACKUP_UUID_HERE",
"config": {
"endpointUrl": "https://s3.eu-central-1.amazonaws.com",
"destinationPath": "s3://my-codesphere-backups/",
"accessKey": "YOUR_S3_ACCESS_KEY"
},
"secrets": {
"secretKey": "YOUR_S3_SECRET_KEY"
}
}
}'

Einschränkungen und Hinweise zu Backups​

Die folgenden Einschränkungen und Anforderungen gelten speziell für das Sichern und Wiederherstellen von PostgreSQL-Datenbanken:

  • Transaktion erforderlich: Um eine Postgres-Datenbank wiederherzustellen, muss mindestens eine Datenbanktransaktion stattgefunden haben.
  • Vorheriges Backup erforderlich: Vor dem gewünschten Ziel-Wiederherstellungszeitpunkt muss mindestens ein abgeschlossenes Backup vorliegen.
  • WAL-Datei-Timing: Der Ziel-Wiederherstellungszeitpunkt muss vor der letzten Transaktion in der aktuellsten Write-Ahead Log (WAL)-Datei liegen. Es kann einige Minuten dauern, bis die aktuellste WAL-Datei im Backup-Storage-Bucket gespeichert wird.
  • Versionskompatibilität: Die Wiederherstellung eines Backups mit einer anderen Datenbankversion als der ursprünglichen Backup-Version funktioniert nicht garantiert.
  • Zugangsdaten müssen übereinstimmen: Bei der Wiederherstellung können Datenbankbenutzer, Datenbankname und Passwörter nicht auf andere Werte geändert werden als die ursprünglich im Backup gespeicherten.

Erweiterungen​

Das PostgreSQL-Image enthält eine Reihe von Erweiterungen, einschließlich PostGIS für räumliche Daten und pgvector für die Vektor-Ähnlichkeitssuche. Alle unten aufgeführten Erweiterungen sind auf jeder Instanz verfügbar, werden jedoch erst nach Aktivierung wirksam.

Eine Erweiterung aktivieren​

Erweiterungen werden pro Datenbank mit CREATE EXTENSION aktiviert. Dazu als postgres-Superuser mit der Zieldatenbank verbinden und Folgendes ausführen:

-- Eine Erweiterung aktivieren
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

-- Prüfen, welche Erweiterungen installiert sind
SELECT extname, extversion FROM pg_extension;

-- Eine Erweiterung wieder deaktivieren
DROP EXTENSION "uuid-ossp";

Alle verfügbaren Erweiterungen und ihre Versionen können direkt von der Instanz aufgelistet werden:

SELECT name, default_version, installed_version FROM pg_available_extensions ORDER BY name;

Verfügbare Erweiterungen​

ErweiterungVersionBeschreibung
address_standardizer3.6.0Zerlegt eine Adresse in ihre Bestandteile, wird in der Regel zur Unterstützung der Geocoding-Adressnormalisierung verwendet.
address_standardizer_data_us3.6.0Beispiel-Datensatz des Address Standardizer für die USA.
amcheck1.4Funktionen zur Überprüfung der Relationsintegrität.
autoinc1.0Funktionen zur automatischen Inkrementierung von Feldern.
bloom1.0Bloom-Zugriffsmethode — signaturdateibasierter Index.
btree_gin1.3Unterstützung für die Indizierung gängiger Datentypen in GIN.
btree_gist1.7Unterstützung für die Indizierung gängiger Datentypen in GiST.
citext1.6Datentyp für Groß-/Kleinschreibung-unabhängige Zeichenketten.
cube1.5Datentyp für mehrdimensionale Würfel.
dblink1.2Verbindung zu anderen PostgreSQL-Datenbanken aus einer Datenbank heraus.
dict_int1.0Textsuche-Wörterbuchvorlage für Ganzzahlen.
dict_xsyn1.0Textsuche-Wörterbuchvorlage für erweiterte Synonymverarbeitung.
earthdistance1.2Berechnung von Großkreisentfernungen auf der Erdoberfläche.
file_fdw1.0Foreign-Data-Wrapper für den Zugriff auf flache Dateien.
fuzzystrmatch1.2Bestimmung von Ähnlichkeiten und Abständen zwischen Zeichenketten.
hstore1.8Datentyp zum Speichern von (Schlüssel, Wert)-Paaren.
insert_username1.0Funktionen zur Nachverfolgung, wer eine Tabelle geändert hat.
intagg1.1Integer-Aggregator und -Enumerator (veraltet).
intarray1.5Funktionen, Operatoren und Indexunterstützung für 1D-Arrays von Ganzzahlen.
isn1.2Datentypen für internationale Produktnummerierungsstandards.
lo1.1Wartung von Large Objects.
ltree1.3Datentyp für hierarchische, baumartige Strukturen.
moddatetime1.0Funktionen zur Nachverfolgung der letzten Änderungszeit.
pageinspect1.12Inspektion des Inhalts von Datenbankseiten auf niedriger Ebene.
pg_buffercache1.5Untersuchung des Shared Buffer Cache.
pg_freespacemap1.2Untersuchung der Free Space Map (FSM).
pg_prewarm1.2Vorwärmen von Relationsdaten.
pg_stat_statements1.11Verfolgt Planungs- und Ausführungsstatistiken aller ausgeführten SQL-Anweisungen.
pg_surgery1.0Erweiterung zur Durchführung von Eingriffen an einer beschädigten Relation.
pg_trgm1.6Textähnlichkeitsmessung und Indexsuche basierend auf Trigrammen.
pg_visibility1.2Untersuchung der Visibility Map (VM) und seitenbezogener Sichtbarkeitsinformationen.
pg_walinspect1.1Funktionen zur Untersuchung des Inhalts des PostgreSQL Write-Ahead Logs.
pgaudit17.1Bietet Auditing-Funktionalität.
pgcrypto1.3Kryptografische Funktionen.
pgrowlocks1.2Anzeige von Informationen zu Sperren auf Zeilenebene.
pgstattuple1.5Anzeige von Statistiken auf Tupel-Ebene.
plpgsql1.0PL/pgSQL-Prozedursprache. Standardmäßig installiert.
postgis3.6.0PostGIS-Geometrie- und Geografie-Raumtypen und -Funktionen.
postgis_raster3.6.0PostGIS-Rastertypen und -Funktionen.
postgis_sfcgal3.6.0PostGIS SFCGAL-Funktionen.
postgis_tiger_geocoder3.6.0PostGIS TIGER-Geocoder und Reverse-Geocoder.
postgis_topology3.6.0PostGIS-Topologie-Raumtypen und -Funktionen.
postgres_fdw1.1Foreign-Data-Wrapper für entfernte PostgreSQL-Server.
refint1.0Funktionen zur Implementierung referentieller Integrität (veraltet).
seg1.4Datentyp zur Darstellung von Liniensegmenten oder Fließkomma-Intervallen.
sslinfo1.2Informationen über SSL-Zertifikate.
tablefunc1.0Funktionen zur Bearbeitung ganzer Tabellen, einschließlich Crosstab.
tcn1.0Getriggerte Änderungsbenachrichtigungen.
tsm_system_rows1.0TABLESAMPLE-Methode, die eine Anzahl von Zeilen als Limit akzeptiert.
tsm_system_time1.0TABLESAMPLE-Methode, die eine Zeit in Millisekunden als Limit akzeptiert.
unaccent1.1Textsuche-Wörterbuch, das Akzente entfernt.
uuid-ossp1.1Generierung universell eindeutiger Identifikatoren (UUIDs).
vector0.8.1Vektordatentyp sowie ivfflat- und hnsw-Zugriffsmethoden (pgvector).
xml21.1XPath-Abfragen und XSLT.

Shutdown-Verhalten​

Die Datenbank wird von Zeit zu Zeit heruntergefahren und neu gestartet, etwa für Konfigurationsänderungen, Image-Updates oder Plattform-Updates. Wie sich der PostgreSQL-Service dabei verhält, hängt von der Anzahl seiner Instanzen ab.

Einzelinstanz​

Bei einer einzelnen Instanz wird die Datenbank gestoppt und wieder gestartet. Die Daten bleiben auf dem persistenten Volume erhalten und sind vom Neustart nicht betroffen.

Die Downtime hängt davon ab, ob Clients ihre Verbindungen beim Start des Shutdowns offen halten. Die Datenbank nimmt sofort keine neuen Verbindungen mehr an und gibt bestehenden Verbindungen bis zu 180 Sekunden Zeit, sich selbstständig zu schließen. Danach werden die verbleibenden Verbindungen geschlossen.

SituationVerhaltenUngefähre Downtime
Alle Clients trennen sich kurz nach Beginn des ShutdownsDie Datenbank stoppt sauber, ohne zu warten.Etwa 1 Minute
Mindestens ein Client hält die Verbindung offenDie Datenbank wartet 180 Sekunden und schließt dann die verbleibenden Verbindungen.Etwa 4 Minuten

Neue Verbindungen werden ab dem Beginn des Shutdowns abgelehnt. Das bedeutet, dass die Datenbank für neue Clients während der gesamten Dauer nicht verfügbar ist, auch wenn bestehende Verbindungen noch funktionieren.

Anwendungen mit einem Connection Pool halten in der Regel langlebige Verbindungen und trennen sich nicht von selbst. Bei solchen Anwendungen ist mit dem längeren Fall zu rechnen.

Hochverfügbarkeit (drei Instanzen)​

Mit drei Instanzen läuft der Service mit einem Primary und zwei Replikaten. Die Instanzen werden nach Möglichkeit auf verschiedene Nodes verteilt.

Wenn der Primary heruntergefahren wird, wechselt der Service zu einem Replikat. Der alte Primary wird sofort gestoppt, ohne auf offene Verbindungen zu warten, und ein Replikat übernimmt die Rolle des neuen Primary.

SituationVerhaltenUngefähre Downtime
Der Primary wird heruntergefahrenEin Replikat übernimmt die Rolle des Primary. Bestehende Verbindungen werden sofort geschlossen.Etwa 10 bis 20 Sekunden

Clients müssen nach dem Failover erneut verbinden. Anwendungen, die fehlgeschlagene Verbindungen automatisch erneut versuchen, erholen sich von selbst.

Datensicherheit​

  • Committete Transaktionen sind sicher.
  • Transaktionen, die beim Schließen der Verbindungen noch offen sind, werden zurückgerollt. Clients erhalten einen Verbindungsfehler und müssen es erneut versuchen.
  • Bei drei Instanzen wird der alte Primary sauber gestoppt, bevor ein Replikat befördert wird, sodass der neue Primary über alle committeten Daten verfügt.