# MongoDB

Add a MongoDB database as an external catalog in Altertable to query its collections with SQL alongside your other data sources. Each collection in the connected database appears as a table.

## Prerequisites

### Allow Altertable egress IPs

If inbound traffic is restricted—including **MongoDB Atlas** IP access lists—allow [Altertable's egress IP addresses](/docs/lakehouse/network.md#egress-ip-addresses) so Workers can connect.

For Atlas:

1. Open the Atlas project and go to **Network Access**
2. Click **Add IP Address**
3. Add each [egress IP address](/docs/lakehouse/network.md#egress-ip-addresses) (Atlas accepts the address or `address/32`)
4. Confirm the entries are active before you test the catalog in Altertable

You can also connect a self-hosted MongoDB server through an [SSH tunnel](/docs/lakehouse/external-catalogs.md).

### Create a database user

Use a MongoDB database user, not your Atlas organization login. In Atlas, create the user under **Database Access** with read access to the database you will query.

## Connecting to Altertable

To add a new MongoDB external catalog:

1. Navigate to the **Catalogs** section in the dashboard

2. Click **New catalog**

3. Select **MongoDB** as the engine

4. Fill in the connection details:

   - **Connection string** (optional): Paste a `mongodb://` or `mongodb+srv://` URL to fill Host, username, SRV, and related options. Enter the password separately. Atlas connection strings often omit the database name, so you still need to set **Database**.
   - **Host**: The hostname. For Atlas, use the hostname from the connection string, such as `cluster0.xxxxx.mongodb.net`—without `mongodb+srv://` or credentials.
   - **Port**: Default `27017`. Leave it empty when **SRV connection** is enabled.
   - **Database**: The MongoDB database whose collections you want to query (for example, `sample_mflix`). Collections in that database appear as tables.
   - **Username**: The database user
   - **Password**: The database user password
   - **SRV connection**: Use a `mongodb+srv` connection and discover hosts through DNS
   - **TLS**: Encrypt the connection with TLS. Atlas SRV connections already use TLS, so you typically leave this off unless you need a custom CA.
   - **Authentication source** (optional): Database where the user is defined, often `admin`
   - **CA certificate** (optional): Custom CA used to verify the MongoDB server

5. Click **Save**

> **Atlas: enable SRV connection:**
>
> Atlas clusters advertise hosts through DNS SRV records (`mongodb+srv`). Enable **SRV connection**. If you leave it off, Altertable can still connect, but collections often fail to appear in the schema.

![New MongoDB connection form](/screenshots/app-components-connections-connection-form--mongo-empty.png)

*New MongoDB connection form*

Once added, collections from the connected database show up as tables in the catalog browser. You can query them with DuckDB SQL:

```sql
SELECT * FROM mongo.sample_mflix.comments LIMIT 100;
```

If the catalog is named `mongo` and the database is `sample_mflix`, the fully qualified table name is `mongo.sample_mflix.comments`.

## Atlas mapping

| Atlas                                           | Altertable                                   |
| ----------------------------------------------- | -------------------------------------------- |
| Cluster hostname (`cluster0.xxxxx.mongodb.net`) | **Host**                                     |
| Database (`sample_mflix`)                       | **Database** (schema in the catalog browser) |
| Collection (`comments`)                         | Table                                        |
| Database user                                   | **Username** and **Password**                |