Codesphere DocumentDB

Codesphere DocumentDB stellt eine MongoDB-kompatible Dokumentendatenbank bereit, die auf PostgreSQL, der DocumentDB-Erweiterung und FerretDB basiert. Sie ist für dokumentenorientierte Anwendungen gedacht, die MongoDB-Protokollkompatibilität innerhalb von Codesphere benötigen.

Funktionen​

Architektur​

Ein DocumentDB-Service besteht aus zwei Komponenten:

1. PostgreSQL mit DocumentDB-Erweiterung — die eigentliche Datenengine. Ein dedizierter PostgreSQL-Server, betrieben durch den CloudNativePG-Operator, führt die Open-Source-DocumentDB-Erweiterung aus, die BSON-Dokumentspeicherung und -verarbeitung innerhalb von PostgreSQL implementiert.
2. FerretDB-Proxy — ein zustandsloses FerretDB-Deployment vor der Datenbank. Es spricht das MongoDB-Wire-Protokoll (kompatibel mit MongoDB-5.0+-Treibern) und übersetzt Client-Befehle in Abfragen gegen die DocumentDB-Erweiterung.

Deine Anwendung verbindet sich mit dem FerretDB-Endpunkt (dem dsn, Port 27017) über Standard-MongoDB-Treiber, während die Daten selbst in PostgreSQL liegen. Die zugrunde liegende PostgreSQL-Instanz ist für Migrationen und Wartung direkt über postgresDSN erreichbar.

Wichtige Hinweise:

• Fixierte Versionen: Das Konfigurationsfeld version fixiert eine kompatible Kombination aus PostgreSQL-Hauptversion, DocumentDB-Erweiterungsversion und FerretDB-Version — zum Beispiel ist 17-0.107.0-ferretdb-2.7.0 PostgreSQL 17 mit DocumentDB 0.107.0 und FerretDB 2.7.0.
• Readiness umfasst beide Komponenten: Das ready-Detail ist nur dann true, wenn sowohl der FerretDB-Proxy als auch die PostgreSQL-Instanz laufen.
• Backups im PostgreSQL-Format: Da die Datenengine PostgreSQL ist, werden Backups im Object Store als native PostgreSQL-Physical-Backups gespeichert, nicht als MongoDB-Dumps. Sie können in einen DocumentDB-Service wiederhergestellt werden, sind jedoch nicht mit mongodump-Archiven austauschbar.
• Keine Schreibpufferung: Der Proxy stellt keine Anfragen in eine Warteschlange und puffert sie nicht. Wenn die PostgreSQL-Instanz nicht verfügbar ist, schlagen Lese- und Schreibvorgänge sofort fehl, anstatt zurückgehalten und erneut versucht zu werden.
• MongoDB-Kompatibilität ist nicht vollständig: FerretDB unterstützt die meisten, aber nicht alle MongoDB-Befehle — zum Beispiel sind Change Streams und Mehrdokument-Transaktionen nicht verfügbar. Siehe die FerretDB-Kompatibilitätsdokumentation für die vollständige Liste.
• Gemeinsame Grundlage: Storage (repliziertes Ceph-Block-Storage) und Netzwerk funktionieren genauso wie beim PostgreSQL-Provider.

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:
  docs-db:
    provider:
      name: ferretdb
      version: v0
    plan:
      id: 0
      parameters:
        storage: 2048
        memory: 512
        cpu: 1
        ferretdbMemory: 64
        ferretdbCpu: 1
    config:
      version: "17-0.107.0-ferretdb-2.7.0"
    secrets:
      superuserPassword: "${{ vault.documentDbSuperuserPassword }}"

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.

Für den MongoDB-kompatiblen Service-Endpunkt lautet der Provider-Name ferretdb. Wenn dein DocumentDB-Service db heißt, ergibt sich der Hostname ms-ferretdb-v0-$TEAM_ID-landscape-$WORKSPACE_ID-db.ms-postgres in Shell-Befehlen bzw. ms-ferretdb-v0-${{ team.id }}-landscape-${{ workspace.id }}-db.ms-postgres in Landscape-Templates.

Für den zugrunde liegenden PostgreSQL-Endpunkt kann der Hostname als ms-postgres-v1-$TEAM_ID-landscape-$WORKSPACE_ID-db.ms-postgres in Shell-Befehlen bzw. ms-postgres-v1-${{ team.id }}-landscape-${{ workspace.id }}-db.ms-postgres in Landscape-Templates konstruiert werden.

Beispiel für eine ci.yml, die den konstruierten Hostnamen direkt in einem Befehl verwendet:

schemaVersion: v0.2

run:
  db:
    provider:
      name: ferretdb
      version: v0
    plan:
      id: 0
      parameters:
        storage: 2048
        memory: 512
        cpu: 1
        ferretdbMemory: 64
        ferretdbCpu: 1
    config:
      version: "17-0.107.0-ferretdb-2.7.0"
    secrets:
      superuserPassword: "${{ vault.documentDbSuperuserPassword }}"

  api:
    steps:
      - command: >
          mongosh "mongodb://postgres:${DOCDB_PASSWORD}@ms-ferretdb-v0-$TEAM_ID-landscape-$WORKSPACE_ID-db.ms-postgres:27017/ferretdb?authSource=postgres"
    env:
      DOCDB_PASSWORD: "${{ vault.documentDbSuperuserPassword }}"

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

schemaVersion: v0.2

run:
  db:
    provider:
      name: ferretdb
      version: v0
    plan:
      id: 0
      parameters:
        storage: 2048
        memory: 512
        cpu: 1
        ferretdbMemory: 64
        ferretdbCpu: 1
    config:
      version: "17-0.107.0-ferretdb-2.7.0"
    secrets:
      superuserPassword: "${{ vault.documentDbSuperuserPassword }}"

  api:
    steps:
      - command: >
          psql "postgres://postgres:${DOCDB_PASSWORD}@${DOCDB_POSTGRES_HOST}:5432/postgres" -c "select 1"
    env:
      DOCDB_POSTGRES_HOST: ms-postgres-v1-${{ team.id }}-landscape-${{ workspace.id }}-db.ms-postgres
      DOCDB_PASSWORD: "${{ vault.documentDbSuperuserPassword }}"

Application-Runtimes können den MongoDB-kompatiblen dsn für dokumentenbasierte Workloads verwenden. Wenn du für Migrationen, Wartung oder erweiterte Erweiterungen direkten PostgreSQL-Zugriff benötigst, verwende stattdessen postgresDSN. Beide Endpunkte sind von anderen Codesphere-Runtimes aus erreichbar, einschließlich Reactives, Managed Containers und Virtual Cluster-Workloads.

Verbindung zu DocumentDB herstellen​

Voraussetzungen​

Sobald deine DocumentDB bereitgestellt ist, kannst du dich von deinen Codesphere-Workspaces aus damit verbinden. Jeder Service listet nicht-sensible Verbindungsdetails auf der jeweiligen Einstellungsseite im Übersichts-Tab (oder in der Eigenschaft details in der öffentlichen API-Payload).

Verbindung über Terminal (mongosh)​

Du kannst mongosh verwenden, um dich vom Terminal deines Workspaces aus zu verbinden.

# mongosh installieren
nix-env -iA nixpkgs.mongosh
source ~/.nix-profile/etc/profile.d/nix.sh

# Syntax
mongosh "mongodb://<username>:<password>@<hostname>:27017/ferretdb?authSource=postgres"

# Beispiel
db.myCollection.insertOne({ message: "Hello Codesphere!" })

Verbindung über Node.js​

Mit dem mongodb-Treiber:

const { MongoClient } = require('mongodb');

const client = new MongoClient(
    'mongodb://postgres:[email protected]:27017/ferretdb'
);

await client.connect();
const db = client.db('ferretdb');
const collection = db.collection('myCollection');

const result = await collection.insertOne({ message: 'Hello Codesphere!' });
console.log(result.insertedId);

await client.close();

Backups​

Da die Datenengine eines DocumentDB-Services ein regulärer PostgreSQL-Server ist, funktionieren Backups genau wie beim PostgreSQL-Provider: Das CloudNativePG-Barman-Cloud-Plugin speichert native PostgreSQL-Physical-Backups in deinem S3-kompatiblen Backup-Store und archiviert kontinuierlich das Write-Ahead-Log, was Point-in-Time Recovery ermöglicht.

Beachte, dass es sich bei Backups um PostgreSQL-Backups handelt, nicht um MongoDB-Dumps: Sie können in einen neuen DocumentDB-Service wiederhergestellt werden, sind jedoch nicht mit mongodump-Archiven austauschbar.

Wenn du native MongoDB-Dumps bevorzugst, kannst du diese auch selbst mit mongodump gegen den Service-Endpunkt erstellen. Das Wiederherstellen eines solchen Dumps in einen DocumentDB-Service mit mongorestore funktioniert ebenfalls, ist aber ein manueller Schritt und kein von Codesphere automatisierter Ablauf.

Konfiguration, Wiederherstellung, erforderliche S3-Berechtigungen und Einschränkungen sind identisch zu PostgreSQL — siehe die PostgreSQL-Backup-Dokumentation für Beispiele.