# How to Construct a MongoDB Sharded Cluster Connection String for External Clients

> Learn how to construct MongoDB sharded cluster connection strings for external clients. Connect easily to mongos router instances using a straightforward format.

- Repository: [Jin/mongodb-cluster-docker-compose](https://github.com/minhhungit/mongodb-cluster-docker-compose)
- Tags: how-to-guide
- Published: 2026-03-07

---

**External clients connect to the sharded cluster by targeting the two mongos router instances exposed on host ports 27117 and 27118, using a connection string format like `mongodb://127.0.0.1:27117,127.0.0.1:27118`.**

When deploying a MongoDB sharded cluster using Docker Compose, external applications cannot connect directly to the internal shard nodes. Instead, they must route requests through the **mongos** query routers. In the `minhhungit/mongodb-cluster-docker-compose` repository, the Docker Compose configuration exposes two router containers on specific host ports, making it straightforward to construct a MongoDB sharded cluster connection string for external access.

## Understanding the Router Architecture

The cluster deploys two mongos instances named `router01` and `router02`. According to the [`docker-compose.yml`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/docker-compose.yml) file, each router maps container port 27017 to distinct host ports:

- **router01** (container `router-01`): Host port **27117**
- **router02** (container `router-02`): Host port **27118**

These mappings are defined in the [router services section](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/master/docker-compose.yml#L4-L13) of the compose file. External clients treat these host ports as the entry points to the entire sharded cluster.

## Basic Connection String Format

For unauthenticated connections, the standard MongoDB connection string lists both router endpoints separated by commas:

```text
mongodb://<host>:27117,<host>:27118

```

Replace `<host>` with the IP address or hostname where Docker is running. For local development, this is typically `127.0.0.1` or `localhost`. The repository's README explicitly documents this example:

```

mongodb://127.0.0.1:27117,127.0.0.1:27118

```

Listing both routers enables driver-level **load balancing** and **automatic failover**. If `router01` becomes unavailable, the driver seamlessly routes requests to `router02` without application code changes.

## Connecting with Authentication

The repository includes a `with-keyfile-auth` variant that enables internal authentication between cluster nodes. When using this configuration, external clients must provide credentials in the connection string.

The format becomes:

```text
mongodb://<username>:<password>@<host>:27117,<host>:27118/?authSource=admin

```

Key parameters:

- **username/password**: Credentials for a user created in the `admin` database
- **authSource=admin**: Required because authentication credentials are stored in the admin database, not the default test database

Note that the repository does not automatically create client users. You must connect to a router via `mongosh` or the shell and execute `db.createUser()` in the `admin` database before external authenticated connections will succeed.

## Practical Connection Examples

### MongoDB Shell (mongosh)

Connect to the cluster using the MongoDB shell:

```bash
mongosh "mongodb://127.0.0.1:27117,127.0.0.1:27118"

```

With authentication:

```bash
mongosh "mongodb://myUser:myPass@127.0.0.1:27117,127.0.0.1:27118/?authSource=admin"

```

### Node.js

Using the native MongoDB driver:

```javascript
const { MongoClient } = require('mongodb');

const uri = 'mongodb://127.0.0.1:27117,127.0.0.1:27118';
const client = new MongoClient(uri, { useUnifiedTopology: true });

async function run() {
  await client.connect();
  const db = client.db('MyDatabase');
  const coll = db.collection('MyCollection');
  await coll.insertOne({ msg: 'Hello from Node.js' });
  console.log('Document inserted');
  await client.close();
}

run().catch(console.error);

```

### Python (PyMongo)

```python
from pymongo import MongoClient

uri = "mongodb://127.0.0.1:27117,127.0.0.1:27118"
client = MongoClient(uri)

db = client["MyDatabase"]
coll = db["MyCollection"]
coll.insert_one({"msg": "Hello from Python"})
print("Inserted document")
client.close()

```

### C# (.NET)

The repository includes sample .NET clients in [`client/DemoMongoClusterWriter/Program.cs`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/client/DemoMongoClusterWriter/Program.cs) and [`client/DemoMongoClusterReader/Program.cs`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/client/DemoMongoClusterReader/Program.cs). Basic connection:

```csharp
using MongoDB.Driver;

var connectionString = "mongodb://127.0.0.1:27117,127.0.0.1:27118";
var client = new MongoClient(connectionString);
var database = client.GetDatabase("MyDatabase");
var collection = database.GetCollection<BsonDocument>("MyCollection");

await collection.InsertOneAsync(new BsonDocument { { "msg", "Hello from .NET!" } });

```

## Summary

- External clients connect exclusively through the **mongos** routers exposed on host ports **27117** and **27118**.
- The standard **MongoDB sharded cluster connection string** format lists both router endpoints: `mongodb://host:27117,host:27118`.
- Listing multiple routers provides automatic **failover** and **load balancing** at the driver level.
- When using the `with-keyfile-auth` configuration, append credentials and `authSource=admin` to the connection string.
- The repository provides working examples in **Node.js**, **Python**, **C#**, and **MongoDB Shell**.

## Frequently Asked Questions

### Do I need to include the shard replica set names in the connection string?

No. External clients should never connect directly to shard replica sets in a MongoDB sharded cluster. Always connect through the **mongos** routers. The connection string only needs to list the router endpoints (ports 27117 and 27118). The `mongos` process handles routing queries to the appropriate shards internally.

### Can I connect to just one router instead of listing both?

Yes, a connection string with a single router (e.g., `mongodb://127.0.0.1:27117`) will work. However, listing both routers in the connection string is strongly recommended for **high availability**. If the single router you specified goes down, your application loses connectivity. With both routers listed, MongoDB drivers automatically fail over to the healthy instance.

### How do I enable authentication for external clients?

The repository ships with a `with-keyfile-auth` folder containing a Docker Compose configuration that enables internal authentication. To enable client authentication:

1. Start the cluster using the keyfile-auth configuration.
2. Connect to one of the routers using the shell.
3. Create a user in the `admin` database: `db.createUser({user: "myUser", pwd: "myPass", roles: [{role: "readWrite", db: "myDatabase"}]})`.
4. Update your connection string to include the credentials and `authSource=admin` parameter.

### What host IP should I use when connecting from outside the Docker host?

Use the IP address or hostname of the machine running Docker. If you are connecting from a different machine on the network, replace `127.0.0.1` with the Docker host's network IP address (e.g., `192.168.1.100`). Ensure that the host ports (27117 and 27118) are not blocked by firewalls and are accessible from the client machine.