Service: FerretDB - EyevinnOSC/community GitHub Wiki

FerretDB

FerretDB (serviceId ferretdb-ferretdb) is an open source, MongoDB-compatible database (license Apache-2.0). It works as a proxy: it accepts MongoDB wire protocol queries, translates them to SQL and stores the data in PostgreSQL with the DocumentDB extension. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance. Its storage backend is the separate OSC service PostgreSQL DocumentDB (ferretdb-documentdb), documented below.

What it can do

  • Let applications that use MongoDB drivers and tools (MongoDB 5.0+) store data in PostgreSQL without code changes.
  • Act as a drop-in replacement for MongoDB in many cases.
  • Run on a managed PostgreSQL DocumentDB backend in the same OSC workspace.

Creating an instance

Create the backend first: create-service-instance with serviceId: "ferretdb-documentdb" (see "PostgreSQL DocumentDB options" below) and confirm it is running with wait-for-service-ready or get-instance-status. Then create FerretDB with serviceId: "ferretdb-ferretdb":

{
  "name": "myferret",
  "PostgresqlUrl": "{{secrets.ferretpgurl}}"
}

PostgresqlUrl is the connection URL of the DocumentDB instance, including credentials. Use describe-service-instance on the DocumentDB instance to get its address, port and credentials, store the URL as a service secret with create-service-secret, and pass it as {{secrets.NAME}} (the reference must be the entire field value). The catalog links this option to ferretdb-documentdb with credentials included.

FerretDB has no default admin username and password of its own. Authentication is governed by the credentials of the PostgreSQL DocumentDB instance it is connected to.

Options

Option Required Type Meaning
name Yes string Name of the instance. Letters, digits and underscore (^\w+$); OSC limits names to 20 characters.
PostgresqlUrl Yes string, sensitive Connection URL (postgres protocol) to the PostgreSQL DocumentDB instance used as storage, with credentials.
LogLevel No string Log verbosity of FerretDB. The catalog gives no description or list of accepted values; not verified.

PostgreSQL DocumentDB (ferretdb-documentdb)

PostgreSQL DocumentDB is a document database engine built as PostgreSQL extensions that add a BSON data type and a DocumentDB API (collections, queries, updates, indexes including TTL, aggregation pipelines). License MIT. It is a long-running service instance with up to 10 GiB of storage per instance and no dependencies on other OSC services. See also the PostgreSQL DocumentDB page.

{ "name": "mydocdb", "PostgresPassword": "{{secrets.documentdbpwd}}" }

PostgreSQL DocumentDB options

Option Required Type Meaning
name Yes string Name of the instance. Letters, digits and underscore (^\w+$); OSC limits names to 20 characters.
PostgresPassword Yes string, sensitive Password for the underlying PostgreSQL. Pass it as {{secrets.NAME}}.
InitdbSql No string SQL that runs when the database is first initialized.

Resources