Codesphere DocumentDB

Codesphere DocumentDB exposes a MongoDB-compatible document database powered by PostgreSQL, the DocumentDB extension, and FerretDB. It is meant for document-oriented applications that want MongoDB protocol compatibility inside Codesphere.

Capabilities​

Architecture​

A DocumentDB service consists of two components:

1. PostgreSQL with the DocumentDB extension — the actual data engine. A dedicated PostgreSQL server, powered by the CloudNativePG operator, runs the open-source DocumentDB extension, which implements BSON document storage and processing inside PostgreSQL.
2. FerretDB proxy — a stateless FerretDB deployment in front of the database. It speaks the MongoDB wire protocol (compatible with MongoDB 5.0+ drivers) and translates client commands into queries against the DocumentDB extension.

Your application connects to the FerretDB endpoint (the dsn, port 27017) with standard MongoDB drivers, while the data itself lives in PostgreSQL. The underlying PostgreSQL instance is directly reachable via postgresDSN for migrations and maintenance.

Things to be aware of:

• Pinned versions: The version config field pins a compatible combination of PostgreSQL major version, DocumentDB extension version, and FerretDB version — for example, 17-0.107.0-ferretdb-2.7.0 is PostgreSQL 17 with DocumentDB 0.107.0 and FerretDB 2.7.0.
• Readiness covers both components: The ready detail is only true when both the FerretDB proxy and the PostgreSQL instance are up and running.
• Backups are in PostgreSQL format: Since the data engine is PostgreSQL, backups are stored in the object store as native PostgreSQL physical backups, not MongoDB dumps. They can be restored into a DocumentDB service, but they are not interchangeable with mongodump archives.
• No write buffering: The proxy does not queue or buffer requests. If the PostgreSQL instance is unavailable, reads and writes fail immediately instead of being held back and retried.
• MongoDB compatibility is not complete: FerretDB supports most, but not all, MongoDB commands — for example, change streams and multi-document transactions are not available. See the FerretDB compatibility documentation for the full list.
• Shared foundation: Storage (replicated Ceph block storage) and networking work the same way as in the PostgreSQL provider.

Schema​

Config​

Secrets​

Details / Output​

Plan​

The provider exposes one plan, Small (id: 0). Example plan: Small (id: 0).

Example in a 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 }}"

Constructing Hostnames​

Landscape-managed service hostnames are deterministic and follow this structure:

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

The hostname is converted to lowercase and any invalid characters are replaced with hyphens.

For the MongoDB-compatible service endpoint, the provider name is ferretdb. If your DocumentDB service is named db, that hostname resolves to ms-ferretdb-v0-$TEAM_ID-landscape-$WORKSPACE_ID-db.ms-postgres in shell commands or ms-ferretdb-v0-${{ team.id }}-landscape-${{ workspace.id }}-db.ms-postgres in landscape templates.

For the underlying PostgreSQL endpoint, the hostname can be constructed as ms-postgres-v1-$TEAM_ID-landscape-$WORKSPACE_ID-db.ms-postgres in shell commands or ms-postgres-v1-${{ team.id }}-landscape-${{ workspace.id }}-db.ms-postgres in landscape templates.

Example ci.yml using the constructed hostname directly in a command:

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 }}"

Example ci.yml using the constructed hostname through an environment variable:

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 can use the MongoDB-compatible dsn for document workloads. If you need direct PostgreSQL access for migrations, maintenance, or advanced extensions, use postgresDSN instead. Both endpoints are reachable from other Codesphere runtimes, including reactives, managed containers, and Virtual Cluster workloads.

Connecting to DocumentDB​

Prerequisites​

Once your DocumentDB is deployed, you can connect to it from your Codesphere workspaces. Each service lists non-sensitive connection details in their respective settings page, in the overview tab (or in the details property in the public API payload).

Connecting via Terminal (mongosh)​

You can use mongosh to connect from your workspace terminal.

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

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

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

Connecting via Node.js​

Using the mongodb driver:

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​

Since the data engine of a DocumentDB service is a regular PostgreSQL server, backups work exactly like backups of the PostgreSQL provider: the CloudNativePG Barman Cloud plugin stores native PostgreSQL physical backups in your S3-compatible backup store and continuously archives the write-ahead log, enabling point-in-time recovery.

Keep in mind that backups are PostgreSQL backups, not MongoDB dumps: they can be restored into a new DocumentDB service, but they are not interchangeable with mongodump archives.

If you prefer MongoDB-native dumps, you can also create them yourself with mongodump against the service endpoint. Restoring such a dump into a DocumentDB service with mongorestore works as well, but is a manual step, it is not a flow automated by Codesphere.

Configuration, recovery, required S3 permissions, and limitations are identical to PostgreSQL — see the PostgreSQL backup documentation for examples.