README
¶
FerretDB
FerretDB was founded to become the de-facto open-source substitute to MongoDB. FerretDB is an open-source proxy, converting the MongoDB 6.0+ wire protocol queries to SQL - using PostgreSQL or SQLite as a database engine.
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 6.0+ in many cases. Features are constantly being added to further increase compatibility and performance.
We welcome all contributors. See our public roadmap, a list of known differences with MongoDB, and contributing guidelines.
Quickstart
Run this command to start FerretDB with PostgreSQL backend:
docker run -d --rm --name ferretdb -p 27017:27017 ghcr.io/ferretdb/all-in-one
Alternatively, run this command to start FerretDB with SQLite backend:
docker run -d --rm --name ferretdb -p 27017:27017 \
-v ./data:/data/ -e FERRETDB_HANDLER=sqlite -e FERRETDB_SQLITE_URL=file:/data/ \
ghcr.io/ferretdb/all-in-one
This command will start a container with FerretDB, PostgreSQL, 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 Docker quickstart guide 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://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 rundocker exec -it ferretdb mongosh. - For PostgreSQL backend, connect to it by running
docker exec -it ferretdb psql -U username ferretdb. FerretDB uses PostgreSQL schemas for MongoDB databases. So, if you created some collections in thetestdatabase using any MongoDB client, you can switch to it by runningSET search_path = 'test';query and see a list of PostgreSQL tables by running\dpsqlcommand. - For the SQLite backend, database files will be created on a host in the
datadirectory. You can access them by runningsqlite3 data/<filename>.sqliteafter some data is inserted into FerretDB.
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
We strongly advise users not to build FerretDB themselves.
Instead, use binaries, Docker images, or .deb/.rpm packages provided by us.
If you want to package FerretDB for your operating system or distribution,
the recommended way to build the binary is to use the build-release task;
see our instructions for contributors for more details.
FerretDB could also 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
Documentation
Community
- Website and blog: https://ferretdb.io.
- Twitter: @ferret_db.
- Mastodon: @ferretdb@techhub.social.
- Slack chat for quick questions.
- GitHub Discussions for longer topics.
- GitHub Issues for bugs and missing features.
- Open Office Hours meeting every Monday at 18:00 UTC at Google Meet.
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
|
|
|
Package ferretdb provides embeddable FerretDB implementation.
|
Package ferretdb provides embeddable FerretDB implementation. |
|
integration
module
|
|
|
internal
|
|
|
backends
Package backends provides common interfaces and code for all backend implementations.
|
Package backends provides common interfaces and code for all backend implementations. |
|
backends/sqlite
Package sqlite provides SQLite backend.
|
Package sqlite provides SQLite backend. |
|
backends/sqlite/metadata
Package metadata provides access to SQLite databases and collections information.
|
Package metadata provides access to SQLite databases and collections information. |
|
backends/sqlite/metadata/pool
Package pool provides access to SQLite databases and their connections.
|
Package pool provides access to SQLite databases and their connections. |
|
bson
Package bson provides converters from/to BSON for built-in and `types` types.
|
Package bson provides converters from/to BSON for built-in and `types` types. |
|
clientconn
Package clientconn provides client connection implementation.
|
Package clientconn provides client connection 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. |
|
clientconn/cursor
Package cursor provides access to cursor registry.
|
Package cursor provides access to cursor registry. |
|
handlers
Package handlers provides an interface for all handlers.
|
Package handlers provides an interface for all handlers. |
|
handlers/common
Package common provides common code for all handlers.
|
Package common provides common code for all handlers. |
|
handlers/common/aggregations
Package aggregations provides aggregation pipelines.
|
Package aggregations provides aggregation pipelines. |
|
handlers/common/aggregations/operators
Package operators provides aggregation operators.
|
Package operators provides aggregation operators. |
|
handlers/common/aggregations/operators/accumulators
Package accumulators provides aggregation accumulator operators.
|
Package accumulators provides aggregation accumulator operators. |
|
handlers/common/aggregations/stages
Package stages provides aggregation stages.
|
Package stages provides aggregation stages. |
|
handlers/common/aggregations/stages/projection
Package projection provides projection for aggregations.
|
Package projection provides projection for aggregations. |
|
handlers/commoncommands
Package commoncommands provides command handlers shared by all handlers.
|
Package commoncommands provides command handlers shared by all handlers. |
|
handlers/commonerrors
Package commonerrors providers errors shared by all handlers.
|
Package commonerrors providers errors shared by all handlers. |
|
handlers/commonparams
Package commonparams contains functions for parsing handlers parameters.
|
Package commonparams contains functions for parsing handlers parameters. |
|
handlers/hana
Package hana provides SAP HANA handler.
|
Package hana provides SAP HANA handler. |
|
handlers/hana/hanadb
Package hanadb provides SAP HANA connection utilities.
|
Package hanadb provides SAP HANA connection utilities. |
|
handlers/pg
Package pg provides PostgreSQL handler.
|
Package pg provides PostgreSQL handler. |
|
handlers/pg/pgdb
Package pgdb provides PostgreSQL connection utilities.
|
Package pgdb provides PostgreSQL connection utilities. |
|
handlers/proxy
Package proxy sends requests to another wire protocol compatible service.
|
Package proxy sends requests to another wire protocol compatible service. |
|
handlers/registry
Package registry provides a registry of handlers.
|
Package registry provides a registry of handlers. |
|
handlers/sjson
Package sjson provides converters from/to jsonb with some extensions for built-in and `types` types.
|
Package sjson provides converters from/to jsonb with some extensions for built-in and `types` types. |
|
handlers/sqlite
Package sqlite provides SQLite handler.
|
Package sqlite provides SQLite handler. |
|
types
Package types provides Go types matching BSON types that don't have built-in Go equivalents.
|
Package types provides Go types matching BSON types that don't have built-in Go equivalents. |
|
types/fjson
Package fjson provides converters to FJSON (JSON with some extensions) for built-in and `types` types.
|
Package fjson provides converters to FJSON (JSON with some extensions) for built-in and `types` types. |
|
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/debugbuild
Package debugbuild provides information about whatever this is a debug build or not.
|
Package debugbuild provides information about whatever this is a debug build or not. |
|
util/fsql
Package fsql provides database/sql utilities.
|
Package fsql provides database/sql utilities. |
|
util/hex
Package hex provides helpers for working with hex dumps.
|
Package hex provides helpers for working with hex dumps. |
|
util/iterator
Package iterator describes a generic Iterator interface and related utilities.
|
Package iterator describes a generic Iterator interface and related utilities. |
|
util/iterator/testiterator
Package testiterator provides a helper for checking iterator implementations.
|
Package testiterator provides a helper for checking iterator implementations. |
|
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/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/testfail
Package testfail provides testing helpers for expected tests failures.
|
Package testfail provides testing helpers for expected tests failures. |
|
util/testutil/teststress
Package teststress provides a helper for stress testing.
|
Package teststress provides a helper for stress testing. |
|
util/testutil/testtb
Package testtb provides a common testing interface.
|
Package testtb provides a common testing interface. |
|
wire
Package wire provides wire protocol implementation.
|
Package wire provides wire protocol implementation. |
|
tools
module
|