MongoDB ExecModule

Overview

MongoDBModule connects a ValkyrAI workflow to one TLS-enabled MongoDB deployment. Version 2.0 replaces the legacy simulated documents, random identifiers, and fixed mutation counts with real bounded provider operations, complete Workflow Studio metadata, IntegrationAccount-only credentials, normalized outputs, and credential-safe failures.

The module is registered as:

com.valkyrlabs.workflow.modules.database.MongoDBModule

It supports find, findOne, count, insertOne, updateOne, and deleteOne. It intentionally does not expose multi-document writes, bulk operations, arbitrary aggregation pipelines, server-side JavaScript, index management, transactions, or change streams.

Usage

1. Create a least-privilege MongoDB IntegrationAccount with a credential-free TLS endpoint in accountId.
2. Put the MongoDB username in username, the password in a SecureField, and mark the account READY.
3. Bind that account through the module's mongoAccount configuration.
4. Choose a supported operation, database, and collection.
5. Provide only the bounded filter, projection, sort, document, or update fields required by that operation.
6. Set confirmWrite: true for insertOne, updateOne, or deleteOne.

Every execution opens one bounded client, performs at most one provider operation, closes the client, and returns attempts: 1 if MongoDB was contacted.

Inputs

Input	Required	Description
operation	Yes	find, findOne, count, insertOne, updateOne, or deleteOne.
database	Yes	Database name matching the safe 1–64 character resource-name contract.
collection	Yes	Collection name of at most 120 characters; system.* and dollar-prefixed names are rejected.
filter	No	MongoDB filter object, capped at 64 KiB. Default: {}.
projection	No	Field projection using only 0 and 1 values, capped at 64 KiB.
sort	No	Sort object using only 1 and -1, capped at 64 KiB.
document	For insertOne	JSON document capped at 256 KiB.
update	For updateOne	Object-valued $set and/or $unset update, capped at 256 KiB.
limit	For find	Page size from 1 through 200. Default: 50.
skip	No	Offset from 0 through 10,000. Default: 0.
upsert	No	Allows updateOne to insert when unmatched. Default: false.
confirmWrite	For writes	Must be exactly true before any single-document write is attempted.

Raw endpoint, username, password, API-key, token, auth, mock, and test fields are rejected in workflow input and module configuration. $where, $function, $accumulator, $out, and $merge are rejected recursively.

Outputs

Output	Description
status	success or error.
operation	Normalized operation name.
database	Validated database name after request validation.
collection	Validated collection name after request validation.
items	Documents returned by find.
document	Document returned by findOne, when present.
count	Page size for find, match indicator for findOne, or bounded document count.
hasMore	Whether find detected one more result beyond the requested page.
insertedId	Provider-assigned or caller-supplied identifier from insertOne.
matchedCount	Documents matched by updateOne; never more than one.
modifiedCount	Documents modified by updateOne; never more than one.
upsertedId	Identifier created by an updateOne upsert.
deletedCount	Documents deleted by deleteOne; never more than one.
attempts	Provider attempts. Validation failures report 0; provider attempts report 1.
error	Safe object containing code, message, and retryable.

Credentials, the endpoint, raw provider exceptions, filter contents, and write payloads are never returned.

IntegrationAccount Requirements

The bound IntegrationAccount must:

• have status exactly READY;
• put a credential-free mongodb+srv://... endpoint, or a mongodb://... endpoint with TLS explicitly enabled, in accountId;
• put the database principal in username;
• put the password in the password SecureField, with apiKey accepted only as a SecureField compatibility source;
• grant only the documented databases, collections, and CRUD operations required by the workflow;
• avoid embedding credentials in the endpoint authority or workflow data.

mongodb:// endpoints without tls=true or ssl=true are rejected. mongodb+srv:// uses TLS by default and is rejected if TLS is explicitly disabled.

Configuration

Configuration	Default	Constraint
mongoAccount	None	Required READY MongoDB IntegrationAccount.
operation	None	Required allowlisted operation.
database	None	Required safe database name.
collection	None	Required safe non-system collection name.
filter	{}	JSON object, at most 64 KiB.
projection	{}	JSON object with 0/1 values, at most 64 KiB.
sort	{}	JSON object with -1/1 values, at most 64 KiB.
document	None	Required by insertOne, at most 256 KiB.
update	None	Required by updateOne; $set and $unset only.
limit	50	1–200.
skip	0	0–10,000.
upsert	false	Valid only for updateOne.
confirmWrite	false	Must be true for writes.
authDatabase	admin	Safe authentication database name.
timeoutMs	5000	250–15,000 milliseconds.

Operations

find

Returns one bounded page. The driver requests limit + 1 documents so hasMore can be reported without an unbounded count query. Use a stable sort and increase skip deliberately for later pages.

findOne

Returns at most one matching document. count is 0 or 1; an absent match is a successful read, not an error.

count

Counts matching documents with an operation timeout and a hard provider limit of 100,000. It does not scan without that cap.

insertOne

Inserts one bounded document after confirmWrite: true. A caller-supplied _id is recommended for deterministic reconciliation. The driver does not retry the write automatically.

updateOne

Updates at most one matching document with $set and/or $unset. upsert is optional and makes the operation capable of inserting a document. Every update requires explicit confirmation.

deleteOne

Deletes at most one matching document after explicit confirmation. Empty filters are permitted because single-document deletion remains bounded, but production workflows should use a stable unique identifier.

Errors and Failure Modes

Code	Meaning	Recovery
VALIDATION_ERROR	Missing/malformed resource, JSON, endpoint, bound, projection, sort, update, raw credential, or forbidden operator.	Correct the named field. MongoDB was not contacted.
CONFIRMATION_REQUIRED	A write was requested without confirmWrite: true.	Review the target and set explicit confirmation.
UNSUPPORTED_OPERATION	A legacy aggregate, bulk, multi-write, transaction, index, or change-stream operation was requested.	Migrate to one documented operation or a separately reviewed module.
INTEGRATION_ACCOUNT_ERROR	No account is bound, status is not READY, or username/SecureField credentials are absent.	Repair and rebind the MongoDB IntegrationAccount.
MONGODB_COMMAND_ERROR	TLS, selection, authentication, timeout, command, or response handling failed.	Verify MongoDB health and least-privilege grants. Reconcile write state before retrying.

Provider exception text is deliberately suppressed because database failures can echo hosts, usernames, filters, document fields, or credentials. Every returned failure is marked non-retryable; the workflow owner decides whether a reconciled retry is safe.

Example

Update one customer by stable external ID:

{
  "operation": "updateOne",
  "database": "crm",
  "collection": "customers",
  "filter": {
    "externalId": "cust-42"
  },
  "update": {
    "$set": {
      "tier": "pro"
    }
  },
  "upsert": false,
  "confirmWrite": true
}

Expected normalized result:

{
  "status": "success",
  "operation": "updateOne",
  "database": "crm",
  "collection": "customers",
  "matchedCount": 1,
  "modifiedCount": 1,
  "attempts": 1
}

Notes

• Pagination is bounded and offset-based. MongoDB does not provide a stable cursor for arbitrary filters, so use a deterministic sort and immutable key where page consistency matters.
• Reads and writes are single-attempt. Driver-level read and write retries are disabled to keep execution evidence unambiguous.
• The module is classified non-idempotent because it can insert, update, upsert, and delete documents. A repeated read is normally safe, but the module-wide contract must cover every operation.
• confirmWrite is an execution guard, not a dry run or a second-phase transaction. No operation supports dry-run.
• Multi-document writes, arbitrary pipelines, server-side JavaScript, transactions, change streams, bulk writes, and index changes remain intentionally unsupported.
• The repository suite does not use a live MongoDB credential. It verifies request normalization, IntegrationAccount enforcement, TLS endpoint validation, operation bounds, secret redaction, failure mapping, annotation scanning, and catalog serialization. Live connectivity and provider authorization remain a deployment-time boundary.