Document database

MongoDB Atlas integration

Ahena works with one MongoDB Atlas project through the Atlas Administration API: it checks the cluster your app uses is running and sized as declared, keeps database users and the project IP access list in line with ahena.config.ts, creates a free M0 cluster (or, with explicit approval, a billed dedicated one), and generates a database module on the official mongodb driver. Your app connects to Atlas directly. Ahena is never in the query path.

BetaFull MongoDB Atlas docs

What Ahena inspects

Read-only: inspecting and Doctor never change anything at MongoDB Atlas.

Clusters: tier, cloud provider and region, state, whether paused, MongoDB version and cloud backup, including Flex clusters.
Database users with their auth database, roles and cluster scopes. Never passwords.
The project IP access list, flagging 0.0.0.0/0.
Each cluster's SRV hostname, never a user or password.
The service account's own project and organization roles.

What Ahena configures

You declare what you want in ahena.config.ts; ahena plan shows each change with its classification before anything is applied.

Change	Classification	Notes
Create a free M0 cluster	CONFIRMATION_REQUIRED	One free cluster per project. Ahena polls until it's IDLE, then re-reads it.
Create a dedicated cluster (M10 and up)	BILLABLE	Billed hourly from creation; the plan shows a cost notice.
Resize a dedicated cluster	BILLABLE	Only an IDLE, unpaused cluster without compute auto-scaling.
Create a database user	CONFIRMATION_REQUIRED	Ahena generates the password and stores it only inside `MONGODB_URI`, encrypted.
Set a user's roles	CONFIRMATION_REQUIRED	Only for users whose roles are listed in the config.
Add an IP access list entry	CONFIRMATION_REQUIRED	An IPv4 address or canonical CIDR block.

Refused outright:

0.0.0.0/0 or any access list entry broader than /8.
Deleting or pausing clusters, deleting users or removing access list entries.
Creating Flex (or M2/M5) clusters, or changing a free or Flex cluster's tier.

Generated code: src/ahena/database/index.ts: one cached MongoClient from MONGODB_URI, with database.db(), database.collection() and database.ping().

How Ahena verifies

After every write, Ahena reads MongoDB Atlas back. Each change ends in one of these states, and the plan's outcome says why:

VERIFIED: Ahena read the provider back and saw the desired state. The CLI shows ✓ only for VERIFIED.
APPLIED_UNVERIFIED: The provider accepted the change, but the re-read doesn't show it yet (after bounded polling), or the re-read failed.

Every create first re-reads Atlas and only creates what's absent, so a retry never duplicates a cluster, user or entry. After applying, Ahena plans again and reads back each user's existence and roles, the access list and the cluster's tier. Passwords are write-only in Atlas, so they're never read back.

If a request may have reached MongoDB Atlas but the answer was lost, Ahena re-reads before deciding: done, safe to retry, or “check before retrying”.

What Doctor diagnoses

Key checks from ahena doctor. Each finding says why it matters, where, the impact and whether Ahena can fix it. The full list is in the MongoDB Atlas docs.

Check	What it means
`mongodb-atlas.credential`	The service account can get a token and call the API, including its API access list.
`mongodb-atlas.cluster`	The declared cluster exists, is IDLE and isn't paused (paused fails in production).
`mongodb-atlas.cluster.tier`	Production runs on a free or Flex cluster.
`mongodb-atlas.cluster.backup`	Cloud backup is off on a production dedicated cluster.
`mongodb-atlas.users.<username>`	The user exists with the configured roles.
`mongodb-atlas.access-list.open`	`0.0.0.0/0` is on the access list (fails in production).

More on findings, health and continuous checks: Doctor.

Approvals

MongoDB Atlas changes here are classified CONFIRMATION_REQUIRED and BILLABLE. Every change is planned and shown as a diff first. Ahena itself enforces who can approve it:

SAFE changes are applied without asking.
In production, every other change needs approval in the Ahena dashboard, signed in, by an admin.
In other environments, CONFIRMATION_REQUIRED changes are approved in the CLI; BILLABLE and DESTRUCTIVE changes always need the dashboard.
MANUAL steps are never applied by Ahena.

--yes and --allow-billable don't replace a dashboard approval. See approvals for how it works and why the browser.

Manual steps

These are MANUAL: Ahena never does them. It lists them with the exact steps when they apply.

Create the service account and add it to the project with the roles Ahena needs.
If your organization requires an API access list, add the address Ahena reports to the service account.
Remove 0.0.0.0/0 from the access list once your app's addresses are listed.
Turn on cloud backup for production dedicated clusters, and resume paused clusters, in Atlas.

Credentials and permissions

Name	Secret	Notes
`MONGODB_ATLAS_CLIENT_ID`	Yes	The service account's client ID (`mdb_sa_id_…`).
`MONGODB_ATLAS_CLIENT_SECRET`	Yes	The service account's client secret, shown once by Atlas.
`MONGODB_ATLAS_PROJECT_ID`	No	The Atlas project ID; Ahena lists the projects it can see if it's missing.
`MONGODB_URI`	Yes	Created by Ahena with the database user and stored encrypted in that environment.

Least privilege

Project Read Only for Doctor, inspect and plans; add Project Database Access Admin, Project Network Access Manager, Project Cluster Creator or Project Cluster Manager only for what Ahena should change.
Ahena reads the service account's own roles when connecting and reports each permission as granted, missing or unknown.

Each credential Ahena stores gets its own key and is envelope-encrypted, bound to the environment. See security.

Workflow example

Connect, check, plan, then apply. Placeholders (…) stand for your own values.

MONGODB_ATLAS_CLIENT_ID=… MONGODB_ATLAS_CLIENT_SECRET=… ahena connect mongodb-atlas -e production --set MONGODB_ATLAS_PROJECT_ID=…

Connect a service account to production.

```
ahena doctor -e production
```
Check the cluster, users, roles and the access list.
```
ahena plan -e production
```
See the user, access list and cluster changes.
```
ahena apply -e production
```
Approve, then Ahena applies and reads each change back.

ahena generate mongodb-atlas -e production

Write the database module.

Verification status

Beta

Available in beta. Every capability is validated by Ahena's automated provider contract and conformance tests; verification against the real service is next.

How MongoDB Atlas is tested

Tested against an in-memory simulation of the Atlas Administration API v2 and its OAuth token endpoint, built from MongoDB's published OpenAPI spec: versioned media types, pagination, error codes, project-role enforcement and the service account API access list.
Not yet verified against the real service. The live test creates only database users and documentation-range access list entries (plus a free M0 cluster when asked) in a project named ahena-test-…, never a paid cluster.
The generated database module is typechecked against the mongodb driver.

The providers overview explains Ahena's testing methodology and what has been verified for every provider.

Limitations

Service accounts only; legacy API keys aren't supported.
Existing users' passwords are never read or rotated, and nothing is deleted.
IPv6 entries, private endpoints, VPC peering, custom roles, non-SCRAM users, backups and alerts aren't managed.

Disconnecting

ahena disconnect mongodb-atlas removes the stored credentials (delete the service account or its secret in Atlas); clusters, users and the access list are untouched.