130 lines
4.7 KiB
Markdown
130 lines
4.7 KiB
Markdown
---
|
|
title: "Database — MongoDB (Mongoose Adapter)"
|
|
aliases: [payload-mongodb, mongoose-adapter, payload-mongo]
|
|
tags: [payloadcms, mongodb, mongoose, database]
|
|
sources: [raw/database__mongodb.md]
|
|
created: 2026-05-15
|
|
updated: 2026-05-15
|
|
---
|
|
|
|
## Setup
|
|
|
|
Install and wire up `@payloadcms/db-mongodb`:
|
|
|
|
```ts
|
|
import { mongooseAdapter } from '@payloadcms/db-mongodb'
|
|
|
|
export default buildConfig({
|
|
db: mongooseAdapter({
|
|
url: process.env.DATABASE_URL, // required
|
|
}),
|
|
})
|
|
```
|
|
|
|
---
|
|
|
|
## Adapter Options
|
|
|
|
| Option | Default | Notes |
|
|
|--------|---------|-------|
|
|
| `url` | — | **Required.** MongoDB connection string |
|
|
| `autoPluralization` | — | Auto-pluralize singular collection slugs |
|
|
| `bulkOperationsSingleTransaction` | `false` | Process bulk ops one-at-a-time; fixes DocumentDB/Cosmos DB transaction limits |
|
|
| `connectOptions` | — | Override Mongoose connection options |
|
|
| `collectionsSchemaOptions` | — | Customize Mongoose schema per collection |
|
|
| `disableIndexHints` | `false` | Disable `id` index hint for pagination count; fixes AWS DocumentDB issues |
|
|
| `migrationDir` | — | Custom directory for migration files |
|
|
| `transactionOptions` | — | Configure or disable (`false`) transactions |
|
|
| `collation` | — | Language-specific string sorting (MongoDB 3.4+), locale auto-threaded from request |
|
|
| `allowAdditionalKeys` | `false` | Allow extra MongoDB fields not in Payload schema — **access control won't apply** |
|
|
| `allowIDOnCreate` | `false` | Use caller-supplied `id` on create without a custom ID field |
|
|
| `disableFallbackSort` | `false` | Disable fallback sort on non-unique fields (may break consistent ordering) |
|
|
| `useAlternativeDropDatabase` | `false` | Use `deleteMany({})` per collection instead of raw `dropDatabase` (testing only) |
|
|
| `useBigIntForNumberIDs` | `false` | Use `BigInt` for `'number'`-type custom IDs (for DBs that don't support double/int32) |
|
|
| `useJoinAggregations` | `true` | Use correlated subqueries for join fields; set `false` for multiple `find` fallback |
|
|
| `usePipelineInSortLookup` | `true` | Use `pipeline` in `$lookup` aggregation for sorting |
|
|
|
|
---
|
|
|
|
## Accessing Mongoose Models Directly
|
|
|
|
After `payload.init()`, models are exposed on the adapter:
|
|
|
|
```ts
|
|
// Collection model
|
|
payload.db.collections['posts']
|
|
|
|
// Globals model
|
|
payload.db.globals
|
|
|
|
// Versions (collections or globals)
|
|
payload.db.versions['posts']
|
|
```
|
|
|
|
---
|
|
|
|
## Alternative MongoDB Implementations
|
|
|
|
Import `compatibilityOptions` for pre-configured settings for DocumentDB, Cosmos DB, and Firestore:
|
|
|
|
```ts
|
|
import { mongooseAdapter, compatibilityOptions } from '@payloadcms/db-mongodb'
|
|
|
|
export default buildConfig({
|
|
db: mongooseAdapter({
|
|
url: process.env.DATABASE_URL,
|
|
...compatibilityOptions.firestore, // or .documentDB / .cosmosDB
|
|
}),
|
|
})
|
|
```
|
|
|
|
**Known limitations:**
|
|
- **Azure Cosmos DB** — does not support transactions across multiple collections (common in Payload hooks); requires `indexSortableFields: true` at root config
|
|
- DocumentDB and Firestore may still have issues despite compatibility presets
|
|
|
|
---
|
|
|
|
## Collation (Language-Aware Sorting)
|
|
|
|
Enable locale-sensitive string comparison:
|
|
|
|
```ts
|
|
db: mongooseAdapter({
|
|
url: process.env.DATABASE_URL,
|
|
collation: {
|
|
strength: 1, // case/accent insensitivity level
|
|
// locale is auto-set from request
|
|
},
|
|
})
|
|
```
|
|
|
|
- Affects sort order — test thoroughly before production
|
|
- Locale is threaded automatically from the request context
|
|
|
|
---
|
|
|
|
## Key Takeaways
|
|
|
|
- MongoDB adapter is the original Payload DB; install `@payloadcms/db-mongodb`
|
|
- `url` is the only required option; all others are opt-in overrides
|
|
- Direct Mongoose model access via `payload.db.collections[slug]` enables raw queries when needed
|
|
- `bulkOperationsSingleTransaction: true` + `disableIndexHints: true` for DocumentDB/Cosmos DB compatibility
|
|
- `allowAdditionalKeys: true` bypasses Payload's schema stripping **and access control** — use with care
|
|
- Azure Cosmos DB requires extra config (`indexSortableFields: true`, no cross-collection transactions)
|
|
- Collation enables proper multilingual sorting but must be tested before production rollout
|
|
|
|
---
|
|
|
|
## Related
|
|
|
|
- [[wiki/payloadcms/database-indexes|Database Indexes]] — single-field and compound index config
|
|
- [[wiki/payloadcms/database-migrations|Database Migrations]] — migration CLI, Postgres-focused but covers shared concepts
|
|
- [[wiki/payloadcms/configuration|Payload Config — Overview]] — root `buildConfig` where `db` is wired
|
|
- [[wiki/payloadcms/queries|Queries]] — where/sort/pagination options used against MongoDB
|
|
- [[wiki/payloadcms/localization|Localization]] — locale threading that feeds MongoDB collation
|
|
|
|
---
|
|
|
|
## Sources
|
|
|
|
- `raw/database__mongodb.md` — compiled from [payloadcms.com/docs/database/mongodb](https://payloadcms.com/docs/database/mongodb)
|