Configuration flags

FerretDB provides numerous configuration flags you can customize to suit your needs and environment. You can always see the complete list by using --help flag. To make user experience cloud native, every flag has its environment variable equivalent. There is no configuration file.

Configuration flags - 图1info

Some default values are overridden in our Docker image.

General

FlagDescriptionEnvironment VariableDefault Value
-h, —helpShow context-sensitive helpfalse
—versionPrint version to stdout and exitfalse
—handlerBackend handlerFERRETDB_HANDLERpg (PostgreSQL)
—modeOperation modeFERRETDB_MODEnormal
—state-dirPath to the FerretDB state directory
(set to - to disable)
FERRETDB_STATE_DIR.
(/state for Docker)
—repl-set-nameReplica set name
(should be set for OpLog to work correctly)
FERRETDB_REPL_SET_NAMEempty

Interfaces

FlagDescriptionEnvironment VariableDefault Value
—listen-addrListen TCP addressFERRETDB_LISTEN_ADDR127.0.0.1:27017
(:27017 for Docker)
—listen-unixListen Unix domain socket pathFERRETDB_LISTEN_UNIX
—listen-tlsListen TLS address (see here)FERRETDB_LISTEN_TLS
—listen-tls-cert-fileTLS cert file pathFERRETDB_LISTEN_TLS_CERT_FILE
—listen-tls-key-fileTLS key file pathFERRETDB_LISTEN_TLS_KEY_FILE
—listen-tls-ca-fileTLS CA file pathFERRETDB_LISTEN_TLS_CA_FILE
—proxy-addrProxy addressFERRETDB_PROXY_ADDR
—proxy-tls-cert-fileProxy TLS cert file pathFERRETDB_PROXY_TLS_CERT_FILE
—proxy-tls-key-fileProxy TLS key file pathFERRETDB_PROXY_TLS_KEY_FILE
—proxy-tls-ca-fileProxy TLS CA file pathFERRETDB_PROXY_TLS_CA_FILE
—debug-addrListen address for HTTP handlers for metrics, profiling, etc
(set to - to disable)
FERRETDB_DEBUG_ADDR127.0.0.1:8088
(:8088 for Docker)

Backend handlers

PostgreSQL

PostgreSQL backend can be enabled by --handler=pg flag or FERRETDB_HANDLER=pg environment variable.

FlagDescriptionEnvironment VariableDefault Value
—postgresql-urlPostgreSQL URL for ‘pg’ handlerFERRETDB_POSTGRESQL_URLpostgres://127.0.0.1:5432/ferretdb

FerretDB uses pgx v5 library for connecting to PostgreSQL. Supported URL parameters are documented there:

Additionally:

  • pool_max_conns parameter is set to 50 if it is unset in the URL;
  • application_name is always set to “FerretDB”;
  • timezone is always set to “UTC”.

SQLite

SQLite backend can be enabled by --handler=sqlite flag or FERRETDB_HANDLER=sqlite environment variable.

FlagDescriptionEnvironment VariableDefault Value
—sqlite-urlSQLite URI (directory) for ‘sqlite’ handlerFERRETDB_SQLITE_URLfile:data/ .
(file:/state/ for Docker)

FerretDB uses modernc.org/sqlite library for accessing SQLite database files. Supported URL parameters are documented there:

Additionally:

  • _pragma=auto_vacuum(none) parameter is set if that PRAGMA is not present;
  • _pragma=busy_timeout(10000) parameter is set if that PRAGMA is not present;
  • _pragma=journal_mode(wal) parameter is set if that PRAGMA is not present.

One difference is that URI should point to the existing directory (with absolute or relative path), not to a single database file. That allows FerretDB to work with multiple databases.

In-memory SQLite databases are fully supported. In that case, the URI should still point to the existing directory (that will be unused). For example: file:./?mode=memory.

Miscellaneous

FlagDescriptionEnvironment VariableDefault Value
—log-levelLog level: ‘debug’, ‘info’, ‘warn’, ‘error’FERRETDB_LOG_LEVELinfo
—[no-]log-uuidAdd instance UUID to all log messagesFERRETDB_LOG_UUID
—[no-]metrics-uuidAdd instance UUID to all metricsFERRETDB_METRICS_UUID
—otel-traces-urlOpenTelemetry OTLP/HTTP traces endpoint URL (e.g. http://host:4318/v1/traces)FERRETDB_OTEL_TRACES_URLempty (disabled)
—telemetryEnable or disable basic telemetryFERRETDB_TELEMETRYundecided