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