> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/cloud/integrations/providers/mongodb.md).

# MongoDB

Connect MongoDB to the Database module — your own connection string, or a managed Atlas Flex cluster.

MongoDB holds your project's collections: connect a cluster you already run with its connection string, or let Norbix provision a managed MongoDB Atlas Flex cluster for you.

## Get your credentials

For your own cluster (MongoDB Atlas shown; any MongoDB that the Norbix runtime can reach works):

1. Open [MongoDB Atlas](https://cloud.mongodb.com) and sign in.
2. **Database Access** → **Add New Database User** — create a user with read and write rights on the database you will use.
3. **Network Access** → **Add IP Address** — allow traffic from the Norbix runtime IPs.
4. **Clusters** → **Connect** → **Drivers** → copy the connection string, for example `mongodb+srv://app:<password>@cluster0.example.mongodb.net`, and put the user's password in it.

For a managed **Atlas Flex** cluster you need nothing: Norbix creates the cluster, the database and the password. It is available on managed deployments of Norbix only.

## Connect it in Cloud

**Where:** Database → Integrations → **Add New Integration** → MongoDB (**Connect**) · `/projects/<project>/db/integrations/new/mongodb`

The form **New MongoDB Integration** first asks **How would you like to connect MongoDB?**: **Mongo DB (Connection String)** or **Mongo DB (Atlas Flex)**.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-974ce9d126695fa04b8b027f82f9ec776c0349e2%2Fmongodb-1.png?alt=media" alt="New MongoDB Integration: How would you like to connect MongoDB? with the cards Mongo DB (Connection String), selected, and Mongo DB (Atlas Flex), Available on managed deployments"><figcaption><p>Pick how to connect.</p></figcaption></figure>

With **Mongo DB (Connection String)**:

| Field                            | Required | What it does                                                                                            | Example                                                     |
| -------------------------------- | -------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| Connection String                | yes      | Your cluster's connection string. It is encrypted and never shown again; to change it, paste a new one. | `mongodb+srv://app:<password>@cluster0.example.mongodb.net` |
| Default Database Name (optional) | no       | The database to use, so calls do not have to name it.                                                   | `reporting`                                                 |
| Integration Name                 | yes      | The name in the list.                                                                                   | `Reporting replica`                                         |

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-bc42931529f5254106d36843a48a4e1122ef02f6%2Fmongodb-3.png?alt=media" alt="The connection-string form filled in: Connection String (hidden), the Info box that the secret will not be displayed again, Default Database Name reporting, Integration Name Reporting replica, Cancel and Save"><figcaption><p>The filled connection-string form.</p></figcaption></figure>

With **Mongo DB (Atlas Flex)**, pick a **Cluster tier** (**Flex**, or **M10** dedicated) and an **Integration Name**. The region follows your project's region; the database name and password are generated. After **Save** the integration shows *Cluster provisioning in progress* and becomes usable when provisioning finishes — the page updates by itself.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-318c0549cac20830d93b3b8a3e90b503465ee1f8%2Fmongodb-2.png?alt=media" alt="The Mongo DB (Atlas Flex) card selected; Cluster tier with the Flex card: 5 GB, Shared RAM, From $0.011/hour, up to $30/month"><figcaption><p>The Atlas Flex option and its cluster tiers.</p></figcaption></figure>

Press **Save**. The page becomes **Editing MongoDB integration** with the integration id (copy button) and the badges **ENABLED** · **NOT TESTED**.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-459d3f46719c967aa1e23de501f443a8b88c2135%2Fmongodb-4.png?alt=media" alt="Editing MongoDB integration after Save: the badges ENABLED and NOT TESTED, the integration id with a copy button and the Actions menu"><figcaption><p>After Save.</p></figcaption></figure>

## Test and set as default

* **Test integration** (bottom of the form) connects and runs a short check — see [Test an integration](/codemash/cloud/integrations/test.md). The badge becomes **TESTED**.
* **Actions** → **Set as default** makes it the database of record calls that name no integration — see [Set as default](/codemash/cloud/integrations/set-default.md). The first integration of an environment is the default.
* **Reveal connection string** on a Flex integration's page shows the generated string when you need direct access; it needs `database:manage` and is never offered to AI tools.

Atlas Flex keeps one database per environment, named `<env>_<integrationId>` (for example `prod_int_7pW2sKvB9qLm3XcT1yRfGh`). Promoting an environment gives the target its own new, empty Flex database. Only PROD copies count against your plan's Flex limit.

## Common errors

| Message                                             | Cause                                                                                          | Fix                                                                                                    |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Test failed** on the first check                  | The Atlas IP access list does not allow Norbix, or the user / password in the string is wrong. | Allow the Norbix IPs in Atlas **Network Access**; check the user; paste the string again and **Save**. |
| *Cluster provisioning failed*                       | Atlas could not create the Flex cluster.                                                       | Try again, or contact support.                                                                         |
| `CM-ERRORS-DATABASE-026` / `CM-ERRORS-DATABASE-027` | A new PROD Flex database would pass the plan's Flex limit (trial / paid plan).                 | Delete an unused Flex integration, or upgrade the plan.                                                |
| `CM-ERRORS-DATABASE-038`                            | This environment's copy has no saved connection string (after a promotion).                    | Open the integration in that environment and save its connection string.                               |

## Do it from code

```ts
const { id } = await norbix.hub.database.saveDatabaseIntegration({
  integration: {
    provider: 'MongoDbConnectionString',
    integrationName: 'Analytics copy',
    connectionString: 'mongodb://mongo:27017', // a real one: mongodb+srv://user:password@cluster0.example.mongodb.net
    databaseName: 'analytics',
    isEnabled: true,
  },
});
```

```sh
norbix hub database integration test --integrationId int_16tRKvLqwNnK1sPWkSkNUV
```

Avoid putting a connection string on a command line: it stays in the shell history. API: [Save Database Integration](/codemash/api-reference/database/integrations/save-database-integration.md) · [Test Database Integration](/codemash/api-reference/database/integrations/test-database-integration.md) · [Reveal Managed Flex Connection String](/codemash/api-reference/database/integrations/reveal-managed-flex-connection-string.md)