MongoDB

MongoDB is a document-oriented NoSQL database. Hyperterse provides support for MongoDB using the official MongoDB Go Driver. Statements are passed directly as MongoDB database commands, giving you access to any operation MongoDB supports.

Connecting to your server

MongoDB adapters use the standard MongoDB connection URI:

adapters:
  my_mongodb:
    connector: mongodb
    connection_string: 'mongodb://localhost:27017'

For MongoDB Atlas or SRV records:

connection_string: 'mongodb+srv://user:pass@cluster.mongodb.net/mydb'

Adapter options

Configure connection pool and timeouts via adapter options:

adapters:
  production_db:
    connector: mongodb
    connection_string: 'mongodb://user:pass@host:27017/mydb'
    options:
      maxPoolSize: 50
      minPoolSize: 5
      connectTimeoutMS: 10000
      serverSelectionTimeoutMS: 5000

For a complete list of connection options, see the MongoDB Go Driver connection string options.

Setting up a database

It is very easy to set up a database for Hyperterse. You can use your existing MongoDB deployment or start one and wire it up to Hyperterse.

1. Start MongoDB

   Start MongoDB using your preferred method:

   # Docker
   docker run -d -p 27017:27017 mongo:latest
   
   # macOS with Homebrew
   brew services start mongodb-community
   
   # Or use MongoDB Atlas (cloud)
   # Create a free cluster and copy the connection string

2. Configure Hyperterse

   Add the MongoDB adapter to your configuration:

   adapters:
     main_db:
       connector: mongodb
       connection_string: 'mongodb://localhost:27017'
       options:
         maxPoolSize: 10

   For authenticated MongoDB:

   connection_string: 'mongodb://user:password@localhost:27017/mydb'

   For MongoDB Atlas with TLS:

   connection_string: 'mongodb+srv://user:pass@cluster.mongodb.net/mydb'

3. Verify connection

   Test the connection using the development server:

   hyperterse dev -f config.terse

   Look for a successful connection message:

   INFO  Connected to adapter: main_db

Usage

MongoDB queries in Hyperterse use JSON statements with two fields: database and command. The command field takes a raw MongoDB database command — the same syntax used by db.runCommand() in the MongoDB shell.

statement: |
  {"database": "mydb", "command": {"find": "users", "filter": {"name": "{{ inputs.name }}"}, "limit": 10}}

The command name (e.g. "find", "insert") must be the first key inside the command object. This is a MongoDB requirement.

Use parameterized inputs with {{ inputs.name }} for dynamic values. For ObjectId fields, pass them as {"$oid": "hexstring"} in filters and updates.

Statement format

Field	Description
database	The MongoDB database name to run the command against.
command	A raw MongoDB command object. See MongoDB command reference for all available commands.

Performance

Hyperterse does not limit MongoDB performance. Use indexes, projection, and appropriate limits in your statements. Configure maxPoolSize and minPoolSize in adapter options to tune connection pooling.

Troubleshooting

Connection refused

Verify MongoDB is running and reachable:

mongosh "mongodb://localhost:27017"

Check firewall and network when connecting to a remote server or Atlas.

Authentication failed

Ensure the connection string includes the correct username and password (URL-encoded if they contain special characters):

connection_string: 'mongodb://user:password@host:27017/mydb'

For Atlas, use the connection string from the Atlas UI (it includes auth and options).

TLS / Atlas

For MongoDB Atlas, use the mongodb+srv:// URI provided by Atlas. The driver handles TLS and discovery. If you use a custom certificate, refer to the MongoDB Go Driver TLS documentation.

Invalid statement JSON

The query statement must be valid JSON with database and command fields. Ensure quotes are correct and that {{ inputs.x }} placeholders are inside quoted strings. After substitution, the connector parses the result as JSON; malformed JSON will return an error.

The command name (e.g. "find", "insert") must be the first key inside the command object. MongoDB rejects commands where the command name is not the first field.