Skip to content

Commit 172869a

Browse files
authored
docs: Add PlanetScale and MongoDB Atlas guides (#57)
1 parent a386a78 commit 172869a

4 files changed

Lines changed: 407 additions & 9 deletions

File tree

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,9 @@ ships with the package and so always describes the version you installed. The
120120

121121
Although any accessible database is supported, we also have guides for integrating with the following platforms:
122122

123-
- [Neon](integrations/neon.md)
123+
- [Neon](docs/integrations/neon.md)
124+
- [PlanetScale](docs/integrations/planetscale.md), Postgres and Vitess
125+
- [MongoDB Atlas](docs/integrations/mongodb-atlas.md)
124126

125127
## How it works
126128

‎docs/integrations/mongodb-atlas.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
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.
Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ postgresql://USER:PASSWORD@ep-<id>-pooler.<region>.aws.neon.tech/neondb?sslmode=
6464
Transaction pooling is enough because of how the engine uses the database:
6565
short transactions, transaction-scoped migration locks, row-based writer
6666
leases and temporary tables created `ON COMMIT DROP` inside a transaction.
67-
[Hosted Postgres](../docs/hosted-postgres.md#choose-a-connection) has the reasoning.
67+
[Hosted Postgres](../hosted-postgres.md#choose-a-connection) has the reasoning.
6868

6969
## TLS
7070

@@ -88,7 +88,7 @@ transactions, reconciliation, writer leases, checkpoints and tombstones
8888
against the real endpoint. WorkOS responses are local fixtures, so it makes
8989
no WorkOS calls and needs no key. Run it once for each URI you intend to use:
9090
it proves the credentials, network path, TLS and permissions that a local run
91-
cannot. [Hosted Postgres](../docs/hosted-postgres.md#verify-the-actual-endpoint) has
91+
cannot. [Hosted Postgres](../hosted-postgres.md#verify-the-actual-endpoint) has
9292
more on what it covers.
9393

9494
## Run the sync from your own host
@@ -104,8 +104,8 @@ npx workos-sync-postgres backfill
104104
npx workos-sync-postgres listen
105105
```
106106

107-
The [container image](../README.md#against-a-real-environment) and the
108-
[library](../docs/getting-started.md#embed-it) take the same URL. Two things about
107+
The [container image](../../README.md#against-a-real-environment) and the
108+
[library](../getting-started.md#embed-it) take the same URL. Two things about
109109
Neon's compute to plan for:
110110

111111
- **The compute stays awake while the sync runs.** Neon suspends an idle
@@ -216,7 +216,7 @@ curl -H "Authorization: Bearer $WORKOS_SYNC_STATUS_TOKEN" <invocation_url>/statu
216216

217217
- **There is no `listen`.** The mirror is kept current by a tick per minute,
218218
or within seconds of a change when the webhook nudges it. Every route is a
219-
bounded, resumable slice of the kind [Serverless hosts](../docs/serverless.md)
219+
bounded, resumable slice of the kind [Serverless hosts](../serverless.md)
220220
describes. `MAX_PAGES` and `MAX_EVENTS_PER_TICK` at the top of the module
221221
are the budgets, and each response reports `pages` so you can size them
222222
against the 15-minute limit.
@@ -250,7 +250,7 @@ curl -H "Authorization: Bearer $WORKOS_SYNC_STATUS_TOKEN" <invocation_url>/statu
250250
`directory_users` is the usual case, at four requests per second per
251251
directory. The `pages` field in each response shows a stream approaching
252252
the budget before it crosses it, and
253-
[Serverless hosts](../docs/serverless.md#a-stream-larger-than-the-slot)
253+
[Serverless hosts](../serverless.md#a-stream-larger-than-the-slot)
254254
has the same recipe for the CLI.
255255

256256
- **The function is branch-scoped.** Each branch that deploys it polls WorkOS
@@ -283,11 +283,11 @@ lease and the schema fingerprint. In practice:
283283
with nothing to re-run.
284284
- **Two branches syncing the same environment are two syncs on one key.**
285285
Each polls and backfills on its own; see
286-
[rate limits](../docs/operations.md#rate-limits) for the budget they share.
286+
[rate limits](../operations.md#rate-limits) for the budget they share.
287287

288288
## Query it
289289

290-
Everything in [Querying the mirror](../docs/queries.md) applies. Use the SQL editor
290+
Everything in [Querying the mirror](../queries.md) applies. Use the SQL editor
291291
in the Neon console, or open `psql` on the same URI:
292292

293293
```sh

0 commit comments

Comments
 (0)