MongoDB Integration Guide

Overview

MongoDB is a popular NoSQL database that stores data in flexible JSON-like documents. It's known for scalability, flexibility, and ease of use.

Integration Type: NoSQL Document Database
Authentication: Connection URI with username/password
Connection Method: MongoDB Wire Protocol (native)
Data Model: Databases containing Collections of Documents

Getting Started

Prerequisites:

• A MongoDB account
• A MongoDB cluster created
• Database user credentials
• Access to MongoDB Atlas

Steps to Create a MongoDB Cluster:

1. Go to MongoDB Atlas: https://www.mongodb.com/cloud/atlas
2. Sign in or create an account
3. Create an organization and project
4. Click "Build a Database"
5. Choose a tier (M0 Free for development)
6. Select your region
7. Click "Create"
8. Wait for cluster deployment (1-3 minutes)
9. Create a database user in "Database Access"
10. Allow network access in "Network Access"

⚠️ Critical - IP Whitelist Configuration: In "Network Access" (Security > Network Access), you MUST add your IP address or allow access from 0.0.0.0/0 (any IP) for development/testing. Without this, Tellus cannot connect to your MongoDB cluster. For production, whitelist specific IP addresses instead of allowing all IPs.

Obtaining Credentials

Connection String (Primary Method)

Format: mongodb+srv://username:password@cluster.mongodb.net/dbname

Get it from: MongoDB Atlas Console > Your Cluster > "Connect" button > "Drivers"

Individual Components:

• Host: Your cluster hostname (e.g., myapp-cluster.mongodb.net)
• Port: 27017 (default, usually not shown in URI)
• Username: Database user created in Database Access
• Password: Database user password
• Database: Database name (optional)

Steps to Get Connection String:
1. MongoDB Atlas Console
2. Click your cluster
3. Click "Connect"
4. Choose "Drivers"
5. Select your runtime
6. Copy the connection string
7. Replace <username> and <password> with actual values

Configuration in Dashboard

1. Click "Add Project"
2. Select "MongoDB" as Database Provider
3. Fill in Credentials:
   • Option A: Paste complete connection string
   • Option B: Fill in individual components (host, port, username, password)
4. Set Database Name (optional)
5. Click "Test Connection" to verify
6. Click "Save Project"

Tellus Integration

Tellus enables you to execute powerful document queries against MongoDB Atlas using a unified object-relational API. Connect your database by providing the connection URI in your tellus.config.js:

import { Tellus } from '@tellus/client';

const tellus = new Tellus({
  databases: {
    store: {
      provider: 'mongodb',
      uri: process.env.MONGO_URI,
      database: 'ecommerce_db'
    }
  }
});

Basic Operations (CRUD)

Once connected, you can interact with your MongoDB collections using standard Tellus queries.

1. Create (Insert)

// Insert a new product document
const newProduct = await tellus.db('store').collection('products').insert({
  name: 'Mechanical Keyboard',
  price: 129.99,
  category: 'Electronics',
  tags: ['gaming', 'peripherals']
});

2. Read (Select)

// Search using complex NoSQL operators abstracted by Tellus
const electronics = await tellus.db('store').collection('products')
  .find({ 
    category: 'Electronics',
    price: { $lt: 200 }
  })
  .limit(5)
  .execute();

3. Update

// Increment price using Tellus update helpers
await tellus.db('store').collection('products')
  .where('id', '==', newProduct.id)
  .update({
    price: tellus.increment(10)
  });

4. Delete

// Remove the product document
await tellus.db('store').collection('products')
  .where('id', '==', newProduct.id)
  .delete();

Using MongoDB in the Dashboard

• Browse Databases and Collections - View all databases and collections
• View Documents - Click a collection to see documents in JSON format
• Search and Filter - Search by ObjectId or filter by field values
• Create Documents - Add new documents with custom fields
• Edit Documents - Modify existing document fields
• Delete Documents - Remove documents with confirmation
• Manage Indexes - View and create indexes for performance

Example Setup: Online Store

Create "users" collection:

{
  "_id": ObjectId(),
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "createdAt": new Date(),
  "address": {
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA"
  }
}

Create "products" collection:

{
  "_id": ObjectId(),
  "name": "Wireless Headphones",
  "description": "High-quality wireless headphones",
  "price": 199.99,
  "category": "Electronics",
  "stock": 50,
  "rating": 4.5,
  "tags": ["audio", "wireless"]
}

Create indexes for performance:

db.users.createIndex({email: 1})
db.products.createIndex({category: 1, price: 1})
db.products.createIndex({tags: 1})

MongoDB Query Examples

Filter documents in the dashboard:

// Find active users
{status: "active"}

// Find products over $100
{price: {$gt: 100}}

// Find products in specific categories
{category: {$in: ["Electronics", "Books"]}}

// Complex query
{
  "status": "completed",
  "total": {$gt: 50},
  "createdAt": {$gte: ISODate("2024-01-01")}
}

Security Best Practices

• Connection Strings: Store securely in environment variables. Don't hardcode or commit to version control.
• User Management: Create dedicated users for each application. Use principle of least privilege.
• Network Security: Whitelist only necessary IP addresses. Use VPC peering for direct connections.
• Data Protection: Enable field-level encryption. Encrypt sensitive data at application level.
• Monitoring: Set up alerts for unusual connections. Monitor query performance and storage growth.

Useful Links

• MongoDB Atlas
• MongoDB Documentation
• MongoDB University (Free Courses!)
• Community Forum