Skip to main content

MongoDB Advanced Connection Strings

For Controller and Server UI persistence you can use advanced connection strings to connect to MongoDB. Use advanced connection strings if you require support for these:


  • Replica Sets

  • Sharding

  • MongoDB Atlas


If you were using replica sets before the availability of the connection string option (2020.1 release), you have to change to a connection string.

Unique Connection Strings for Workers

Each worker can have a unique connection string that determines how it connects to the database. This allows remote worker nodes to use connections that differ from the controller to set credentials or options specific to a particular worker.

To set unique connection strings for a worker:

  1. Sign in to the worker for which you want to set a different MongoDB connection string than the controller.

  2. Open Command Prompt or PowerShell (as administrator).

  3. From the prompt navigate to C:\Program Files\Alteryx\bin.

  4. Enter this command: AlteryxService.exe setmongoconnectionworker="{mongoConnectionString}".

  5. Replace {mongoConnectionString} with the appropriate connection string for your environment. This connection string must connect to the same database as your controller. Scroll down to see examples of various connection string formats in the Controller Persistence Examples section.

  6. To apply the setting, restart the Alteryx Service:

    1. Navigate to the Windows Services application on your machine.

    2. Find the service named AlteryxService.

    3. Select the Restart the Service button.

Connection String Tips and Examples

  • Supported connection string parameters are driver dependent. To use them in a connection string, parameters have to be supported by all the below-listed supported drivers. Supported driver versions include...

    • c 1.17 (mongoc)

    • c++ 3.6 (mongocxx)

    • c# 2.12 (mongoc#)

  • Special characters in usernames, passwords, or parameter values have to be URL encoded.

Go to the MongoDB Connection String documentation for help formatting your connection string.

On-premise, single-node example with SSL/TLS:


On-premise, replica set, example with SSL/TLS:


Atlas example:


On-premise, single-node example with SSL/TLS:


On-premise, replica set, example with SSL/TLS:


Atlas example:


On-premise, single-node example with SSL/TLS:


On-premise, replica set, example with SSL/TLS:


Atlas example: