| title |
aliases |
tags |
sources |
created |
updated |
| Database — Overview & Adapter Selection |
| payload-database |
| payload-db-overview |
| payload-database-adapters |
|
| payloadcms |
| database |
| mongodb |
| postgres |
| sqlite |
| drizzle |
| mongoose |
|
| raw/database__overview.md |
|
2026-05-15 |
2026-05-15 |
Overview
Payload is database agnostic — it communicates through a Database Adapter, a thin translation layer between Payload's internal structures and the native DB format.
Official Adapters
| Adapter |
Package |
ORM |
| MongoDB |
@payloadcms/db-mongodb |
Mongoose |
| Postgres |
@payloadcms/db-postgres |
Drizzle |
| SQLite |
@payloadcms/db-sqlite |
Drizzle |
Each adapter is an external dependency — install separately from Payload core.
Configuration
Set the db property in payload.config.ts:
import { buildConfig } from 'payload'
import { mongooseAdapter } from '@payloadcms/db-mongodb'
export default buildConfig({
db: mongooseAdapter({
url: process.env.DATABASE_URL,
}),
})
Choosing a Database
MongoDB — prefer when:
- Many dynamic fields (arrays, blocks, hasMany selects)
- Heavy localization (all locales stored in one document)
- You want to avoid DDL migration management
- Prefer schema simplicity over strict enforcement
Postgres / SQLite — prefer when:
- Data shape is flat and stable
- Need enforced referential integrity at DB level
- Comfortable with wiki/payloadcms/database-migrations workflow
- Many relationships between collections
SQLite note
- Same as Postgres (Drizzle) except Point Field not yet supported
- Good for local dev or embedded deployments
Data Storage Model Difference
|
MongoDB |
Postgres/SQLite |
| Arrays/Blocks |
Embedded in one document |
Normalized into join tables |
| Localization |
All locales in one document |
Separate locale columns/rows |
| Migrations |
None (schema-free) |
Required for schema changes |
Key Takeaways
- Payload doesn't dictate your DB — adapter pattern means any DB is theoretically supportable
- MongoDB stores each Payload document as a single DB document — minimal complexity for dynamic schemas
- Postgres/SQLite enforce schema at DB level — use when data consistency is critical
- All major Payload features (localization, arrays, blocks) work across all official adapters
- SQLite is Drizzle-based like Postgres — same migration workflow, missing Point Field only
- Adapter is installed separately:
npm install @payloadcms/db-mongodb (or postgres/sqlite variant)
Related
Sources
