FerretDB

module
v2.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 3, 2025 License: Apache-2.0

README

FerretDB

[!TIP] Looking for FerretDB v1? It is there.

Go Reference

Go codecov

Security Packages Docs

FerretDB is an open-source alternative to MongoDB. It is a proxy that converts MongoDB 5.0+ wire protocol queries to SQL and uses PostgreSQL with DocumentDB extension as a database engine.

flowchart LR
  A["Any application<br>Any MongoDB driver"]
  F{{FerretDB}}
  P[(PostgreSQL<br>DocumentDB extension)]

  A -- "MongoDB protocol<br>BSON" --> F
  F -- "PostgreSQL protocol<br>SQL" --> P

Why do we need FerretDB?

MongoDB was originally an eye-opening technology for many of us developers, empowering us to build applications faster than using relational databases. In its early days, its ease-to-use and well-documented drivers made MongoDB one of the simplest database solutions available. However, as time passed, MongoDB abandoned its open-source roots; changing the license to SSPL - making it unusable for many open-source and early-stage commercial projects.

Most MongoDB users do not require any advanced features offered by MongoDB; however, they need an easy-to-use open-source document database solution. Recognizing this, FerretDB is here to fill that gap.

Scope and current state

FerretDB is compatible with MongoDB drivers and popular MongoDB tools. It functions as a drop-in replacement for MongoDB 5.0+ in many cases. Features are constantly being added to further increase compatibility and performance.

We welcome all contributors. See our public roadmap, lists of known differences and supported commands, and contributing guidelines.

Quickstart

Run this command to start FerretDB with PostgreSQL:

docker run -d --rm --name ferretdb -p 27017:27017 --platform linux/amd64 \
  ghcr.io/ferretdb/ferretdb-eval:2

This command will start a container with FerretDB, pre-packaged PostgreSQL with DocumentDB extension, and MongoDB Shell for quick testing and experiments. However, it is unsuitable for production use cases because it keeps all data inside and loses it on shutdown. See our installation guides for instructions that don't have those problems.

With that container running, you can:

  • Connect to it with any MongoDB client application using MongoDB URI mongodb://username:password@127.0.0.1:27017/.
  • Connect to it using MongoDB Shell by just running mongosh. If you don't have it installed locally, you can run docker exec -it ferretdb mongosh.
  • For PostgreSQL, connect to it by running docker exec -it ferretdb psql -U username postgres.

You can stop the container with docker stop ferretdb.

We also provide binaries and packages for various Linux distributions. as well as Go library package that embeds FerretDB into your application. See our documentation for more details.

Building and packaging

[!NOTE] We advise users not to build FerretDB themselves. Instead, use binaries, Docker images, or packages provided by us.

FerretDB could be built as any other Go program, but a few generated files and build tags could affect it. See there for more details.

Managed FerretDB at cloud providers

Community

If you want to contact FerretDB Inc., please use this form.

Directories

Path Synopsis
build
version
Package version provides information about FerretDB version and build configuration.
 Package version provides information about FerretDB version and build configuration.
cmd
envtool
ferretdb
Package ferretdb provides embeddable FerretDB implementation.
 Package ferretdb provides embeddable FerretDB implementation.
internal
clientconn
Package clientconn provides wire protocol server implementation.
 Package clientconn provides wire protocol server implementation.
clientconn/conninfo
Package conninfo provides access to connection-specific information.
 Package conninfo provides access to connection-specific information.
clientconn/connmetrics
Package connmetrics provides listener and connection metrics.
 Package connmetrics provides listener and connection metrics.
dataapi
Package dataapi provides a Data API wrapper, which allows FerretDB to be used over HTTP instead of MongoDB wire protocol.
 Package dataapi provides a Data API wrapper, which allows FerretDB to be used over HTTP instead of MongoDB wire protocol.
dataapi/api
Package api provides primitives to interact with the openapi HTTP API.
 Package api provides primitives to interact with the openapi HTTP API.
dataapi/server
Package server provides a Data API server handlers.
 Package server provides a Data API server handlers.
documentdb
Package documentdb provides DocumentDB extension integration.
 Package documentdb provides DocumentDB extension integration.
documentdb/cursor
Package cursor provides access to DocumentDB cursors.
 Package cursor provides access to DocumentDB cursors.
documentdb/documentdb_api
documentdb/documentdb_api_catalog
documentdb/documentdb_api_internal
documentdb/documentdb_core
documentdb/genwrap
Package main contains code generator for DocumentDB APIs.
 Package main contains code generator for DocumentDB APIs.
handler
Package handler provides implementations of command handlers.
 Package handler provides implementations of command handlers.
handler/middleware
Package middleware provides wrappers for command handlers.
 Package middleware provides wrappers for command handlers.
handler/proxy
Package proxy sends requests to another wire protocol compatible service.
 Package proxy sends requests to another wire protocol compatible service.
handler/session
Package session provides access to session registry.
 Package session provides access to session registry.
mongoerrors
Package mongoerrors provides MongoDB-compatible error types and codes.
 Package mongoerrors provides MongoDB-compatible error types and codes.
util/ctxutil
Package ctxutil provides context helpers.
 Package ctxutil provides context helpers.
util/debug
Package debug provides debug facilities.
 Package debug provides debug facilities.
util/devbuild
Package devbuild provides information about whatever this is a development build or not.
 Package devbuild provides information about whatever this is a development build or not.
util/hex
Package hex provides helpers for working with hex dumps.
 Package hex provides helpers for working with hex dumps.
util/iface
Package iface provides converters from functions/methods to interfaces, similarly to http.HandlerFunc.
 Package iface provides converters from functions/methods to interfaces, similarly to http.HandlerFunc.
util/lazyerrors
Package lazyerrors provides error wrapping with file location.
 Package lazyerrors provides error wrapping with file location.
util/logging
Package logging provides logging helpers.
 Package logging provides logging helpers.
util/must
Package must provides helper functions that panic on error.
 Package must provides helper functions that panic on error.
util/observability
Package observability provides abstractions for tracing, metrics, etc.
 Package observability provides abstractions for tracing, metrics, etc.
util/resource
Package resource provides utilities for tracking resource lifetimes.
 Package resource provides utilities for tracking resource lifetimes.
util/scram
Package scram provides an implementation of SCRAM-SHA-256 subset.
 Package scram provides an implementation of SCRAM-SHA-256 subset.
util/state
Package state stores FerretDB process state.
 Package state stores FerretDB process state.
util/telemetry
Package telemetry provides basic telemetry facilities.
 Package telemetry provides basic telemetry facilities.
util/testutil
Package testutil provides testing helpers.
 Package testutil provides testing helpers.
util/testutil/teststress
Package teststress provides a helper for stress testing.
 Package teststress provides a helper for stress testing.
util/tlsutil
Package tlsutil provides TLS utilities.
 Package tlsutil provides TLS utilities.
util/xiter
Package xiter provides iterator utilities.
 Package xiter provides iterator utilities.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.