Version: Weekly Build

Codesphere DocumentDB

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

Eigenschaft	Wert	Hinweise
Provider-Name	`ferretdb`	Wird in Landscape-Provider-Definitionen verwendet.
Version	`v0`	Aktuelle vom Provider bereitgestellte Schemaversion.
Kategorie	`Database`	Wird im Managed-Services-Katalog angezeigt.
Geltungsbereich	`global`	Verfügbar auf Resource-Group-Ebene statt an eine einzelne Workspace-Runtime gebunden.
Resource-Group-Singleton	`false`	Resource Groups können mehrere DocumentDB-Service-Instanzen erstellen.
Pause-Unterstützung	`true`	Dieser Provider unterstützt das Pausieren.

Preview-Feature

Dieser Provider ist derzeit ein Preview-Feature. Er ist standardmäßig nicht aktiviert und muss vom Betreiber freigeschaltet werden. Als Preview befindet sich der Provider noch in der Weiterentwicklung; sein Schema, die Pläne und das Verhalten können sich künftig ändern.

Funktionen

Funktion	Unterstützt	Hinweise
Backups	✅	Backups werden im Object Store als native PostgreSQL-Physical-Backups gespeichert, unter Nutzung der Standard-PostgreSQL-Speicherarchitektur. Es handelt sich nicht um MongoDB-Dumps.
Point-in-Time Recovery	✅	Die Datenbank kann auf einen bestimmten Zeitpunkt wiederhergestellt werden.

Gut zu wissen

Hochverfügbarkeit ist noch nicht verfügbar; der Service läuft als Einzelinstanz.
Upgrades werden niemals automatisch durchgeführt.
Storage wächst nicht automatisch, der storage-Planparameter kann jedoch jederzeit manuell erhöht werden.

Architektur

Ein DocumentDB-Service besteht aus zwei Komponenten:

PostgreSQL mit der DocumentDB-Erweiterung — die eigentliche Daten-Engine. Ein dedizierter PostgreSQL-Server, betrieben vom CloudNativePG-Operator, führt die Open-Source-DocumentDB-Erweiterung aus, die BSON-Dokumentenspeicherung und -verarbeitung innerhalb von PostgreSQL implementiert.
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.

Die 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.

Zu beachten:

Fixierte Versionen: Das Konfigurationsfeld version legt eine kompatible Kombination aus PostgreSQL-Hauptversion, DocumentDB-Erweiterungsversion und FerretDB-Version fest — zum Beispiel ist 17-0.107.0-ferretdb-2.7.0 PostgreSQL 17 mit DocumentDB 0.107.0 und FerretDB 2.7.0.
Readiness betrifft 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 Daten-Engine PostgreSQL ist, werden Backups im Object Store als native PostgreSQL-Physical-Backups gespeichert, nicht als MongoDB-Dumps. Sie können in einen DocumentDB-Service zurückgespielt werden, sind aber nicht mit mongodump-Archiven austauschbar.
Kein Write-Buffering: Der Proxy puffert oder queued keine Anfragen. Ist die PostgreSQL-Instanz nicht erreichbar, 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 Multi-Document-Transaktionen nicht verfügbar. Die vollständige Liste findet sich in der FerretDB-Kompatibilitätsdokumentation.
Gemeinsame Grundlage: Storage (replizierter Ceph-Block-Storage) und Networking funktionieren genauso wie im PostgreSQL-Provider.

Schema

Config

Feld	Typ	Bei Erstellung erforderlich	Hinweise
`version`	`string`	Nein	Provider-Version für den Postgres-, DocumentDB- und FerretDB-Stack. Standard- und einziger zulässiger Wert: `17-0.107.0-ferretdb-2.7.0`.

Secrets

Feld	Typ	Bei Erstellung erforderlich	Hinweise
`superuserPassword`	`string`	Ja	Passwort für den administrativen Benutzer.

Details / Ausgabe

Feld	Typ	Verfügbarkeit	Hinweise
`hostname`	`string`	Nach dem Provisioning verfügbar	Interner Hostname des MongoDB-kompatiblen Endpunkts.
`port`	`integer`	Nach dem Provisioning verfügbar	MongoDB-kompatibler Port.
`dsn`	`string`	Nach dem Provisioning verfügbar	MongoDB-Verbindungsstring für den Admin-Benutzer.
`postgresHostname`	`string`	Nach dem Provisioning verfügbar	Interner Hostname der zugrunde liegenden PostgreSQL-Instanz.
`postgresDSN`	`string`	Nach dem Provisioning verfügbar	PostgreSQL-Verbindungsstring für den direkten Zugriff auf die zugrunde liegende Datenbank.
`ready`	`boolean`	Nach dem Provisioning verfügbar	Gibt an, ob die Instanz für Verbindungen bereit ist.

Plan

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

Parameter	Typ	Standard	Minimum	Maximum	Statisch	Hinweise
`cpu`	`number`	`1`	-	-	Ja	PostgreSQL-CPU-Zuteilung, abgerechnet als `cpu-tenths`.
`memory`	`integer`	`512`	-	-	Ja	PostgreSQL-Speicherzuteilung in MiB, abgerechnet als `ram-mib`.
`storage`	`integer`	`1024`	`1024`	-	Nein	Persistenter Speicher in MiB, abgerechnet als `storage-mib`.
`ferretdbCpu`	`number`	`1`	`1`	`1`	Ja	FerretDB-CPU-Zuteilung, abgerechnet als `cpu-tenths`.
`ferretdbMemory`	`integer`	`64`	`64`	`128`	Ja	FerretDB-Speicherzuteilung in MiB, abgerechnet als `ram-mib`.

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 zusammensetzen

Hostnamen von Landscape-verwalteten Services 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.

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

Für den zugrunde liegenden PostgreSQL-Endpunkt lässt sich der Hostname als ms-postgres-v1-$TEAM_ID-landscape-$WORKSPACE_ID-db.rg-$TEAM_ID in Shell-Befehlen bzw. ms-postgres-v1-${{ resourceGroup.id }}-landscape-${{ workspace.id }}-db.rg-${{ resourceGroup.id }} in Landscape-Templates konstruieren.

Provider	Version	Resource-Group-ID	Workspace-ID	Service-Name	Hostname
`ferretdb`	`v0`	`42`	`100`	`db`	`ms-ferretdb-v0-42-landscape-100-db.rg-42`
`postgres`	`v1`	`42`	`100`	`db`	`ms-postgres-v1-42-landscape-100-db.rg-42`

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.rg-$TEAM_ID: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-${{ resourceGroup.id }}-landscape-${{ workspace.id }}-db.rg-${{ resourceGroup.id }}
      DOCDB_PASSWORD: "${{ vault.documentDbSuperuserPassword }}"

Application-Runtimes können den MongoDB-kompatiblen dsn für dokumentbasierte Workloads nutzen. Wird für Migrationen, Wartung oder erweiterte Erweiterungen direkter PostgreSQL-Zugriff benötigt, kann stattdessen postgresDSN verwendet werden. Beide Endpunkte sind von anderen Codesphere-Runtimes aus erreichbar, einschließlich Reactives, Managed Containers und Virtual-Cluster-Workloads.

Verbindung zu DocumentDB herstellen

Voraussetzungen

Sobald die DocumentDB bereitgestellt wurde, kann aus Codesphere-Workspaces heraus eine Verbindung hergestellt werden. Jeder Service listet nicht sensible Verbindungsdetails auf der jeweiligen Einstellungsseite im Übersichts-Tab (bzw. in der Eigenschaft details im Public-API-Payload).

info

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

Verbinden über das Terminal (`mongosh`)

mongosh kann verwendet werden, um sich vom Workspace-Terminal aus zu verbinden.

Keine TLS-Verschlüsselung zwischen dem Client und dem FerretDB-Proxy

# 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!" })

Verbinden ü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 Daten-Engine eines DocumentDB-Service ein regulärer PostgreSQL-Server ist, funktionieren Backups genau wie Backups des PostgreSQL-Providers: Das CloudNativePG-Barman-Cloud-Plugin speichert native PostgreSQL-Physical-Backups im S3-kompatiblen Backup-Store und archiviert das Write-Ahead-Log fortlaufend, was Point-in-Time Recovery ermöglicht.

Dabei ist zu beachten, dass es sich bei Backups um PostgreSQL-Backups und nicht um MongoDB-Dumps handelt: Sie können in einen neuen DocumentDB-Service zurückgespielt werden, sind aber nicht mit mongodump-Archiven austauschbar.

Wer native MongoDB-Dumps bevorzugt, kann diese auch selbst mit mongodump gegen den Service-Endpunkt erstellen. Das Zurückspielen eines solchen Dumps in einen DocumentDB-Service mit mongorestore funktioniert ebenfalls, ist jedoch ein manueller Schritt und kein von Codesphere automatisierter Ablauf.

Konfiguration, Wiederherstellung, erforderliche S3-Berechtigungen und Einschränkungen sind identisch zu PostgreSQL — Beispiele finden sich in der PostgreSQL-Backup-Dokumentation.

Funktionen​

Architektur​

Schema​

Config​

Secrets​

Details / Ausgabe​

Plan​

Beispiel in einer Landscape​

Hostnamen zusammensetzen​

Verbindung zu DocumentDB herstellen​

Voraussetzungen​

Verbinden über das Terminal (mongosh)​

Verbinden über Node.js​

Backups​