How ferretdb/ferretdb works
FerretDB is a MongoDB wire-protocol proxy that translates client operations into PostgreSQL-backed document database work. The principal path is MongoDB client → connection/listener and middleware dispatch → command handling → DocumentDB/PostgreSQL, with results returned over the client connection. Separate HTTP Data API and MCP interfaces also feed the shared middleware. The README documents compatibility with MongoDB drivers and PostgreSQL with the DocumentDB extension. Some wiring is taken from that documentation and the sampled handler/API code; unsampled setup details are not inferred.
Main entry points: handler.go Command handler · setup.go Runtime setup · dispatcher.go Middleware dispatcher · pool.go DocumentDB pool
Components 18
Client protocols
- Wire listener
internal/clientconn/listener.go - Middleware dispatcher
internal/handler/middleware/dispatcher.go - Data API server
internal/dataapi/server/server.go - MCP server
internal/mcp/server.go - Proxy handler
internal/handlers/proxy/proxy.go
Query execution
- Command handler
internal/handler/handler.go - MongoDB commands
internal/handler/commands.go - Session registry
internal/handler/session/registry.go
Document storage
- DocumentDB pool
internal/documentdb/pool.go - DocumentDB API
internal/documentdb/documentdb_api/documentdb_api.go
Operations
- Runtime setup
internal/util/setup/setup.go - Telemetry
internal/util/telemetry/telemetry.go - Metrics state
internal/util/state/provider.go
Other components
- MongoDB client
- PostgreSQL + DocumentDB
- Data API client
- MCP client
- Proxy client
Connections 19
- MongoDB client → Wire listener: sends MongoDB protocol
- Wire listener → Middleware dispatcher: dispatches requests
- Middleware dispatcher → Command handler: routes commands
- Command handler → MongoDB commands: handles commands
- Command handler → DocumentDB pool: executes database work
- Command handler → Session registry: manages sessions
- DocumentDB pool → DocumentDB API: uses document API
- DocumentDB pool → PostgreSQL + DocumentDB: sends SQL
- Data API client → Data API server: sends HTTP requests
- Data API server → Middleware dispatcher: submits commands
- MCP client → MCP server: calls tools
- MCP server → Middleware dispatcher: submits commands
- Proxy client → Proxy handler: sends requests
- Runtime setup → Command handler: configures runtime
- Runtime setup → Wire listener: configures listener
- Runtime setup → Data API server: configures API
- Runtime setup → MCP server: configures MCP
- Command handler → Metrics state: exposes metrics
- Runtime setup → Telemetry: configures telemetry