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

# Connecting your own MongoDB

> Connect your own MongoDB cluster so your apps' runtime data lives in a database you own, using an IP allowlist or AWS PrivateLink and password or AWS IAM auth.

Base44 supports connecting your own MongoDB database, so your apps' runtime data lives in a cluster you own and control.

> [!WARNING]
>
> Complete this setup before you create any apps in the workspace. Base44 needs an empty workspace to enable the connection, and apps created beforehand cannot be moved onto your database afterwards.

Work through the 6 steps in order. Steps 3 and 4 are independent of each other, so you can do those in either order, but everything else builds on what came before.

***

## Choosing your setup

There are 2 independent choices to make, and all 4 combinations are supported, including username and password over PrivateLink.

| Decision | Either | Or |
| - | - | - |
| **How Base44 authenticates** | **Username & password:** a database user in your cluster | **AWS IAM (passwordless):** Base44's IAM role, with no stored credential |
| **How Base44 reaches you** | **IP allowlist:** over TLS on the public internet, restricted to Base44's addresses | **AWS PrivateLink:** private connectivity that never traverses the public internet |

**AWS IAM** removes the shared secret entirely and is preferred where available. It requires an AWS-hosted cluster.

**AWS PrivateLink** is the stronger network posture. It requires a MongoDB Atlas dedicated cluster hosted on AWS, in any supported region, and involves 2 coordination steps with Base44, so allow extra lead time.

***

## Meeting the requirements

Check your cluster against these before you start. Base44 validates most of them when you save your connection, so a mismatch here shows up as a failure later.

| Requirement | Value |
| - | - |
| Deployment type | Replica set |
| MongoDB version | 7.0 or later. Compound wildcard indexes, used when you create the indexes, are new in version 7.0 |
| Minimum storage | 100 GB. Managing and extending capacity is your responsibility |
| Database name | `app_prod`. Base44 confirms the current name for your environment |
| TLS | Required, with valid certificates |
| Workspace state | No apps created yet |
| If using AWS IAM | Cluster hosted on AWS |
| If using AWS PrivateLink | MongoDB Atlas, dedicated tier, hosted on AWS in any supported region. Tell your Base44 contact which region your cluster is in before you start |

> [!NOTE]
>
> **Before you create your cluster:**
>
> * Free and Flex clusters cannot use private endpoints, and dedicated tiers currently start at M10. Talk to your Base44 contact first if you run Amazon DocumentDB or self-managed MongoDB.
> * Set your region now rather than later. Moving a cluster to another region rebuilds all 3 nodes, and a private endpoint cannot be used until nodes are running in its own region again.

***

## Step 1: Create the database

Create the cluster to match the requirements above, then create the database Base44 gives you. For production this is currently `app_prod`.

```javascript theme={null}
const byomDb = db.getSiblingDB("app_prod");
```

Collections are created on demand, so you do not need to create them yourself.

***

## Step 2: Create the indexes

Base44 does not create or modify indexes on your cluster. All indexing is yours to manage, including the ones below. Run these against `app_prod`.

> [!WARNING]
>
> **Two indexes need particular care:**
>
> * `support_access_ttl_idx` must include `expireAfterSeconds: 0`. Base44 grants time-limited support access by writing an expiry timestamp onto app-user rows, and this TTL index is what removes them. Without that option it is an ordinary index and those rows never expire.
> * `wildcard_first` is a compound wildcard index, which requires MongoDB 7.0 or later.

```javascript theme={null}
const byomDb = db.getSiblingDB("app_prod");

byomDb.entitys.createIndexes([
  { key: { app_id: 1, entity_name: 1, is_deleted: 1, created_date: -1 },
    name: "app_id_1_entity_name_1_is_deleted_1_created_date_-1" },
  { key: { app_id: 1, entity_name: 1, is_deleted: 1, _id: 1 },
    name: "app_id_1_entity_name_1_is_deleted_1__id_1" },
  { key: { "data.$**": 1, app_id: 1, entity_name: 1, is_deleted: 1, created_date: -1 },
    name: "wildcard_first" }
]);

byomDb.app_users.createIndexes([
  { key: { app_id: 1, email: 1 }, name: "app_id_1_email_1" },
  { key: { email: 1, role: 1, created_date: -1 },
    name: "email_1_role_1_created_date_-1" },
  { key: { updated_date: -1 }, name: "updated_date_-1" },
  { key: { support_access_expires_at: 1 },
    name: "support_access_ttl_idx",
    expireAfterSeconds: 0 }
]);
```

***

## Step 3: Set up network access

Choose the option that matches your decision above.

### Using an IP allowlist

Add these Base44 ranges to your MongoDB IP access list:

```text theme={null}
74.220.48.0/24
74.220.56.0/24
```

Confirm the current ranges with your Base44 contact before you finalize your firewall rules.

### Using AWS PrivateLink

Base44 runs in AWS us-west-2 (Oregon), so Base44's side of the connection is always there. Your cluster does not have to be:

* **A cluster in us-west-2:** The simplest and fastest path, with nothing extra to do.
* **A cluster in another AWS region:** Supported, with one extra step and extra lead time while Base44 provisions the connectivity. Expect some added latency on database calls, and cross-region data transfer charges on your side. Tell your Base44 contact which region you are in before you start, so they can confirm they can reach it.

This needs 2 handoffs with Base44, and neither side can complete it alone. Keep the Atlas wizard open between steps 3 and 5.

**To set up AWS PrivateLink:**

1. In Atlas, go to **Network Access** > **Private Endpoint** > **Dedicated Cluster**, then click **Add Private Endpoint**. Choose **AWS** and the region your cluster is in.
2. If your cluster is not in us-west-2, click **Edit** next to **Accepted Endpoint Regions** on the endpoint service Atlas just created, then add **us-west-2**. Do this before you send anything to Base44. Without it, Base44 cannot create the connection at all, and you never receive the ID in step 4.
3. Wait for Atlas to create a VPC endpoint service, which takes 3 to 5 minutes, then send the service name it shows to your Base44 contact. It looks like `com.amazonaws.vpce.<your-region>.vpce-svc-xxxxxxxxxxxx`. Do not fill in the **Create New Endpoint** form, because it asks for a VPC and subnets that belong to Base44 rather than you.
4. Wait for Base44 to create the matching interface endpoint and send you back a 22-character endpoint ID, which looks like `vpce-01d2…`.
5. Back in Atlas, click **Add Endpoint** and choose **Connect Existing Endpoint** rather than **Create New Endpoint**, because the endpoint already exists on Base44's side. Paste the ID you were sent, then wait for the status to show **Available**.

> [!NOTE]
>
> The 2 IDs are different things and easy to mix up. What you send Base44 is a long dotted service name containing `vpce-svc-`. What you receive is a short `vpce-…` with no `-svc-`.

***

## Step 4: Set up database access

Choose the option that matches your authentication decision.

### Using a username and password

Create a database user scoped to `app_prod`, and give it read and write access across the whole database.

**To add a database user:**

1. In Atlas, go to **Security** > **Database Access**, then click **Add New Database User**.
2. Under **Authentication Method**, select **Password**, then set a username and password.
3. Under **Database User Privileges** > **Specific Privileges**, add one privilege: the role **readWrite**, the database **app\_prod**, and the collection left blank.
4. Click **Add User**.

Leaving the collection blank grants read and write access on all collections in that database, which Base44 needs. Do not scope it to a single collection, because that causes a "not authorized to insert" error.

### Using AWS IAM

Register Base44's IAM role as a database user on your cluster. No password is created or stored, because Base44 mints short-lived credentials at connection time.

**To add Base44's IAM role as a database user:**

1. In Atlas, go to **Security** > **Database Access**, then click **Add New Database User**.
2. Under **Authentication Method**, select **AWS IAM**.
3. Under **AWS IAM Type**, select **IAM Role**.
4. Enter the ARN `arn:aws:iam::789051085499:role/Base44-Access`.
5. Under **Database User Privileges** > **Specific Privileges**, add one privilege: the role **readWrite**, the database **app\_prod**, and the collection left blank.
6. Click **Add User**.

***

## Step 5: Build your connection string

Atlas gives you a string that is not quite the shape Base44 needs, so you copy it from Atlas and then adjust it. Atlas asks 2 things in order, and the first is where the PrivateLink path usually goes wrong. Both paths end at **Drivers**, but the connection type you pick first is what decides whether you get the private host or the public one.

**To get your connection string from Atlas:**

1. In Atlas, go to **Clusters**, then click **Connect**.
2. For **Connection type**, pick **Private Endpoint** if you set up PrivateLink, or the standard connection otherwise.
3. For **Connection method**, pick **Drivers**, then copy the string it shows.

| Your network choice | Connection type | Host you should end up with |
| - | - | - |
| IP allowlist | Standard connection | `yourcluster.ab12c.mongodb.net` |
| AWS PrivateLink | Private Endpoint | `yourcluster-pl-0.ab12c.mongodb.net` |

> [!WARNING]
>
> If you chose PrivateLink and your host has no `-pl-` in it, you have copied the public endpoint. It connects and validates successfully, and quietly defeats the purpose of the setup. Check for `-pl-` before you continue.

Adjust your copied string to match the line for your combination.

**Username and password with an IP allowlist:**

```text theme={null}
mongodb+srv://USER:PASSWORD@yourcluster.ab12c.mongodb.net/app_prod?tls=true&retryWrites=true&w=majority
```

**Username and password with PrivateLink:**

```text theme={null}
mongodb+srv://USER:PASSWORD@yourcluster-pl-0.ab12c.mongodb.net/app_prod?tls=true&retryWrites=true&w=majority
```

**AWS IAM with an IP allowlist:**

```text theme={null}
mongodb+srv://yourcluster.ab12c.mongodb.net/?authMechanism=MONGODB-AWS&authSource=$external&tls=true
```

**AWS IAM with PrivateLink:**

```text theme={null}
mongodb+srv://yourcluster-pl-0.ab12c.mongodb.net/?authMechanism=MONGODB-AWS&authSource=$external&tls=true
```

The AWS IAM strings have no username or password, which is expected.

### Rules your connection string must satisfy

Base44 rejects a string that breaks any of these outright, rather than warning you.

| Rule | Notes |
| - | - |
| `tls=true` set explicitly | The most common failure. Atlas's copied string does not include it, so append `&tls=true` |
| Database path `/app_prod`, or omitted | Any other database name is rejected |
| URL-encode special characters in the username or password | Password authentication only |
| No `tlsInsecure`, `tlsAllowInvalidCertificates`, `tlsAllowInvalidHostnames`, or `tlsDisableOCSPEndpointCheck` | Certificate validation cannot be disabled |
| No `tlsCAFile`, `tlsCertificateKeyFile`, or `tlsCRLFile` | Custom CA bundles and mTLS are not supported |
| No `srvServiceName` | The SRV service name cannot be customized |
| No `w=0` | Write acknowledgement cannot be disabled |
| Password authentication must include `USER:PASSWORD` and must not set `authMechanism=MONGODB-AWS` | |
| AWS IAM must not include credentials, and must set `authMechanism=MONGODB-AWS` and `authSource=$external` | |

> [!WARNING]
>
> Base44 treats your connection string as a high-security secret. The raw value is stored only in encrypted secret storage and used server-side solely to establish the connection, and the settings screen and API show only a redacted form afterwards. Provide it only through your workspace settings, never by email or chat.

***

## Step 6: Complete setup in Base44

Once your cluster, indexes, network access, and database access are ready, connect it to your workspace.

**To complete your setup:**

1. Click your workspace name at the bottom left of your account.
2. Click **Settings**.
3. Click **Overview**.
4. Under **Data hosting** > **Workspace MongoDB connection**, select your **Authentication method**, either **Username & password** or **AWS IAM (passwordless)**, to match your database access.
5. Paste your connection string. The database name is fixed to `app_prod` and cannot be edited.
6. Click **Validate and save**. Base44 connects to your cluster, runs a ping, then writes, reads back, and deletes one temporary document per validated collection. Nothing is saved if any check fails.
7. Once the status shows **Validated**, click **Enable**.
8. Create your apps only after the status shows **Enabled**.

> [!WARNING]
>
> Validation is not activation. Your runtime data routes to your database only after you complete the **Enable** step.

***

## After setup

A few things change once your connection is live, and 2 of them cannot be undone without help.

* Apps created after you enable the connection route their runtime entity and app-user data to your cluster. Base44 platform metadata, such as accounts, workspaces, billing, and app definitions, always remains on Base44-managed infrastructure.
* You cannot change the connection from your workspace settings once it is enabled. Rotating a password or moving clusters is a managed migration handled with Customer Care.
* You can disable the connection only before the workspace's first app is created. After that, changes need a managed migration.

***

## Troubleshooting

Base44 rejects a connection rather than accepting a broken one, so each failure comes with a specific message. Find yours below.

| Message | Cause | Fix |
| - | - | - |
| MongoDB URI must explicitly set `tls=true` | Atlas string copied as-is | Append `&tls=true` |
| BYOM URI database path must be `/app_prod` | The wrong database in the path | Use `/app_prod`, or drop the path |
| Authenticated, but the database user is not authorized | The user is scoped too narrowly | Grant **readWrite** on `app_prod` with the collection field blank |
| Authentication failed | The wrong password, or the IAM role ARN is not registered as an AWS IAM Role user | Re-check your database access |
| Could not reach the cluster | The IP ranges are not allowlisted, or the private endpoint is not yet **Available** | Re-check your network access |
| Base44 cannot create the connection, and you never receive a `vpce-` ID | `us-west-2` is missing from your endpoint service's **Accepted Endpoint Regions** | Add it, then ask your Base44 contact to try again |
| MongoDB URI host is not allowed | The host resolves to a private address Base44 cannot verify | Contact your Base44 contact |
| The enabled BYOM connection cannot be changed | You are editing an already-enabled connection | Contact Customer Care |

If your error is not listed here, contact your Base44 contact and we will help you get connected.


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