Get Started with Hasura DDN and MongoDB

Overview

This tutorial takes about fifteen minutes to complete. You'll learn how to:

• Set up a new Hasura DDN project
• Connect it to a MongoDB database
• Generate Hasura metadata
• Create a build
• Run your first query

Additionally, we'll familiarize you with the steps and workflows necessary to iterate on your API.

This tutorial assumes you're starting from scratch. We'll use a locally running MongoDB instance via Docker and connect it to Hasura, but you can easily follow the steps if you already have data seeded; Hasura will never modify your source schema.

Prerequisites

Install the DDN CLI

macOS and Linux

Simply run the installer script in your terminal:

curl -L https://graphql-engine-cdn.hasura.io/ddn/cli/v4/get.sh | bash

Windows

• Download the latest DDN CLI installer for Windows.
• Run the DDN_CLI_Setup.exe installer file and follow the instructions. This will only take a minute.
• By default, the DDN CLI is installed under C:\Users\{Username}\AppData\Local\Programs\DDN_CLI
• The DDN CLI is added to your %PATH% environment variable so that you can use the ddn command from your terminal.

Install Docker

The Docker based workflow helps you iterate and develop locally without deploying any changes to Hasura DDN, making the development experience faster and your feedback loops shorter. You'll need Docker Compose v2.27.1 or later.

Validate the installation

You can verify that the DDN CLI is installed correctly by running:

ddn doctor

Tutorial

Step 1. Install mongosh

This tutorial uses mongosh — the Mongo shell — to interact with the local MongoDB instance. You can download it here.

Step 2. Authenticate your CLI

Before you can create a new Hasura DDN project, you need to authenticate your CLI:

ddn auth login

This will launch a browser window prompting you to log in or sign up for Hasura DDN. After you log in, the CLI will acknowledge your login, giving you access to Hasura Cloud resources.

Step 3. Scaffold out a new local project

Next, create a new local project:

ddn supergraph init my-project && cd my-project

Once you move into this directory, you'll see your project scaffolded out for you. You can view the structure by either running ls in your terminal, or by opening the directory in your preferred editor.

Step 4. Initialize your MongoDB connector

In your project directory, run:

ddn connector init my_mongo -i

From the dropdown, start typing mongo and hit enter to accept the default port. Then, provide the following connection string:

mongodb://local.hasura.dev:27017/my_database

Step 5. Start the local MongoDB container

Begin by creating a compose file for the Mongo service:

touch app/connector/my_mongo/compose.mongo.yaml

Then, open the file and add the following:

services:
  mongodb:
    image: mongo:latest
    container_name: mongodb
    ports:
      - "27017:27017"

Run the container:

docker compose -f app/connector/my_mongo/compose.mongo.yaml up -d

Use the mongosh shell to seed the database:

docker exec -it mongodb mongosh my_database --eval "
db.users.insertMany([
  { user_id: 1, name: 'Alice', age: 25 },
  { user_id: 2, name: 'Bob', age: 30 },
  { user_id: 3, name: 'Charlie', age: 35 }
]);
"

The shell will return information about the newly-inserted users records.

Step 6. Introspect your MongoDB database

Next, use the CLI to introspect your MongoDB database:

ddn connector introspect my_mongo

After running this, you should see a representation of your collection's schema in app/connector/my_mongo/schema/users.json; you can view this using cat or open the file in your editor.

For each collection in your database, the MongoDB connector will generate a separate JSON file representing it.

Additionally, you can check which resources are available — and their status — at any point using the CLI:

ddn connector show-resources my_mongo

Step 7. Add your model

Now, track the collection from your MongoDB database as a model in your DDN metadata:

ddn models add my_mongo users

Open the app/metadata directory and you'll find a newly-generated file: Users.hml. The DDN CLI will use this Hasura Metadata Language file to represent the users collections from MongoDB in your API as a model.

Step 8. Create a new build

To create a local build, run:

ddn supergraph build local

The build is stored as a set of JSON files in engine/build.

Step 9. Start your local services

Start your local Hasura DDN Engine and MongoDB connector:

ddn run docker-start

Your terminal will be taken over by logs for the different services.

Step 10. Run your first query

In a new terminal tab, open your local console:

ddn console --local

In the GraphiQL explorer of the console, write this query:

query {
  users {
    userId
    name
    age
  }
}

You'll get the following response:

{
  "data": {
    "users": [
      {
        "userId": 1,
        "name": "Alice",
        "age": 25
      },
      {
        "userId": 2,
        "name": "Bob",
        "age": 30
      },
      {
        "userId": 3,
        "name": "Charlie",
        "age": 35
      }
    ]
  }
}

Step 11. Iterate on your MongoDB schema

Let's add a new collection for posts:

docker exec -it mongodb mongosh my_database --eval "
db.posts.insertMany([
  { user_id: 1, post_id: 1, title: 'My First Post', content: 'This is Alice\'s first post.' },
  { user_id: 1, post_id: 2, title: 'Another Post', content: 'Alice writes again!' },
  { user_id: 2, post_id: 3, title: 'Bob\'s Post', content: 'Bob shares his thoughts.' },
  { user_id: 3, post_id: 4, title: 'Hello World', content: 'Charlie joins the conversation.' }
]);
"

Step 12. Refresh your metadata and rebuild your project

tip

The following steps are necessary each time you make changes to your source schema. This includes, adding, modifying, or dropping collections.

Step 12.1. Re-introspect your data source

Run the introspection command again:

ddn connector introspect my_mongo

In app/connector/my_mongo/configuration.json, you'll see schema updated to include operations for the posts collection. You'll also see a posts.json file in the schema directory.

Step 12.2. Update your metadata

Add the posts model:

ddn model add my_mongo posts

Step 12.3. Kill your services

Bring down the services by pressing CTRL+C in the terminal tab logging their activity.

Step 12.4. Create a new build

Next, create a new build:

ddn supergraph build local

Step 12.5. Delete your connector's image

Open Docker Desktop and delete the container and image for your MongoDB connector. It should be named something similar to app-my_mongo-1.

Step 12.6 Restart your services

Bring everything back up:

ddn run docker-start

This will create a fresh image of your connector along with restarting your other services.

Step 13. Query your new build

Head back to your console and query the posts model:

query GetPosts {
  posts {
    userId
    postId
    title
    content
  }
}

You'll get a response like this:

{
  "data": {
    "posts": [
      {
        "userId": 1,
        "postId": 1,
        "title": "My First Post",
        "content": "This is Alice's first post."
      },
      {
        "userId": 1,
        "postId": 2,
        "title": "Another Post",
        "content": "Alice writes again!"
      },
      {
        "userId": 2,
        "postId": 3,
        "title": "Bob's Post",
        "content": "Bob shares his thoughts."
      },
      {
        "userId": 3,
        "postId": 4,
        "title": "Hello World",
        "content": "Charlie joins the conversation."
      }
    ]
  }
}

Step 14. Create a relationship

Open the Posts.hml file and add the following to the end:

---
kind: Relationship
version: v1
definition:
  name: user
  sourceType: Posts
  target:
    model:
      name: Users
      relationshipType: Object
  mapping:
    - source:
        fieldPath:
          - fieldName: userId
      target:
        modelField:
          - fieldName: userId

LSP-Assisted authoring is available

We've created an extension for VS Code that leverages LSP to make authoring these metadata objects easier. Check it out here.

Step 15. Rebuild your project

Bring down the services by pressing CTRL+C in the terminal tab logging their activity.

As your metadata has changed, create a new build:

ddn supergraph build local

As before, open Docker Desktop and delete the container and image for your MongoDB connector. It should be named something similar to app-my_mongo-1.

Bring everything back up:

ddn run docker-start

Step 16. Query using your relationship

Now, execute a nested query using your relationship:

query GetPosts {
  posts {
    postId
    title
    content
    user {
      userId
      name
      age
    }
  }
}

Which should return a result like this:

{
  "data": {
    "posts": [
      {
        "postId": 1,
        "title": "My First Post",
        "content": "This is Alice's first post.",
        "user": {
          "userId": 1,
          "name": "Alice",
          "age": 25
        }
      },
      {
        "postId": 2,
        "title": "Another Post",
        "content": "Alice writes again!",
        "user": {
          "userId": 1,
          "name": "Alice",
          "age": 25
        }
      },
      {
        "postId": 3,
        "title": "Bob's Post",
        "content": "Bob shares his thoughts.",
        "user": {
          "userId": 2,
          "name": "Bob",
          "age": 30
        }
      },
      {
        "postId": 4,
        "title": "Hello World",
        "content": "Charlie joins the conversation.",
        "user": {
          "userId": 3,
          "name": "Charlie",
          "age": 35
        }
      }
    ]
  }
}

Next steps

Congratulations on completing your first Hasura DDN project with MongoDB! 🎉

Here's what you just accomplished:

• You started with a fresh project and connected it to a local MongoDB database.
• You set up metadata to represent your collections and relationships, which acts as the blueprint for your API.
• Then, you created a build — essentially compiling everything into a ready-to-use API — and successfully ran your first GraphQL queries to fetch data.
• Along the way, you learned how to iterate on your schema and refresh your metadata to reflect changes.

Now, you're equipped to connect and expose your data, empowering you to iterate and scale with confidence. Great work!

Take a look at our MongoDB docs to learn more about how to use Hasura DDN with MongoDB. Or, if you're ready, get started with adding permissions to control access to your API.