Skip to content

FerretDB/FerretDB

main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
January 31, 2023 14:59
January 31, 2023 14:59
January 12, 2023 14:32
December 29, 2022 16:20
October 31, 2021 23:18

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:

    version: "3"
    
    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@localhost/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 with FerretDB with the .deb and .rpm packages provided for each release.

Building and packaging

We strongly advise users not to build FerretDB themselves. Instead, use Docker images or .deb and .rpm packages provided by us. If you want to package FerretDB for your operating system or distribution, the recommended way 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.