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 Fly.io 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!
Prerequisites
- A Supabase project. Create yours here: database.new.
- Docker or Orbstack.
- [Optional] A Fly.io account for production deployment.
Run FerretDB locally with Docker
FerretDB provides a Docker image allowing us to run it locally, for example via Orbstack, with a couple 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.
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.
Once up and running, constructing the MongoDB URI is easil:
Test with mongosh
If you have MongoDB installed locally on your machine, you can test via mongosh, the MongoDB shell.
If you don't have MongoDB installed locally, you can run the shell via a Docker container:
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.
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:
Let's query the collection to see if the changes have been made:
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.
Deploy to Fly.io
For production use cases, you can easily deploy FerretDB on Fly. Simply create a fly.toml file (make sure to update primary_region)
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 secrets set FERRETDB_POSTGRESQL_URL=$DB_URL
- 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 127.0.0.1 in the MONGODB_URL with your dedicated IPv4 address and you're ready to roll!
Conclusion
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.