# MongoDB Connection Strings

> The MongoDB connection strings API Maker takes - mongodb:// and mongodb+srv://, replica sets, MongoDB Atlas, TLS - with examples, how to add one to an instance, and the common errors.

Source: https://docs.apimaker.dev/v4/docs/Database-connection-string/mongodb-connection-strings.html

API Maker connects to MongoDB with the official driver of MongoDB, so it takes the connection strings of the [MongoDB manual](https://www.mongodb.com/docs/manual/reference/connection-string/), with their options.

## The format

```text
mongodb://user:password@host:port/?option=value&option=value
mongodb+srv://user:password@cluster.example.net/?option=value
```

| Part | What it is |
|---|---|
| `mongodb://` | The hosts written out, one or several : `db1:27017,db2:27017`. |
| `mongodb+srv://` | One name which DNS turns into the hosts. MongoDB Atlas gives this form. |
| `user:password@` | The user and its password. Write the password as it is, even with `@` or `:` in it : API Maker encodes it before it connects. |
| `host:port` | `27017` when no port is given. |
| `?options` | Options of the driver : `authSource`, `replicaSet`, `directConnection`, `tls`, `readPreference`, `w`, `maxPoolSize`… |

A database in the path only says where the user is defined, when `authSource` does not. An instance reaches every database its user may read.

## Examples

```text
# 1. A MongoDB on the same computer, without users
mongodb://127.0.0.1:27017

# 2. One member of a replica set, reached directly
mongodb://user:password@127.0.0.1:27017/?authSource=admin&replicaSet=rs0&directConnection=true

# 3. A replica set of three servers
mongodb://user:password@db1.example.com:27017,db2.example.com:27017,db3.example.com:27017/?authSource=admin&replicaSet=rs0

# 4. MongoDB Atlas
mongodb+srv://user:password@cluster0.abcde.mongodb.net/?retryWrites=true&w=majority

# 5. TLS, with the certificate of your own authority
mongodb://user:password@db.example.com:27017/?authSource=admin&tls=true&tlsCAFile=/root/certs/ca.pem
```

## Add it to API Maker

An instance never holds the connection string itself : it names a key of your [default secret](https://docs.apimaker.dev/v4/docs/secrets/secrets.html), where the string stays encrypted, out of Git.

1. **Put the string in the secret** **Security → Secret Management** → `Default`. Add it under `common.connectionString`, with a name of your choice, and save.
2. **Create the instance** **APIs & Logic → Instance API (DB API)** → add an instance : pick the database type, give it a name, and pick the key of the secret under **Connection**.
3. **Test it** **Test Instance** connects with the string. An instance which can not reach its database is not saved, and the form says why.

**Connection String Sandbox** is optional : a second key, for code which runs in a sandbox and reaches the database by another address than API Maker does.

## Common errors

| What you see | What to check |
|---|---|
| `Authentication failed` | The user, the password, and `authSource` : the database the user was created in, often `admin`. |
| `Server selection timeout` | API Maker can reach the server : the firewall, and `bindIp` in `mongod.conf`. A replica set answers with the names of its members : API Maker must reach those names too, or add `directConnection=true` to talk to one member only. |
| A timeout with MongoDB Atlas | The address of your API Maker server is in the IP access list of the cluster. |
| An error about the replica set | `replicaSet` is the name of the replica set, as `rs.status()` shows it. |

## Related

- [Secret Management](https://docs.apimaker.dev/v4/docs/secrets/secrets.html) · [Your first API](https://docs.apimaker.dev/v4/docs/getting-started/first-api.html) · [Connection strings in the MongoDB manual](https://www.mongodb.com/docs/manual/reference/connection-string/)