PostgreSQL

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

Funktionen​

Architektur​

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

• Dedizierte Instanz: Die Datenbank läuft in einem eigenen Pod mit eigenem persistenten Volume. Es wird nichts mit anderen Services oder Teams geteilt.
• Speicher: Daten werden auf Ceph-Block-Storage (RBD) gespeichert, das auf Storage-Ebene repliziert wird.
• Backups: Backups werden kontinuierlich in Object Storage archiviert, was sowohl die Wiederherstellung eines bestimmten Backups als auch Point-in-Time Recovery ermöglicht.
• Container-Image: Codesphere liefert eigene PostgreSQL-Images, basierend auf den CloudNativePG-Images, mit den unten aufgeführten Erweiterungen vorinstalliert.
• Einzelinstanz: Da der Service als Einzelinstanz ohne Replikate läuft, können Konfigurationsänderungen und Versions-Upgrades zu einer kurzen Downtime führen.

Schema​

Konfiguration​

Secrets​

Details / Ausgabe​

Plan​

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

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 der Landscape verwaltete Service-Hostnamen sind deterministisch und folgen dieser Struktur:

ms-{providerName}-{providerVersion}-{teamId}-landscape-{workspaceId}-{serviceName}.ms-postgres

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

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

Beispiel für eine 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.ms-postgres:5432/app" -c "select 1"
    env:
      PG_PASSWORD: "${{ vault.pgUserPassword }}"

Beispiel für eine 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-${{ team.id }}-landscape-${{ workspace.id }}-db.ms-postgres
      PG_PASSWORD: "${{ vault.pgUserPassword }}"

Innerhalb von Anwendungs-Runtimes wird die Verbindung über den zurückgegebenen dsn oder über hostname, port, den konfigurierten Benutzernamen und das gespeicherte Passwort aufgebaut. 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 den Codesphere-Workspaces aus eine Verbindung dazu aufgebaut werden. Jeder Service listet seine nicht sensiblen Verbindungsdetails auf seiner Einstellungsseite im Übersichtstab auf (oder in der Eigenschaft details des öffentlichen API-Payloads).

Verbindung über das Terminal (psql)​

Das Kommandozeilentool psql kann direkt aus dem 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 in jeden S3-kompatiblen Backup-Store. Dieser Abschnitt enthält 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 periodisch 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 ebenso 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"
      }
    }
  }'

Erforderliche S3-Berechtigungen​

Die Zugangsdaten (Access Key und Secret Key), die für den Zugriff auf den S3-kompatiblen Backup-Store verwendet werden, müssen ausreichende Berechtigungen zum Erstellen, Lesen, Aktualisieren und Löschen von Objekten besitzen. Bei AWS S3 bedeutet das, dass der IAM-Benutzer oder die Rolle, die mit dem Access Key verknüpft ist, mindestens die folgenden Berechtigungen benötigt.

{
  "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 Wiederherstellungen​

Das Wiederherstellen eines Backups erstellt immer einen neuen Managed Service; der bestehende Service bleibt unverändert.

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 '{
    "teamId": 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 '{
    "teamId": 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"
      }
    }
  }'

Hinweise und Einschränkungen 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: Es muss mindestens ein abgeschlossenes Backup vor dem gewünschten Wiederherstellungszeitpunkt vorliegen.
• WAL-Datei-Zeitpunkt: Der Wiederherstellungszeitpunkt muss vor der letzten Transaktion in der letzten Write-Ahead-Log-Datei (WAL) liegen. Es kann einige Minuten dauern, bis die letzte WAL-Datei im Backup-Storage-Bucket gespeichert wird.
• Versionskompatibilität: Die Wiederherstellung eines Backups mit einer anderen Datenbankversion als der ursprünglichen ist nicht garantiert funktionsfähig.
• Zugangsdaten müssen übereinstimmen: Bei der Wiederherstellung können Datenbankbenutzer, Datenbankname und Passwörter nicht von den ursprünglich im Backup gespeicherten Werten abweichen.

Erweiterungen​

Das PostgreSQL-Image wird mit einer Reihe von Erweiterungen ausgeliefert, darunter PostGIS für räumliche Daten und pgvector für die Ähnlichkeitssuche von Vektoren. Alle unten aufgeführten Erweiterungen sind auf jeder Instanz verfügbar, jedoch erst aktiv, nachdem sie aktiviert wurden.

Eine Erweiterung aktivieren​

Erweiterungen werden pro Datenbank mit CREATE EXTENSION aktiviert. 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 aus aufgelistet werden:

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

Verfügbare Erweiterungen​