<!-- llms.txt: https://workos.com/llms.txt -->
<!-- feedback.md: https://workos.com/docs/feedback.md -->

# MongoDB Atlas

## Introduction

[MongoDB Atlas](https://www.mongodb.com/atlas) is MongoDB's hosted database service. The sync engine uses the `@workos/sync-mongodb` destination to mirror WorkOS objects into collections you can query alongside your application data.

The [MongoDB Atlas integration guide](https://github.com/workos/sync-engine/blob/main/docs/integrations/mongodb-atlas.md) in the sync engine repository covers cluster selection, database users, network access, connection strings, TLS, and deployment.

## Prepare the cluster

Give the sync's database user `readWrite` on the mirror's database. Add `dbAdmin` on that database only if you need `init --repair`. The sync does not need the broader Atlas admin role; see [Database user](https://github.com/workos/sync-engine/blob/main/docs/integrations/mongodb-atlas.md#database-user) for details.

Allow the sync host through Atlas's network access controls before connecting. See [Network access](https://github.com/workos/sync-engine/blob/main/docs/integrations/mongodb-atlas.md#network-access) for IP access lists and private networking considerations.

## Run from your own host

Use the Atlas connection string as `DATABASE_URL`. The `mongodb+srv://` form enables TLS and discovers the cluster through DNS. The mirror defaults to the `workos` database when the connection string does not name one; see [Choose a connection](https://github.com/workos/sync-engine/blob/main/docs/integrations/mongodb-atlas.md#choose-a-connection) for connection formats and database selection.

Follow [Run the sync from your own host](https://github.com/workos/sync-engine/blob/main/docs/integrations/mongodb-atlas.md#run-the-sync-from-your-own-host) to initialize the mirror, backfill existing data, and start polling for changes. You can run the sync as a command, container, or library. The [`@workos/sync-mongodb` README](https://github.com/workos/sync-engine/blob/main/packages/sync-mongodb/README.md) is the reference for configuration and operations.

## Query the mirror

Collections such as `workos_users` keep the WorkOS payload under `_raw`. Their `workos_<name>_live` views exclude deleted objects. Use these views for current-state queries, and include `_env` when filtering or joining data from multiple WorkOS environments.

See [Query it](https://github.com/workos/sync-engine/blob/main/docs/integrations/mongodb-atlas.md#query-it) for Atlas Data Explorer, `mongosh`, and Compass, and the [package's query examples](https://github.com/workos/sync-engine/blob/main/packages/sync-mongodb/README.md#querying-the-mirror) for joins and indexes.
