Skip to main content
Version: v1.22

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.

info

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, pprof, 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
--telemetryEnable or disable basic telemetryFERRETDB_TELEMETRYundecided