---
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)