FerretDB

module
v0.9.3 Latest Latest
Warning

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

 Go to latest Published: Mar 13, 2023 License: Apache-2.0

README

FerretDB

Go Reference Go Integration Docker codecov

FerretDB (previously MangoDB) 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 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 database solution. Recognizing this, FerretDB is here to fill that gap.

Scope and current state

FerretDB will be compatible with MongoDB drivers and will strive to serve as a drop-in replacement for MongoDB 6.0+.

Currently, the project is in its early stages and welcomes all contributors. See our public roadmap, a list of known differences with MongoDB, and contributing guidelines.

Quickstart

These steps describe a quick local setup. They are not suitable for most production use-cases because they keep all data inside containers and don't encrypt incoming connections. For more configuration options check Configuration flags and variables page.

  1. Store the following in the docker-compose.yml file:

    services:
  postgres:
    image: postgres
    container_name: postgres
    ports:
      - 5432:5432
    environment:
      - POSTGRES_USER=username
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=ferretdb

  ferretdb:
    image: ghcr.io/ferretdb/ferretdb:latest
    container_name: ferretdb
    restart: on-failure
    ports:
      - 27017:27017
    environment:
      - FERRETDB_POSTGRESQL_URL=postgres://postgres:5432/ferretdb

networks:
  default:
    name: ferretdb

    postgres container runs PostgreSQL that would store data. ferretdb runs FerretDB.

  2. Fetch the latest version of FerretDB with docker compose pull. Afterwards start services with docker compose up -d.

  3. If you have mongosh installed, just run it to connect to FerretDB. It will use credentials passed in mongosh flags or MongoDB URI to authenticate to the PostgreSQL database. You'll also need to set authMechanism to PLAIN. The example URI would look like:

    mongodb://username:password@127.0.0.1/ferretdb?authMechanism=PLAIN

    See Security Authentication for more details.

    If you don't have mongosh, run the following command to run it inside the temporary MongoDB container, attaching to the same Docker network:

    docker run --rm -it --network=ferretdb --entrypoint=mongosh mongo "mongodb://username:password@ferretdb/ferretdb?authMechanism=PLAIN"

You can also install FerretDB with the .deb and .rpm packages or use binaries provided for each release.

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.

Documentation

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
fuzztool
Package ferretdb provides embeddable FerretDB implementation.
 Package ferretdb provides embeddable FerretDB implementation.
integration module
internal
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.
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/commonerrors
Package commonerrors providers errors shared by all handlers.
 Package commonerrors providers errors shared by all handlers.
handlers/dummy
Package dummy provides a basic handler implementation.
 Package dummy provides a basic handler implementation.
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/pg/pjson
Package pjson provides converters from/to jsonb with some extensions for built-in and `types` types.
 Package pjson provides converters from/to jsonb with some extensions for built-in and `types` types.
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/tigris
Package tigris provides Tigris handler.
 Package tigris provides Tigris handler.
handlers/tigris/tigrisdb
Package tigrisdb provides Tigris connection utilities.
 Package tigrisdb provides Tigris connection utilities.
handlers/tigris/tjson
Package tjson provides converters from/to Tigris JSON with schema for built-in and `types` types.
 Package tjson provides converters from/to Tigris JSON with schema for built-in and `types` types.
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/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.
 Package iterator describes a generic Iterator interface.
util/lazyerrors
Package lazyerrors provides temporary error wrapping for lazy developers.
 Package lazyerrors provides temporary error wrapping for lazy developers.
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/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.
wire
Package wire provides wire protocol implementation.
 Package wire provides wire protocol implementation.
tools module

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.