---
schema_version: "1"
id: 0af13890819436cc468e08c298f7f14788d9de27eb7e86c7e5009f073deb7bb7
title: Upgrading and Migrating MongoDB Connector to version 6.x
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/mongodb-connector/6.3/mongodb-connector-upgrade-migrate.md
canonical_url: https://docs.mulesoft.com/mongodb-connector/6.3/mongodb-connector-upgrade-migrate
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 21447f32953a388c9b647366f1e3bbd0b01cd65f411fec619215023010549a1b
description: MuleSoft Documentation Site
release: "6.3"
latest: false
---
---
product: MongoDB Connector
version: 6.3
---

# Upgrading and Migrating MongoDB Connector to version 6.x

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

## Supported Upgrade Paths

<table><colgroup><col> <col></colgroup><thead><tr><th>From Version</th><th>To Version</th></tr></thead><tbody><tr><td><div><div><p>5.3.x</p></div></div></td><td><div><div><p>6.x.x</p></div></div></td></tr></tbody></table>

## Changes in This Release

MongoDB 6.x.x contains the following changes:

- Changed connection types and configuration

- Changed operation names, metadata, fields, and values

- Changed input sources

- Added the ability to specify which MongoDB Java driver to use

- At runtime, you can overwrite the **Write concern acknowledgement** and **Write concern timeout**
  fields in the global element of the following operations:

  - Find documents

  - Insert document

  - Insert documents

  - Update Documents

  - Count documents operations

### Changes in Connection Types and Configuration

MongoDB 6.x contains the following changes to connection types and configuration:

- Removed the Connection String connection type (reintroduced in 6.3.0 version to support MongoDB
  Atlas)

- Removed the Metadata configuration section

  MongoDB automatically generates the metadata.

#### Config Advanced Tab

The following optional changes apply to the **Advanced** tab in the global configuration:

- Added the following read concern options:

  - Read concern: Enables the control of the consistency and isolation properties of the data read
    from replica sets and replica set shards.

  - Read preference: Specifies the read preferences for this connection.

  - Maximum staleness seconds: Specifies how stale a secondary MongoDB cluster can be before the
    client stops using it for read operations.

    A value of -1 means that there is no maximum staleness threshold.

  - Read preference tags: Enables you to specify a tag set in the read preference to target those
    members associated with a tag in the set.

- Added the following write concern options:

  - Write concern acknowledgment: Requests an acknowledgment that the write operation was propagated
    to the specified number of instances.

  - Write concern timeout: Specifies a time limit for the write concern.

  - Write concern timeout timeunit: Specifies a time unit for the Write concern timeout field.

#### Connection Section

The following changes apply to the tabs in the **Connection** section of the global configuration:

- Added the following fields to the General tab:

  - Required Libraries: Reference to the MongoDB Driver.The version must be 3.11 or later.

  - Server Addresses: This field is now is a list of server addresses to use for the connection.

- Added a Security tab for optional TLS context configuration.

- Added the following optional fields to the Advanced tab:

  - Authentication mechanism: Authentication mechanism used for this connection

  - Replica set name: Name of the replica set to which to connect

  - Authentication source: Database name associated with the user’s credentials

  - Compressors: List of compressors for which to enable network compression for communication
    between this client and a mongod/mongos instance

  - Zlib compression level: Integer that specifies the compression level if using zlib for network
    compression.

    Set this field to 0 for no compression or from 1 through 9 for compression, with 1 being the
    lowest compression level and 9 the highest. High compression levels require more processing time
    than low compression levels.

  - Connection timeout: Connection timeout used when establishing the socket connections

  - Connection timeout time unit: Time unit for the Connection timeout field

  - Local threshold: Size of the latency window for selecting among multiple suitable MongoDB
    instances

  - Local threshold time unit: Time unit for the Local threshold time unit field

  - Server selection timeout: How long to block for server selection before throwing an exception

  - Server selection timeout time unit: Time unit for the Server selection timeout field

  - Socket timeout: Maximum time to wait for a send or receive operation on a socket before the
    attempt times out

  - Socket timeout unit: Time unit for the Socket timeout field

  - Min connection pool size: Minimum size for the connection pool

  - Max connection pool size: Maximum size for the connection pool

  - Max wait queue time: Maximum wait queue time for the connection pool

  - Max wait queue time unit: Time unit for the Maximum wait queue time field

  - Max connection life time: Maximum connection lifetime for the connection pool

  - Max connection life time time unit: Time unit for the Maximum connection life time field

  - Max connection idle time: Maximum connection idle time for the connection pool

  - Max connection idle time unit: Time unit for the Maximum connection idle time field

## Changed Operations, Parameters, and Return Types

The following table shows changes to operation names, input parameters, and return types:

<table><colgroup><col> <col></colgroup><thead><tr><th>MongoDB 5.x Operation</th><th>Changes in MongoDB 6.0</th></tr></thead><tbody><tr><td><p>Count documents</p></td><td><div><div><p>Input parameters are now:</p></div><div><ul><li><p><code>Collection name</code> (String)</p></li><li><p><code>Query</code> (JSON)</p></li></ul></div><div><p>Return type is now Long with the count result.</p></div></div></td></tr><tr><td><p>Create Collection</p></td><td><div><div><p>Input parameters are now:</p></div><div><ul><li><p><code>Collection name</code> (String)</p></li><li><p><code>Max objects</code> (Integer)</p></li><li><p><code>Collection size</code> (Integer)</p></li><li><p><code>Collection size data unit</code> (TimeUnit)</p></li></ul></div></div></td></tr><tr><td><p>Exists collection</p></td><td><p>Operation is now called Collection exists.</p></td></tr><tr><td><p>Create file from payload</p></td><td><div><div><ul><li><p>Operation is now called Create file.</p></li><li><p>Return type is now JSON.</p></li></ul></div></div></td></tr><tr><td><p>Create index</p></td><td><div><div><p>Input parameters are now:</p></div><div><ul><li><p><code>Collection name</code> (String)</p></li><li><p><code>Field name</code> (String)</p></li><li><p><code>Sort order</code> (Enum: ASC or DESC)</p></li></ul></div></div></td></tr><tr><td><p>Dump</p></td><td><div><div><p>Input parameters are now:</p></div><div><ul><li><p><code>Output directory</code> (String)</p></li><li><p><code>Output name prefix</code> (String)</p></li><li><p><code>Oplog</code> (no change)</p></li><li><p><code>Operation timeout</code> (Integer)</p></li><li><p><code>Operation timeout unit</code> (TimeUnit)</p></li></ul></div><div><p>Return type is now a List&lt;String&gt; type that points to the created files. Each string is a filePath type.</p></div></div></td></tr><tr><td><p>Execute command</p></td><td><div><div><ul><li><p>Input parameter is <code>Command</code> (JSON).</p></li><li><p>Return type is now a JSON type that contains the result of the command.</p></li></ul></div></div></td></tr><tr><td><p>Find documents</p></td><td><div><div><p>Input parameters are now:</p></div><div><ul><li><p><code>Collection name</code> (String)</p></li><li><p><code>Query</code> (JSON)</p></li><li><p><code>Fields</code> (String)</p></li><li><p><code>Sort by</code> (JSON)</p></li><li><p><code>Page size</code> (Integer)</p></li><li><p><code>Limit</code> (Integer)</p></li></ul></div><div><p>This operation supports pagination. Each item returned as a JSON type.</p></div></div></td></tr><tr><td><p>Find files</p></td><td><div><div><ul><li><p>Input parameters are now:</p><div><ul><li><p><code>Query</code> (JSON)</p></li><li><p><code>Sort</code> (JSON)</p></li></ul></div></li><li><p>Return type is now a JSON list.</p></li></ul></div></div></td></tr><tr><td><p>Get file content</p></td><td><div><div><ul><li><p>Input parameter is now <code>File id</code> (JSON).</p></li><li><p>Return type is now a stream with the binary file content. This operation also returns the file information as attributes.</p></li></ul></div></div></td></tr><tr><td><p>Insert document</p></td><td><p>Return type is now an entire JSON object with the <code>_id</code> object of the created document.</p></td></tr><tr><td><p>Insert documents</p></td><td><p>Return type is now a Bulk Operation Result, which contains a JSON file that lists each created record and its status.</p></td></tr><tr><td><p>List collections</p></td><td><p>Return type is now a List&lt;String&gt; type that contains the names of the collections.</p></td></tr><tr><td><p>List indices</p></td><td><p>Operation is now called List indexes.</p></td></tr><tr><td><p>Map reduce objects</p></td><td><div><div><ul><li><p>Operation is now called Map reduce.</p></li><li><p>Return type is now a JSON type that represents the output specified in the reduce function.</p></li></ul></div></div></td></tr><tr><td><p>Remove documents</p></td><td><div><div><ul><li><p>Input parameters are now:</p><div><ul><li><p><code>Collection name</code> (String)</p></li><li><p><code>Query</code> (JSON)</p></li></ul></div></li><li><p>Return type is now a Long with the count result.</p></li></ul></div></div></td></tr><tr><td><p>Remove files</p></td><td><p>Input parameter is now <code>File id</code> (JSON).</p></td></tr><tr><td><p>Update documents</p></td><td><div><div><ul><li><p>Input parameters are now:</p><div><ul><li><p><code>Collection name</code> (String)</p></li><li><p><code>Query</code> (JSON)</p></li><li><p><code>Content to update</code> (JSON)</p></li><li><p><code>Multiple update</code> (Boolean: moved to the Advanced tab)</p></li><li><p><code>Upsert</code> (Boolean)</p></li></ul></div></li><li><p>Return type is now a JSON type that contains the following structure:</p><div><ul><li><p>Int Matched</p></li><li><p>Int Modified</p></li><li><p>String Upserted Id</p></li></ul></div></li></ul></div></div></td></tr></tbody></table>

## Changed Operations Metadata

MongoDB 5.x generated operations metadata when the user provided a set of documents per collection
from which to take the attributes. MongoDB 6.0 generates metadata automatically, based on the latest
document in each collection.

### Metadata in MongoDB v6.0

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Operation Name</th><th>Input Metadata</th><th>Output Metadata</th></tr></thead><tbody><tr><td><p>Insert Document</p></td><td><p>Document</p></td><td><p>Resolved dynamically based on the selected value of the collection parameter. The connector adds the latest document of the given collection and uses the document’s structure as input/output metadata.</p></td></tr><tr><td><p>Insert Documents</p></td><td><p>Document</p></td><td><p>Resolved dynamically based on the selected value of the collection parameter. The connector adds the latest document of the given collection and uses the document’s structure as input/output metadata.</p></td></tr><tr><td><p>Update Documents</p></td><td><p>Not applicable</p></td><td><div><div><p>JSON that contains the following structure:</p></div><div><ul><li><p>Int Matched</p></li><li><p>Int Modified</p></li><li><p>JSON upsertedId</p></li></ul></div></div></td></tr><tr><td><p>Remove Documents</p></td><td><p>Query: JSON Object</p></td><td><p>Not applicable</p></td></tr><tr><td><p>Count Documents</p></td><td><p>Query: JSON Object</p></td><td><p>Not applicable</p></td></tr><tr><td><p>Find Documents</p></td><td><p>Query: JSON Object</p></td><td><p>Resolved dynamically based on the selected value of the collection parameter. The connector uses the structure of the last document in the given collection.</p></td></tr><tr><td><p>Create File</p></td><td><p>Not applicable</p></td><td><div><div><p>A JSON object with the following attributes:</p></div><div><ul><li><p>JSON Id</p></li><li><p>String fileName</p></li><li><p>Long Length</p></li><li><p>Int ChunkSize</p></li><li><p>Datetime uploadDate</p></li><li><p>JSON Metadata</p></li></ul></div></div></td></tr><tr><td><p>Find Files</p></td><td><p>Not applicable</p></td><td><div><div><p>List of JSON objects with the following attributes:</p></div><div><ul><li><p>JSON Id</p></li><li><p>String fileName</p></li><li><p>Long Length</p></li><li><p>Int ChunkSize</p></li><li><p>Datetime uploadDate</p></li><li><p>JSON Metadata</p></li></ul></div></div></td></tr></tbody></table>

## Removed Operations

The following operations were removed from the MongoDB connector:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th colspan="2">Removed from MongoDB 5.x</th><th colspan="2">Can be reproduced in MongoDB 6.0.0 through</th></tr></thead><tbody><tr><td><p>Name</p></td><td><p>Description</p></td><td><p>Name</p></td><td><p>Description</p></td></tr><tr><td><p>Incremental dump</p></td><td><p>Executes an incremental dump of the database</p></td><td><p>Dump</p></td><td><p>Use the Dump operation.</p></td></tr><tr><td><p>Restore</p></td><td><p>Takes the output from the dump and restores it</p></td><td><p>Restore from file or Restore from directory</p></td><td><p>Restore from file or Restore from directory take the output from the dump file or directory and restore it.</p></td></tr><tr><td><p>Update documents by function</p></td><td><p>Update documents using a Mongo function</p></td><td><p>Not applicable</p></td><td><p>Not applicable</p></td></tr><tr><td><p>Update documents by functions</p></td><td><p>Update documents using one or more Mongo functions</p></td><td><p>Not applicable</p></td><td><p>Not applicable</p></td></tr><tr><td><p>Find one and update document</p></td><td><p>Finds and updates the first document that matches a given query</p></td><td><p>Not applicable</p></td><td><p>This operation’s functionality can be reproduced by combining other operations.</p><p>For example, you can invoke the Find documents operation with a limit of 1 document. Then you can invoke the Update documents operation using the ID of the document returned previously.</p></td></tr><tr><td><p>Save document</p></td><td><p>Inserts or updates a document based on its object ID</p></td><td><p>Not applicable</p></td><td><p>Not applicable</p></td></tr><tr><td><p>Find one document</p></td><td><p>Finds the first document that matches a given query</p></td><td><p>Find documents</p></td><td><p>Set the Limit=1 to return one document.</p></td></tr><tr><td><p>Execute generic command</p></td><td><p>Executes a generic command on the database</p></td><td><p>Execute command</p></td><td><p>Executes a command on the database</p></td></tr><tr><td><p>List files</p></td><td><p>Lists all files that match the given query and sorts them by filename</p></td><td><p>Not applicable</p></td><td><p>Not applicable</p></td></tr><tr><td><p>Find one file</p></td><td><p>Returns the first file that matches the given query</p></td><td><p>Find files</p></td><td><p>Specify a specific file to query</p></td></tr></tbody></table>

## Removed Parameters

The **Num To Skip** field in the **Find Documents** operation is removed from MongoDB Connector 6.x.
The `skip()` method in MongoDB, which is used internally by the **Num To Skip** field, can lead to
performance issues, especially as the offset increases. This is because the server scans through the
results from the beginning to the specified offset before returning any documents, which adds
unnecessary load and slows down the operation.

To optimize pagination and improve performance when migrating to MongoDB Connector 6.x, the
following approaches are recommended:

- Avoid using `skip()` for large offsets.

  Instead of using the **Num To Skip** field, it is more efficient to refine query conditions to
  exclude unwanted documents directly.

- Use range queries.

  Use existing indexes to perform range queries. For example, if your documents have a timestamp or
  a unique ID field (indexed), you can use these fields to filter results directly to avoid scanning
  through unwanted documents.

  ```json
  { "timestamp": { "$gt": ISODate("2024-01-01T00:00:00Z") } }
  ```

- Apply `limit()` for pagination.

  Use the `limit()` method in combination with range queries to control the number of documents
  returned, effectively implementing pagination without the performance issues associated with
  `skip()`.

  ```json
  { "timestamp": { "$gt": ISODate("2024-01-01T00:00:00Z") } }
  .limit(10)
  ```

- Combine filters and sorting.

  Consider ordering documents by an indexed field, which allows for more efficient queries when
  paginating through results.

## Changes in Input Sources

MongoDB 6.0.0 has one input source, Object Listener, which retrieves all of the created documents
that belong to a specific collection.

The Delete Sources and Update Sources input sources were removed.

### Metadata in Object Listener

<table><colgroup><col> <col></colgroup><thead><tr><th>Input Metadata</th><th>Output Metadata</th></tr></thead><tbody><tr><td><p>Not applicable</p></td><td><p>The connector resolves output metadata dynamically based on the selected value of the Collection Name parameter. The connector reads the last document of the given collection and uses the document’s structure as output metadata.</p></td></tr></tbody></table>

## Requirements and Limitations

<table><colgroup><col> <col></colgroup><thead><tr><th>Software</th><th>Version</th></tr></thead><tbody><tr><td><p>Mule</p></td><td><p>4.1.1 and later</p></td></tr><tr><td><p>MongoDB</p></td><td><p>MongoDB Java driver 3.11 and later</p></td></tr></tbody></table>

## Upgrade Prerequisites

Before you perform the upgrade, you must:

1.  Create a backup of your files, data, and configuration in case you need to restore to the
    previous version.

2.  Install MongoDB v6.0 to replace the MongoDB operations that were previously included in MongoDB
    Connector v5.x.

## Upgrade Steps

Follow these steps to perform the upgrade from MongoDB Connector v5.3.x to MongoDB Connector v6.0:

1.  In Anypoint Studio, create a Mule project.

2.  In the Mule Palette view, click **Search in Exchange**.

3.  In the **Add Dependencies to Project** window, enter `MongoDB` in the search field.

4.  In the **Available modules** section, select **MongoDB Connector** and click **Add**.

5.  Click **Finish**.

6.  Verify that the salesforce-connector dependency version is 6.0.0 in the `pom.xml` file in the
    Mule project.

Studio upgrades the connector automatically.

## Verify the Upgrade

After you install the latest version of the connector, follow these steps to verify the upgrade:

1.  In Studio, verify that there are no errors in the **Problems** or **Console** views.

2.  Check the project `pom.xml` file and verify that there are no problems.

3.  Test the connection and verify that the operations work.

## Troubleshooting

If there are problems with caching the parameters and metadata, try restarting Studio.

## Revert the Upgrade

If it is necessary to revert to the previous version of MongoDB Connector, change the
mule-mongodb-connector dependency version 6.0.0 in the project’s `pom.xml` to the previous version.

## See Also

- [Introduction to Anypoint Connectors](https://docs.mulesoft.com/connectors/introduction/introduction-to-anypoint-connectors)

- [Salesforce Help](https://help.salesforce.com)