|
| 1 | +# MongoDB Atlas |
| 2 | + |
| 3 | +[Atlas](https://www.mongodb.com/atlas) is MongoDB's hosted service. The |
| 4 | +engine's MongoDB destination reaches it over an ordinary connection string, |
| 5 | +so this guide is about the choices Atlas puts in front of you: the cluster |
| 6 | +tier, the database user's role, the IP access list, and which of its |
| 7 | +connection strings to copy. |
| 8 | + |
| 9 | +## Create the cluster |
| 10 | + |
| 11 | +Create a cluster in a project set aside for the mirror, or in the project |
| 12 | +your application already uses: the engine creates its own `workos` |
| 13 | +database and touches nothing else. |
| 14 | + |
| 15 | +| Tier | Suits | |
| 16 | +| -------------------------- | ---------------------------------------------------------------------------------------------------------------- | |
| 17 | +| **Free** (M0) | Evaluating the sync. 512 MB, shared CPU, 500 connections, no backups. Atlas pauses it after a long idle stretch. | |
| 18 | +| **Flex** | A small mirror with a usage-based bill. | |
| 19 | +| **Dedicated** (M10 and up) | A production mirror: backups, metrics, private networking. | |
| 20 | + |
| 21 | +Any tier runs MongoDB 8.0, well past the 5.0 the package needs. When the |
| 22 | +template form offers **Automate security setup**, leave it on: it creates a |
| 23 | +database user and adds your current address to the IP access list, the two |
| 24 | +things the next sections are about. Turn **Preload sample dataset** off on |
| 25 | +a free cluster, where the sample data would take most of the 512 MB. |
| 26 | +Provisioning takes a few minutes, during which the driver reports a |
| 27 | +server-selection timeout. |
| 28 | + |
| 29 | +## Database user |
| 30 | + |
| 31 | +Atlas authenticates with SCRAM users that live in the project, under |
| 32 | +**Database Access**. The sync's user needs `readWrite` on the mirror's |
| 33 | +database: that covers creating the collections, indexes and views, |
| 34 | +writing to them, and dropping the staging collection `reconcile` builds. |
| 35 | +Add `dbAdmin` on the same database if you will run `init --repair`, which |
| 36 | +rewrites a view with `collMod`. The automated setup creates a user with |
| 37 | +the **Atlas admin** role, which is more than the sync needs and fine for an |
| 38 | +evaluation; for production, give a dedicated user the two roles on the one |
| 39 | +database. |
| 40 | + |
| 41 | +The password is shown once. If it is gone, **Database Access → Edit → Edit |
| 42 | +Password → Autogenerate Secure Password → Update User** issues a new one |
| 43 | +and takes a few seconds to deploy. |
| 44 | + |
| 45 | +## Network access |
| 46 | + |
| 47 | +Atlas refuses every address not on the project's **Network Access** list, |
| 48 | +and a refused address looks like a connection timeout, not an error about |
| 49 | +access. Add the address the sync connects from before the first `init`, and |
| 50 | +again when it moves. A host with a changing address on a dedicated tier is |
| 51 | +better served by a private endpoint or VPC peering than by opening the |
| 52 | +list to everything. |
| 53 | + |
| 54 | +## Choose a connection |
| 55 | + |
| 56 | +**Connect → Drivers** shows the connection string: |
| 57 | + |
| 58 | +``` |
| 59 | +mongodb+srv://USER:PASSWORD@CLUSTER.xxxxx.mongodb.net/ |
| 60 | +``` |
| 61 | + |
| 62 | +The `mongodb+srv://` form is a DNS seed list: the driver looks up the |
| 63 | +replica set's hosts and options from DNS and connects to them on port 27017. Where DNS SRV lookups are not possible, the dialog's **Legacy URI |
| 64 | +string** toggle shows the equivalent `mongodb://host1,host2,host3/...` |
| 65 | +form with the hosts and `replicaSet` spelled out; the engine takes either. |
| 66 | +Put the database user's password in (percent-encoded if it has characters |
| 67 | +that mean something in a URL). |
| 68 | + |
| 69 | +The mirror lives in the database the string names, or `workos` when it |
| 70 | +names none; `WORKOS_SYNC_DATABASE` or `--database` overrides both. |
| 71 | + |
| 72 | +## TLS |
| 73 | + |
| 74 | +Atlas requires TLS, and `mongodb+srv://` turns it on. Atlas's certificates |
| 75 | +chain to public roots Node already trusts, so `WORKOS_SYNC_MONGODB_TLS_CA` |
| 76 | +stays unset and there is no `sslCa` to pass in embedded code. |
| 77 | + |
| 78 | +## Verify the endpoint |
| 79 | + |
| 80 | +From a checkout of this repository, after `pnpm install` and `pnpm build`: |
| 81 | + |
| 82 | +```sh |
| 83 | +TEST_MONGODB_URL='mongodb+srv://USER:PASSWORD@CLUSTER.xxxxx.mongodb.net/' \ |
| 84 | + pnpm --filter @workos/sync-mongodb test |
| 85 | +``` |
| 86 | + |
| 87 | +With that variable set, the suite runs against your cluster instead of the |
| 88 | +embedded `mongod` it otherwise starts. Each test creates a |
| 89 | +`workos_test_<hex>` database and drops it afterwards, which is why the |
| 90 | +user running the suite needs Atlas admin (or `dropDatabase` on every |
| 91 | +database); the sync itself does not. WorkOS responses are local fixtures, |
| 92 | +so no key is involved. |
| 93 | + |
| 94 | +Against a free M0 cluster in November 2026 the suite passed except for two |
| 95 | +tests that assume a server a millisecond away: a lease test that stalls a |
| 96 | +tick for 400 ms under a 150 ms lease, and a health test that stops |
| 97 | +`listen()` 50 ms after starting it and expects a completed tick. Both are |
| 98 | +timing assumptions in the tests rather than anything Atlas does. |
| 99 | + |
| 100 | +## Run the sync from your own host |
| 101 | + |
| 102 | +```sh |
| 103 | +export DATABASE_URL='mongodb+srv://USER:PASSWORD@CLUSTER.xxxxx.mongodb.net/' |
| 104 | +export WORKOS_API_KEY=sk_... |
| 105 | + |
| 106 | +npx workos-sync-mongodb init |
| 107 | +npx workos-sync-mongodb backfill |
| 108 | +npx workos-sync-mongodb listen |
| 109 | +``` |
| 110 | + |
| 111 | +The [container image](../../README.md#against-a-real-environment) and the |
| 112 | +[library](../getting-started.md#embed-it) take the same URL. Two things |
| 113 | +to plan for: |
| 114 | + |
| 115 | +- **A free cluster must stay in use.** Atlas pauses an M0 that has had no |
| 116 | + connections for a long stretch and resumes it from the console. A |
| 117 | + running `listen` never leaves that gap; a `tick` on a schedule does not |
| 118 | + either, as long as it keeps running. |
| 119 | +- **The IP access list must include the sync's host**, as above; a |
| 120 | + deployment that moves between addresses needs each of them listed, or a |
| 121 | + private endpoint. |
| 122 | + |
| 123 | +## Query it |
| 124 | + |
| 125 | +Everything in [Querying the mirror](../queries.md) applies, in |
| 126 | +MongoDB's terms: the collections are `workos_users`, `workos_organizations` |
| 127 | +and so on, each with a `workos_<name>_live` view that hides tombstones, and |
| 128 | +the payload is under `_raw`. **Browse collections** in the console opens |
| 129 | +Data Explorer on the `workos` database, and `mongosh` and Compass take the |
| 130 | +same connection string: |
| 131 | + |
| 132 | +```js |
| 133 | +db.workos_users_live.find({ _env: "production" }, { "_raw.email": 1 }); |
| 134 | +``` |
| 135 | + |
| 136 | +The [`@workos/sync-mongodb` README](../../packages/sync-mongodb/README.md#querying-the-mirror) |
| 137 | +has the `$lookup` that joins memberships to users and organizations, and |
| 138 | +the indexes the engine creates for it. |
0 commit comments