This repo provides a service that connects Hasura v3 to MongoDB databases. Supports MongoDB 6 or later.
The MongoDB connector is available from the Hasura connectors directory. There are also Docker images available at:
https://github.com/hasura/ndc-mongodb/pkgs/container/ndc-mongodb
The published Docker images are multi-arch, supporting amd64 and arm64 Linux.
The easiest way to set up build and development dependencies for this project is to use Nix. If you don't already have Nix we recommend the Determinate Systems Nix Installer which automatically applies settings required by this project.
If you prefer to manage dependencies yourself you will need,
- Rust via Rustup
- MongoDB
>= 6
- OpenSSL development files
To run everything you need run this command to start services in Docker containers:
$ just up
Next access the GraphQL interface at http://localhost:7100/
If you are using the development shell (see below) the just
command will be
provided automatically.
Run the above command again to restart after making code changes.
To build the MongoDB connector run,
$ nix build --print-build-logs && cp result/bin/mongodb-connector <dest>
To cross-compile statically-linked binaries for x86_64 or ARM for Linux run,
$ nix build .#mongo-connector-x86_64-linux --print-build-logs && cp result/bin/mongodb-connector <dest>
$ nix build .#mongo-connector-aarch64-linux --print-build-logs && cp result/bin/mongodb-connector <dest>
The Nix configuration outputs Docker images in .tar.gz
files. You can use
docker load -i
to install these to the local machine's docker daemon. But it
may be more helpful to use skopeo
for this purpose so that you can apply
a chosen tag, or override the image name.
To build and install a Docker image locally (you can change
mongodb-connector:1.2.3
to whatever image name and tag you prefer),
$ nix build .#docker --print-build-logs \
&& skopeo --insecure-policy copy docker-archive:result docker-daemon:mongo-connector:1.2.3
To build a Docker image with a cross-compiled ARM binary,
$ nix build .#docker-aarch64-linux --print-build-logs \
&& skopeo --insecure-policy copy docker-archive:result docker-daemon:mongo-connector:1.2.3
If you don't want to install skopeo
you can run it through Nix, nix run nixpkgs#skopeo -- --insecure-policy copy docker-archive:result docker-daemon:mongo-connector:1.2.3
This project uses a development shell configured in flake.nix
that automatically
loads specific version of Rust along with all other project dependencies. The
simplest way to start a development shell is with this command:
$ nix develop
If you are going to be doing a lot of work on this project it can be more convenient to set up direnv which automatically links project dependencies in your shell when you cd to the project directory, and automatically reverses all shell modifications when you navigate to another directory. You can also set up direnv integration in your editor to get your editor LSP to use the same version of Rust that the project uses.
There is a justfile
for getting started quickly. You can use its recipes to
run relevant services locally including the MongoDB connector itself, a MongoDB
database server, and the Hasura GraphQL Engine. Use these commands:
just up # start services; run this again to restart after making code changes
just down # stop services
just down-volumes # stop services, and remove MongoDB database volume
just logs # see service logs
just test # run unit and integration tests
just # list available recipes
Integration tests run in an independent set of ephemeral docker containers.
The just
command is provided automatically if you are using the development
shell. Or you can install it yourself.
The justfile
delegates to arion which is a frontend for docker-compose that
adds a layer of convenience where it can easily load agent code changes. If you
are using the devShell you can run arion
commands directly. They mostly work
just like docker-compose
commands:
To start all services run:
$ arion up -d
To recompile and restart the connector after code changes run:
$ arion up -d connector
The arion configuration runs these services:
- connector: the MongoDB data connector agent defined in this repo (port 7130)
- mongodb
- Hasura GraphQL Engine
- a stubbed authentication server
- jaeger to collect logs (see UI at http://localhost:16686/)
Connect to the HGE GraphiQL UI at http://localhost:7100/
Instead of a docker-compose.yaml
configuration is found in arion-compose.nix
.
The arion configuration in the previous section preloads MongoDB with test data.
There is corresponding OpenDDN configuration in the fixtures/hasura/
directory.
Preloaded databases are populated by scripts in fixtures/mongodb/
. Any .js
or .sh
scripts added to this directory will be run when the mongodb service is
run from a fresh state. Note that you will have to remove any existing docker
volume to get to a fresh state. Using arion you can remove volumes by running
arion down --volumes
.
Override the MongoDB version that arion runs by assigning a Docker image name to
the environment variable MONGODB_IMAGE
. For example,
$ arion down --volumes # delete potentially-incompatible MongoDB data
$ MONGODB_IMAGE=mongo:6 arion up -d
Or run integration tests against a specific MongoDB version,
$ MONGODB_IMAGE=mongo:6 just test-integration
The Hasura MongoDB Connector is available under the Apache License 2.0 (Apache-2.0).