84 lines
3.2 KiB
Markdown
84 lines
3.2 KiB
Markdown
---
|
|
title: "Database — Overview & Adapter Selection"
|
|
aliases: [payload-database, payload-db-overview, payload-database-adapters]
|
|
tags: [payloadcms, database, mongodb, postgres, sqlite, drizzle, mongoose]
|
|
sources: [raw/database__overview.md]
|
|
created: 2026-05-15
|
|
updated: 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`:
|
|
|
|
```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|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
|
|
|
|
- [[wiki/payloadcms/database-migrations|Database Migrations]] — Drizzle migration CLI, push vs migrate, CI wiring
|
|
- [[wiki/payloadcms/database-mongodb|Database — MongoDB]] — full Mongoose adapter options, DocumentDB/CosmosDB compatibility
|
|
- [[wiki/payloadcms/database-indexes|Database Indexes]] — single-field, compound, unique index gotchas
|
|
- [[wiki/payloadcms/configuration|Payload Config — Overview]] — where `db` property lives in `buildConfig`
|
|
- [[wiki/payloadcms/localization|Localization]] — how localization affects storage model choice
|
|
|
|
## Sources
|
|
|
|
- `raw/database__overview.md` — https://payloadcms.com/docs/database/overview
|