obsidian/wiki/payloadcms/database-mongodb.md

title	aliases	tags	sources	created	updated
Database — MongoDB (Mongoose Adapter)	payload-mongodb mongoose-adapter payload-mongo	payloadcms mongodb mongoose database	raw/database__mongodb.md	2026-05-15	2026-05-15

Setup

Install and wire up @payloadcms/db-mongodb:

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:

// 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:

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:

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 — single-field and compound index config
• wiki/payloadcms/database-migrations — migration CLI, Postgres-focused but covers shared concepts
• wiki/payloadcms/configuration — root buildConfig where db is wired
• wiki/payloadcms/queries — where/sort/pagination options used against MongoDB
• wiki/payloadcms/localization — locale threading that feeds MongoDB collation

---

Sources

• raw/database__mongodb.md — compiled from payloadcms.com/docs/database/mongodb