Skip to main content
Hyperterse supports MongoDB as a document database connector. Statements are passed as native MongoDB database commands — the same syntax used by db.runCommand() in the MongoDB shell. This gives you access to any operation MongoDB supports: find, aggregate, insert, update, delete, and administrative commands.
Hyperterse connects to your existing database. It does not create or manage databases — you provide a running MongoDB instance (self-hosted or MongoDB Atlas) and a connection string.

​
Adapter configuration

Create an adapter file in app/adapters/:
app/adapters/mongo-db.terse
connector: mongodb
connection_string: '{{ env.MONGODB_URL }}'
options:
  maxPoolSize: '50'
  minPoolSize: '5'
The connection string uses the standard MongoDB URI format:
mongodb://user:password@host:27017/database

​
Connection options

​
maxPoolSize
string
Maximum number of connections in the pool.
​
minPoolSize
string
Minimum number of idle connections maintained in the pool.
​
connectTimeoutMS
string
Timeout in milliseconds for establishing a new connection.
​
serverSelectionTimeoutMS
string
Timeout in milliseconds for selecting a server from a replica set or sharded cluster.

​
Verify the connection

Start the server and confirm the adapter connects: 
hyperterse start
A successful connection produces: 
INFO  Connected to adapter: mongo-db
If the connection fails, the server exits immediately with a diagnostic message.

​
Usage

MongoDB tool statements are JSON objects with two required fields: database and command. The command field takes a raw MongoDB database command.
app/tools/find-users/config.terse
description: 'Find users by name'
use: mongo-db
statement: |
  {
    "database": "mydb",
    "command": {
      "find": "users",
      "filter": { "name": "{{ inputs.name }}" },
      "limit": 10
    }
  }
inputs:
  name:
    type: string
    description: 'User name to search for'
auth:
  plugin: allow_all
The command name (e.g., "find", "insert", "aggregate") must be the first key inside the command object. MongoDB rejects commands where the operation name is not the first field.

​
Statement format

FieldDescription
databaseThe MongoDB database to run the command against.
commandA raw MongoDB database command object.

​
Aggregation example

app/tools/sales-summary/config.terse
description: 'Aggregate sales by product category'
use: mongo-db
statement: |
  {
    "database": "analytics",
    "command": {
      "aggregate": "sales",
      "pipeline": [
        { "$match": { "year": {{ inputs.year }} } },
        { "$group": { "_id": "$category", "total": { "$sum": "$amount" } } },
        { "$sort": { "total": -1 } }
      ],
      "cursor": {}
    }
  }
inputs:
  year:
    type: int
    description: 'Calendar year to aggregate'
auth:
  plugin: allow_all

​
ObjectId handling

For queries involving ObjectId fields, pass them using the extended JSON format: 
{ "filter": { "_id": { "$oid": "{{ inputs.id }}" } } }

​
Troubleshooting

​
Connection refused

Verify MongoDB is running and reachable: 
mongosh "mongodb://localhost:27017"
Check firewall rules for remote instances and ensure the Atlas IP allowlist includes your server’s address.

​
Authentication failed

Ensure the connection string contains the correct username and password. URL-encode special characters in passwords (e.g., @ becomes %40).

​
TLS / Atlas

For MongoDB Atlas, always use the mongodb+srv:// URI provided by Atlas. The driver handles TLS and server discovery automatically. For custom certificates, configure TLS options in the connection string.

​
Invalid statement JSON

The statement field must be valid JSON after {{ inputs.* }} substitution. Ensure all placeholders resolve to properly quoted JSON values. The command object must have the operation name as its first key.