> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supaboard.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MongoDB

Connect Supaboard to a MongoDB database using a standard connection string (URI).

Open **Data sources → Connect Data Source → MongoDB** to use this guide. For the overall workflow and the check after setup, see [Connect a data source](/data-sources/connect-a-data-source).

## Before you connect

**Network access** — Supaboard connects from a fixed set of egress IPs. For MongoDB Atlas, add them to your cluster's IP access list under **Security → Network Access**. The current IP list is shown inside the connector form under **Whitelist IPs**.

**Database user permissions** — The user in your connection string needs at minimum:

* `read` role on the target database

See [Recommended database user permissions](#recommended-database-user-permissions) for instructions.

## Connection fields

| Field | Default | Required | Description |
| - | - | - | - |
| **Display Name** | — | Yes | Label shown in the Supaboard UI |
| **Connection String** | — | Yes | Full MongoDB URI (see format below) |

## Connection string format

Supaboard accepts a full MongoDB URI. The standard format is:

```text theme={null}
mongodb+srv://username:password@cluster-host/?authSource=admin
```

For non-SRV connections (self-hosted or older Atlas clusters):

```text theme={null}
mongodb://username:password@host:27017/database?authSource=admin
```

| Part | Description |
| - | - |
| `mongodb+srv://` | Use `+srv` for Atlas and DNS-based clusters; use `mongodb://` for direct host connections |
| `username:password` | MongoDB user credentials — URL-encode special characters (e.g. `@` → `%40`) |
| `cluster-host` | Cluster hostname (Atlas) or server IP/hostname (self-hosted) |
| `database` | Optional — the specific database to connect to; if omitted, Supaboard auto-discovers |
| `authSource=admin` | The authentication database — usually `admin` for Atlas |

## Finding your connection details

### MongoDB Atlas

1. Open [cloud.mongodb.com](https://cloud.mongodb.com) and select your project.
2. In the **Clusters** view, click **Connect** on your cluster.
3. Select **Drivers** (or **Connect your application**).
4. Choose any driver — you only need the connection string, not the code snippet.
5. Copy the connection string. It will look like:
   ```text theme={null}
   mongodb+srv://<username>:<password>@cluster0.xxxxx.mongodb.net/?retryWrites=true&w=majority
   ```
6. Replace `<username>` and `<password>` with your Atlas database user credentials.
7. Paste the full string into the **Connection String** field in Supaboard.

**Documentation:** [Connect to a cluster](https://www.mongodb.com/docs/atlas/connect-to-database-deployment/) · [Connection string URI format](https://www.mongodb.com/docs/manual/reference/connection-string/)

**Adding Supaboard IPs to Atlas:**

Atlas requires you to explicitly allow external IPs before any connection can succeed.

1. In your Atlas project, go to **Security → Network Access**.
2. Click **Add IP Address**.
3. Add each Supaboard egress IP individually (found in the connector form under **Whitelist IPs**).
4. Click **Confirm**.

> Atlas IP access list changes take effect immediately. You do not need to restart your cluster.

**Documentation:** [Configure IP access list entries](https://www.mongodb.com/docs/atlas/security/ip-access-list/)

## IPsec Site-to-Site VPN

If your database lives on a private network, you can peer your VPN gateway with Supaboard over IKEv2 IPsec instead of exposing the database or running a bastion host. Enable the **Use IPsec site-to-site VPN** toggle in the connector form.

| Field | Required | Description |
| - | - | - |
| **VPN Gateway Address** | Yes | Public IP of your VPN gateway — or a per-server mapping for providers with one tunnel endpoint per peer (OCI/AWS managed VPN), e.g. `<supaboard-ip>=<tunnel-ip>,…` |
| **Pre-Shared Key** | Yes | The PSK configured on your gateway for the Supaboard tunnels |
| **Remote Subnet** | No | CIDR the tunnel should route. Defaults to your database host `/32` |

**Checklist:**

* [ ] Your VPN gateway has one IKEv2 + pre-shared-key tunnel per Supaboard IP (the IPs shown under **Whitelist IPs**)
* [ ] The gateway allows UDP 500, UDP 4500, and ESP (IP protocol 50) from those IPs
* [ ] The **Host** field is the database's **private IP address** — private DNS names don't resolve from Supaboard
* [ ] Enter the database name manually — auto-discovery doesn't run through the VPN before the connection is saved

Gateway settings, supported ciphers, a strongSwan example, and troubleshooting: [IPsec Site-to-Site VPN guide](/data-sources/security/ipsec-vpn).

## Recommended database user permissions

In MongoDB Atlas:

1. Go to **Security → Database Access**.
2. Click **Add New Database User**.
3. Choose **Password** authentication.
4. Set a username and strong password.
5. Under **Database User Privileges**, select **Built-in Role → Read Only** (or use a custom role scoped to specific databases).
6. Click **Add User**.
7. Use this username and password in your connection string.

For self-hosted MongoDB:

```javascript theme={null}
use your_database
db.createUser({
  user: "supaboard",
  pwd: "strong_password_here",
  roles: [{ role: "read", db: "your_database" }]
})
```

## Troubleshooting

| Error | Likely cause | Fix |
| - | - | - |
| `connection refused` | Atlas IP access list missing Supaboard IPs | Add all Supaboard egress IPs under **Security → Network Access** |
| `Authentication failed` | Wrong username or password in the URI | Verify credentials in Atlas under **Security → Database Access** |
| `bad auth : authentication failed` | Wrong `authSource` | Add `?authSource=admin` to the URI |
| `URI must include hostname` | Malformed connection string | Check that the URI starts with `mongodb://` or `mongodb+srv://` |
| `querySrv ENODATA` | DNS resolution failing for `+srv` URI | Try switching to a direct `mongodb://` URI with explicit host and port |
| Special characters in password | URI parsing error | URL-encode special characters: `@` → `%40`, `#` → `%23`, `:` → `%3A` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.