DEV Community

Cover image for NoSQL Postgres: Add MongoDB compatibility to your Supabase projects with FerretDB
Yuri for Supabase

Posted on • Originally published at

NoSQL Postgres: Add MongoDB compatibility to your Supabase projects with FerretDB

FerretDB is an open source document database that adds MongoDB compatibility to other database backends, such as Postgres and SQLite. By using FerretDB, developers can access familiar MongoDB features and tools using the same syntax and commands for many of their use cases.

In this post, we'll start from scratch, running FerretDB locally via Docker, trying out the connection with mongosh and the MongoDB Node.js client, and finally deploy FerretDB to for a production ready set up.

If you prefer video guide, you can follow along below. And make sure to subscribe to the Supabase YouTube channel!


🚀 Learn more about Supabase

Run FerretDB locally with Docker

FerretDB provides a Docker image allowing us to run it locally, for example via Orbstack, with a couple of simple commands.

FerretDB only requires the Postgres database URI to be provided as the FERRETDB_POSTGRESQL_URL environment variable. Every Supabase project comes with a full Postgres database. You can find the connection URI string in your Supabase Dashboard.

Make sure Use connection pooling is checked and Session mode is selected. Then copy the URI. Replace the password placeholder with your saved database password.

If your network supports IPv6 connections, you can also use the direct connection string. Uncheck Use connection pooling and copy the new URI.

///Set the required environment variables
export DB_USER=postgres
export DB_PASSWORD=<your db password>
export SUPA_PROJECT_REF=<your Supabase project ref>
export SUPA_REGION=<your project region>

///Run FerretDB in docker container
docker run -p 27017:27017 -p 8080:8080 -e FERRETDB_POSTGRESQL_URL=$DB_URL
Enter fullscreen mode Exit fullscreen mode

FerretDB runs on the default MongoDB port 27017 and also spins up some monitoring tools on port 8080. Once up and running you can access these at localhost:8080.

Enter fullscreen mode Exit fullscreen mode

Test with mongosh

If you have MongoDB installed locally on your machine, you can test via mongosh, the MongoDB shell.

mongosh '$MONGODB_URL'
Enter fullscreen mode Exit fullscreen mode

If you don't have MongoDB installed locally, you can run the shell via a Docker container:

docker run --rm -it --entrypoint=mongosh mongo \
Enter fullscreen mode Exit fullscreen mode

Insert documents into FerretDB

With mongosh running, let's try to insert some documents into our FerretDB instance. You are going to insert two footballer data into a players collection.

       futbin_id: 3,
       player_name: "Giggs",
       player_extended_name: "Ryan Giggs",
       quality: "Gold - Rare",
       overall: 92,
       nationality: "Wales",
       position: "LM",
       pace: 90,
       dribbling: 91,
       shooting: 80,
       passing: 90,
       defending: 44,
       physicality: 67
       futbin_id: 4,
       player_name: "Scholes",
       player_extended_name: "Paul Scholes",
       quality: "Gold - Rare",
       overall: 91,
       nationality: "England",
       position: "CM",
       pace: 72,
       dribbling: 80,
       shooting: 87,
       passing: 91,
       defending: 64,
       physicality: 82,
       base_id: 246
Enter fullscreen mode Exit fullscreen mode

Great! Now when you run db.players.find(), it should return all the documents stored in the collection.

Update document record in FerretDB

Next, you need to update "Giggs" record to reflect his current position as a CM. To do this, we can just run an updateOne command to target just that particular player:

    { player_name: "Giggs" },
    { $set: { position: "CM" } }
Enter fullscreen mode Exit fullscreen mode

Let's query the collection to see if the changes have been made:

db.players.find({player_name: "Giggs"})
Enter fullscreen mode Exit fullscreen mode

You can run many MongoDB operations on FerretDB. See the list of supported commands in the FerretDB documentation for more.

Inspect the JSONB data in the Supabase Dashboard

FerretDB stores each collection in a table on the ferretdb schema, each document represented by a JSONB entry. You can inspect this in the Table Editor in your Supabase Dashboard.

table editor

Deploy to

For production use cases, you can easily deploy FerretDB on Fly. Simply create a fly.toml file (make sure to update primary_region)

app = "supa-ferretdb-<your-supabase-project-ref>"
primary_region = "bos"

  image = ""

  internal_port = 27017
  protocol = "tcp"

    port = "27017"

  cpu_kind = "shared"
  cpus = 1
  memory_mb = 1024
Enter fullscreen mode Exit fullscreen mode

And follow these flyctl commands:

  • fly launch --no-deploy

    • An existing fly.toml file was found for app supa-ferretdb?
    • Would you like to copy its configuration to the new app? (y/N) > y

  • fly deploy

  • fly ips allocate-v4

    • Note: this is a paid feature! You can test it for free as long as you release the dedicated IPv4 before the end of the billing period!

Now simply replace in the MONGODB_URL with your dedicated IPv4 address and you're ready to roll!


FerretDB allows you to run MongoDB workloads on Postgres and SQLite. This flexibility means you can easily add MongoDB compatibility to your Supabase projects, while avoiding vendor lock-in and retaining control of your data architecture.

To get started with FerretDB, check out the FerretDB quickstart guide.

More Supabase

Top comments (0)