Skip to main content

MongoDB Integration

This guide aims to show you how to create a connection from your Windmill instance to an external MongoDB Atlas database, then use it to make queries.

info

MongoDB Atlas is the cloud-hosted and managed version of MongoDB. This guide won't cover the self-hosted version of MongoDB and also assumes, that you already have an Atlas database set up.

You can find more information about setting up MongoDB Atlas here.

Integration between MongoDB and Windmill

Create Resource

Windmill provides integration with many different apps and services with the use of Resources. Each Resource has a Resources Type, which controls the shape of it. To be able to connect to a MongoDB instance, we'll need to define a Resource with the mongodb_rest Resource Type first.

tip

You can find a list of all the officially supported Resource Types on Windmill Hub.

Head to the Resources page in the Windmill app, click on "Add a resource/API" in the top right corner and select the mongodb_rest type.

Select Resource Type

caution

There is a mongodb and a mongodb_rest Resource Type.

  • mongodb_rest uses an API Key and Endpoint
  • mongodb uses a custom configuration (asking for db, tls, servers, and credentials)

For the present section, we'll select mongodb_rest as this will make it easier to connect to MongoDB Atlas.

To enable access to your database, follow the instructions in this article and paste your API key and endpoint in Windmill. When it's done, click "Save".

Paste in Resource Values

Using Custom Configuration

Integration MongoDB through the mongodb resource type can be made by providing the following parameters.

Parameters below:
PropertyTypeDescriptionDefaultRequiredWhere to FindAdditional Details
dbstringDatabase nametrueMongoDB Atlas DashboardName of the database you want to connect to
tlsbooleanUse TLS for connectionstruefalseYour own preferenceSet to true for secure connections
serversarrayArray of server objectstrueMongoDB Atlas DashboardEach server object should contain host and port
host (nested)stringServer addresstrueMongoDB Atlas DashboardHostname of the MongoDB instance
port (nested)integerPort number27017falseMongoDB Atlas DashboardDefault MongoDB port is 27017
credentialobjectAuthentication informationtrueMongoDB Atlas DashboardContains username, password, db, mechanism
username (nested)stringDatabase usernametrueMongoDB Atlas DashboardYour database user's username
password (nested)stringDatabase passwordtrueMongoDB Atlas DashboardYour database user's password
db (nested)stringAuthentication databasetrueMongoDB Atlas DashboardThe database used for authentication
mechanism (nested)stringAuthentication mechanismSCRAM-SHA-1falseYour own preferenceDefault authentication mechanism is "SCRAM-SHA-1"

Create Script

Next, let's create a Script that will use the newly created Resource. Head on to the Home page and click on the "+Script" button. We'll be using TypeScript as the language.

info

Windmill uses Deno as the TypeScript runtime.

Name the Script my_mongodb_script, give it a summary, "Query the Example MongoDB Dataset" for example and click "Next".

Script creation first step

Paste in the following code into the editor:

import { MongoClient } from 'https://deno.land/x/[email protected]/mod.ts';

type MongodbRest = {
endpoint: string;
api_key: string;
};

export async function main(
auth: MongodbRest,
data_source: string,
database: string,
collection: string,
filter: Record<string, any>
) {
const client = new MongoClient({
endpoint: auth.endpoint,
dataSource: data_source,
auth: { apiKey: auth.api_key }
});
const documents = client.database(database).collection(collection);
return await documents.find(filter);
}

In case you are using the sample dataset of MongoDB Atlas, you'll have a sample_restaurants database filled with restarurants. To make a query for a specific restaurant name, the arguments of the Script would look like the followings (casing matters):

  • auth - select the Resource we created in the previous step (my_mongodb_rest)
  • data_source - Cluster0
  • database - sample_restaurants
  • collection - restaurants
  • filter - { "name": "Nordic Delicacies" }

After filling the inputs, try running the Script by clicking "Test" or pressing Ctrl + Enter. You should see exactly one restaurant returned in the bottom right corner.

Run the Script

If you tried querying by the _id field, you might have noticed that it didn't return anything. That's because it is stored as an ObjectID, which is a special type in MongoDB. To query by ID, you'll need to convert the filter value to an ObjectID first. Replace your code with the following to make it able to query by ID:

import { MongoClient, ObjectId } from 'https://deno.land/x/[email protected]/mod.ts';

type MongodbRest = {
endpoint: string;
api_key: string;
};

export async function main(
auth: MongodbRest,
data_source: string,
database: string,
collection: string,
filter: Record<string, any>
) {
const client = new MongoClient({
endpoint: auth.endpoint,
dataSource: data_source,
auth: { apiKey: auth.api_key }
});
const documents = client.database(database).collection(collection);
if ('_id' in filter) {
filter['_id'] = new ObjectId(filter['_id']);
}
return await documents.find(filter);
}

Now try running the Script again with the same arguments, except for the filter, which should be { "_id": "5eb3d668b31de5d588f4293b" }. You should see the same restaurant named "Nordic Delicacies" returned.

tip

You can find more Script examples related to MongoDB on Windmill Hub.

Once you're done, click on "Save", which will save it to your workspace. You can now use this Script in your Flows, Apps or as standalone.