[Workers] Add MongoDB integration docs by MattieTK · Pull Request #31382 · cloudflare/cloudflare-docs

MattieTK · 2026-06-10T23:46:31Z

Summary

Adds documentation for connecting Cloudflare Workers to MongoDB using the native Node.js driver (mongodb >= 6.15.0) and Mongoose. We occasionally get requests in discord for information on how to do this since we don't support these drivers in Hyperdrive, and setting up database connections on a request-basis is inefficient.

Three changes:

New integration page at /workers/databases/third-party-integrations/mongodb/ – covers both a direct connection (simple, ~300ms overhead per request) and a Durable Object approach (recommended, persists connections for ~35ms warm queries). Also documents the Mongoose package.json exports patch required for workerd compatibility.
Table row added to /workers/databases/connecting-to-databases/ under the serverless databases section, listing MongoDB with the mongodb/mongoose drivers and TCP Socket as the connection method.
New tutorial at /workers/tutorials/connect-to-mongodb-atlas/ – a step-by-step guide that creates a Worker, connects to MongoDB, queries a sample collection, then upgrades to a Durable Object for lower latency.

Relevant upstream context:

cloudflare/workerd#3315 – added node:net
cloudflare/workerd#3594 – added node:tls TLSSocket
Automattic/mongoose#14613 – Mongoose exports map issue

Documentation checklist

Is there a changelog entry (guidelines)? If you don't add one for something awesome and new (however small) — how will our customers find out? Changelogs are automatically posted to RSS feeds, the Discord, and X.
The change adheres to the documentation style guide.
If a larger change - such as adding a new page- an issue has been opened in relation to any incorrect or out of date information that this PR fixes.

github-actions · 2026-06-10T23:47:14Z

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
`/src/content/docs/workers/`	`@cloudflare/workers-docs`, `@GregBrimble`, `@irvinebroque`, `@mikenomitch`, `@korinne`, `@WalshyDev`, `@cloudflare/deploy-config`, `@cloudflare/product-owners`, `@cloudflare/wrangler`, `@MattieTK`, `@cloudflare/dev-plat-leads`, `@vy-ton`

ask-bonk

3 issues need fixing before merge.

HIGH — Workers TypeScript examples must use TypeScriptExample (not bare ts/typescript fences). I suggested the most prominent blocks; please apply the same wrapper to any remaining examples on both pages.

HIGH — WranglerConfig blocks must use TOML input and $today for compatibility_date instead of JSONC/hardcoded dates.

MEDIUM — The tutorial output block should use txt output rather than sh output.

ask-bonk · 2026-06-11T00:00:31Z

Review posted on PR #31382.

Labels applied: product:workers, content:new, documentation.

Summary of findings:

Severity	Issue	Location
HIGH	Workers TypeScript examples use bare `ts`/`typescript` fences instead of the required `TypeScriptExample` component.	`mongodb.mdx` (3 blocks), tutorial (3 blocks)
HIGH	`WranglerConfig` blocks use JSONC input and hardcoded `compatibility_date` instead of TOML + `$today`.	`mongodb.mdx`, tutorial
MEDIUM	Command output block uses `sh output` instead of `txt output`.	Tutorial step 4

I posted 11 inline suggestions covering the import additions, representative TypeScriptExample wrappers, both WranglerConfig conversions, and the output language fix. The author should apply the same TypeScriptExample wrapper to any smaller typescript snippets I didn't individually flag (e.g., the step 5 import snippets in the tutorial).

No pre-existing issues in unchanged files were flagged. The content is technically accurate and the structure is solid once the component/style-guide violations are resolved.

github run

github-actions · 2026-06-11T00:33:33Z

Preview URL: https://102e695c.preview.developers.cloudflare.com
Preview Branch URL: https://feat-mongodb-docs.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/workers/tutorials/connect-to-mongodb-atlas/	https://feat-mongodb-docs.preview.developers.cloudflare.com/workers/tutorials/connect-to-mongodb-atlas/
https://developers.cloudflare.com/workers/databases/third-party-integrations/mongodb/	https://feat-mongodb-docs.preview.developers.cloudflare.com/workers/databases/third-party-integrations/mongodb/
https://developers.cloudflare.com/workers/databases/connecting-to-databases/	https://feat-mongodb-docs.preview.developers.cloudflare.com/workers/databases/connecting-to-databases/

…ngodb.mdx Co-authored-by: ask-bonk[bot] <249159057+ask-bonk[bot]@users.noreply.github.com>

Co-authored-by: ask-bonk[bot] <249159057+ask-bonk[bot]@users.noreply.github.com>

…ngodb.mdx Co-authored-by: ask-bonk[bot] <249159057+ask-bonk[bot]@users.noreply.github.com>

Co-authored-by: ask-bonk[bot] <249159057+ask-bonk[bot]@users.noreply.github.com>

Close TypeScriptExample and WranglerConfig blocks that were missing fence/tag terminators, and fill in the empty example blocks in the MongoDB integration page and Atlas tutorial.

cloudflare-docs-bot · 2026-06-23T10:57:11Z

Review

🚨 2 critical, ⚠️ 9 warnings, 💡 3 suggestions found in commit 102e695.

Code Review

This code review is in beta and may not always be helpful — use your judgment.

Critical (2)

File	Issue
`workers/databases/third-party-integrations/mongodb.mdx` line 242	Missing import for DurableObjectState — The Mongoose example's constructor declares `state: DurableObjectState`, but it only imports `{ DurableObject }` from "cloudflare:workers" (line 227). The `DurableObjectState` type is not in scope, so the snippet will not compile. Fix: Import `DurableObjectState` alongside `DurableObject` from "cloudflare:workers".
`workers/databases/third-party-integrations/mongodb.mdx` line 244	Repeated mongoose.model registration in constructor — `mongoose.model("Movie", movieSchema, "movies")` is called every time the Durable Object is constructed. Mongoose throws `OverwriteModelError` when a model with the same name is registered more than once in the same isolate, which will happen as Durable Object instances are created/evicted within a Worker isolate. Fix: Define the model once at module scope (e.g. `const Movie = mongoose.model("Movie", movieSchema, "movies")`) and assign `this.Movie = Movie` in the constructor, or guard registration with `mongoose.models["Movie"] ?? mongoose.model(...)`.

Warnings (2)

File	Issue
`workers/tutorials/connect-to-mongodb-atlas.mdx` line 141	MongoClient leaked per request — The simple Worker example creates a new `MongoClient` and connects it on every request, but the client is never closed or disposed before the handler returns. Fix: Wrap the connection logic in a `try`/`finally` and call `await client.close()` before returning, or switch to a single client reused for the isolate lifetime.
`workers/databases/third-party-integrations/mongodb.mdx` line 64	Unclosed MongoClient connection — The direct-connection example creates a new `MongoClient` and opens a connection, then returns the response without ever calling `client.close()`, leaking a TCP/TLS connection for each Worker invocation. Fix: Wrap the query logic in a `try/finally` block and call `await client.close()` in the `finally` to ensure the connection is cleaned up.

Style Guide Review

Warnings (7)

File	Issue
`workers/tutorials/connect-to-mongodb-atlas.mdx` line 92	Use for package manager commands — Bare ```sh code block contains `npx wrangler secret put MONGODB_URI` Fix: Use `` instead of a bare code fence
`workers/tutorials/connect-to-mongodb-atlas.mdx` line 269	Use for package manager commands — Bare ```sh code block contains `npx wrangler deploy` Fix: Use `` instead of a bare code fence
`workers/tutorials/connect-to-mongodb-atlas.mdx` line 284	Internal links must include trailing slash — Links `(/workers/tutorials)` and `(/workers/databases)` are missing trailing slashes Fix: Change to `(/workers/tutorials/)` and `(/workers/databases/`)
`workers/databases/third-party-integrations/mongodb.mdx` line 22	No directional words — Admonition uses 'as shown below' Fix: Replace 'as shown below' with a direct reference to the Durable Object example.
`workers/databases/third-party-integrations/mongodb.mdx` line 226	Pass Expressive Code options via TypeScriptExample props — Inner ```ts fence has title="src/MongoDBConnection.ts" inside Fix: Remove the inner fence title; the filename is already set on the component prop.
`workers/databases/third-party-integrations/mongodb.mdx` line 159	Use TypeScriptExample for Workers-style code — Bare ```ts block exports a default Worker fetch handler Fix: Wrap the block in .
`workers/databases/third-party-integrations/mongodb.mdx` line 205	Use PackageManagers for npx commands — Fenced block contains only 'npx wrangler deploy' Fix: Replace with .

Suggestions (3)

File	Issue
`workers/tutorials/connect-to-mongodb-atlas.mdx` line 124	Avoid `navigate to` phrasing — Line uses `navigate to your cluster` Fix: Change to `go to your cluster`
`workers/databases/third-party-integrations/mongodb.mdx` line 27	Tabs primary answer first — First tab is 'Direct connection (simple)' while the second tab is 'Durable Object (recommended)' Fix: Place the recommended Durable Object tab first.
`workers/databases/third-party-integrations/mongodb.mdx` line 264	Standard link phrasing — Next-step bullet uses 'Learn more about Durable Objects' Fix: Change to 'For more information, refer to Durable Objects.'

Commands

Only codeowners can run commands. Post a comment with the command to trigger it.

Command	Description
`/review`	Runs a review now. Incremental if a prior review exists, full if not.
`/full-review`	Re-reviews the entire PR diff from scratch, ignoring incremental history. Useful after a rebase, when you want a fresh review, or if the bot gets out of sync and reports issues that no longer exist.
`/ignore-review-limit`	Permanently lifts the 2-review automatic limit for this PR. Future pushes will trigger reviews as normal.

[Workers] Add MongoDB integration docs

c889281

github-actions Bot added product:workers Related to Workers product size/l labels Jun 10, 2026

github-actions Bot assigned GregBrimble, irvinebroque, korinne, mikenomitch, vy-ton and WalshyDev Jun 10, 2026

ask-bonk Bot added content:new Request for new/missing content documentation Documentation edits labels Jun 10, 2026

ask-bonk Bot reviewed Jun 11, 2026

View reviewed changes

MattieTK and others added 8 commits June 11, 2026 13:38

Update

ec59b13

Update src/content/docs/workers/databases/third-party-integrations/mo…

0fe4721

…ngodb.mdx Co-authored-by: ask-bonk[bot] <249159057+ask-bonk[bot]@users.noreply.github.com>

Update src/content/docs/workers/databases/third-party-integrations/mo…

c9983b2

…ngodb.mdx Co-authored-by: ask-bonk[bot] <249159057+ask-bonk[bot]@users.noreply.github.com>

Update src/content/docs/workers/databases/third-party-integrations/mo…

a486973

…ngodb.mdx Co-authored-by: ask-bonk[bot] <249159057+ask-bonk[bot]@users.noreply.github.com>

Update src/content/docs/workers/tutorials/connect-to-mongodb-atlas.mdx

fa9cfde

Co-authored-by: ask-bonk[bot] <249159057+ask-bonk[bot]@users.noreply.github.com>

Update src/content/docs/workers/databases/third-party-integrations/mo…

c357d3e

…ngodb.mdx Co-authored-by: ask-bonk[bot] <249159057+ask-bonk[bot]@users.noreply.github.com>

Apply suggestions from code review

8ca8e4a

Co-authored-by: ask-bonk[bot] <249159057+ask-bonk[bot]@users.noreply.github.com>

[Workers] Fix unclosed MDX tags in MongoDB docs

102e695

Close TypeScriptExample and WranglerConfig blocks that were missing fence/tag terminators, and fill in the empty example blocks in the MongoDB integration page and Atlas tutorial.

MattieTK marked this pull request as ready for review June 23, 2026 10:57

MattieTK requested review from a team, GregBrimble, WalshyDev, irvinebroque, korinne and vy-ton as code owners June 23, 2026 10:57

MattieTK requested review from a team as code owners June 23, 2026 10:57

MattieTK requested a review from penalosa June 23, 2026 10:57

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[Workers] Add MongoDB integration docs#31382

[Workers] Add MongoDB integration docs#31382
MattieTK wants to merge 9 commits into
productionfrom
feat/mongodb-docs

MattieTK commented Jun 10, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 10, 2026

Uh oh!

ask-bonk Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ask-bonk Bot commented Jun 11, 2026

Uh oh!

github-actions Bot commented Jun 11, 2026 •

edited

Loading

Uh oh!

cloudflare-docs-bot Bot commented Jun 23, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Uh oh!

Conversation

MattieTK commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Documentation checklist

Uh oh!

github-actions Bot commented Jun 10, 2026

Uh oh!

ask-bonk Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ask-bonk Bot commented Jun 11, 2026

Uh oh!

github-actions Bot commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cloudflare-docs-bot Bot commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review

Code Review

Style Guide Review

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

MattieTK commented Jun 10, 2026 •

edited

Loading

github-actions Bot commented Jun 11, 2026 •

edited

Loading

cloudflare-docs-bot Bot commented Jun 23, 2026 •

edited

Loading