# PayloadCMS Setup: PostgreSQL or FerretDB

> Set up PayloadCMS with managed PostgreSQL or MongoDB-compatible FerretDB on Layerbase Cloud, and why FerretDB beats MongoDB for most Payload projects.

Published: 2026-05-20
Canonical: https://layerbase.com/blog/payloadcms-database-setup

> **Choosing a hosted document database:** [Compare DocumentDB and FerretDB](/create/mongodb) for current availability and branching support. Standalone DocumentDB has its own gateway; FerretDB remains a separate engine. Engine-specific examples and migration instructions below apply only to the engine named.

Short version: use PostgreSQL with `@payloadcms/db-postgres` unless your data is genuinely document-shaped, in which case use FerretDB with the unmodified `@payloadcms/db-mongodb` adapter, because FerretDB speaks the MongoDB wire protocol and Payload cannot tell the difference. Either setup is the same three moves: create the database, put its connection string in `DATABASE_URL`, run `pnpm dev`. PostgreSQL runs on the Layerbase Cloud free tier with no card; FerretDB is not a free-tier engine and starts on the lowest paid plan. Keep SQLite for local development and small single-machine deployments, not for a production Payload install.

PayloadCMS supports three database backends: PostgreSQL, MongoDB (via its wire protocol), and SQLite. This post shows how to wire up the two production-ready options on [Layerbase Cloud](https://layerbase.com/cloud) in under five minutes each, and makes the case for picking FerretDB instead of a managed MongoDB when you want the document model.

## Contents

- [Which database should PayloadCMS use?](#which-database-should-payloadcms-use)
- [PayloadCMS with PostgreSQL](#payloadcms-with-postgresql)
- [PayloadCMS with FerretDB](#payloadcms-with-ferretdb)
- [Why we recommend FerretDB over MongoDB](#why-we-recommend-ferretdb-over-mongodb)
- [Local development with Layerbase Desktop](#local-development-with-layerbase-desktop)
- [FAQ](#faq)
- [Wrapping up](#wrapping-up)

## Which database should PayloadCMS use?

For most Payload projects, the answer is **PostgreSQL**. It handles relational data cleanly, the JSONB column type covers schema-flexible use cases when you need them, and the operational tooling around Postgres is unmatched (pg_dump, point-in-time recovery, every ORM and BI tool).

Pick **FerretDB** instead if:

- Your data is genuinely document-shaped (deeply nested, schema-flexible, query-by-pattern)
- Your team already knows MongoDB drivers and `mongosh`
- You want the Mongo developer experience without the SSPL licensing risk

Pick **SQLite** only for local development or very small single-machine deployments. It is not what you want behind a production Payload install.

The rest of this post covers Postgres and FerretDB. Postgres is available on the Layerbase Cloud free tier with no credit card. FerretDB is not a free-tier engine, so it starts on our lowest paid plan.

## PayloadCMS with PostgreSQL

### 1. Create the database

Visit [layerbase.com/create/postgresql](https://layerbase.com/create/postgresql), pick a name (e.g. `payload-prod`), and click **Sign in and create**. Provisioning takes about ten seconds. Copy the connection string from the dashboard; it looks like:

```text
postgresql://layerbase:<password>@your-host.cloud.layerbase.dev:5432/app?sslmode=require
```

### 2. Install the Payload adapter

```bash
pnpm add @payloadcms/db-postgres
```

### 3. Configure `payload.config.ts`

```ts
import { buildConfig } from 'payload'
import { postgresAdapter } from '@payloadcms/db-postgres'

export default buildConfig({
  db: postgresAdapter({
    pool: {
      connectionString: process.env.DATABASE_URL,
    },
  }),
  collections: [
    /* your collections */
  ],
})
```

Put the connection string in `.env`:

```text
DATABASE_URL=postgresql://layerbase:...@your-host.cloud.layerbase.dev:5432/app?sslmode=require
```

### 4. Run

```bash
pnpm payload generate:types
pnpm dev
```

Payload runs migrations on first boot. Done.

## PayloadCMS with FerretDB

FerretDB implements the MongoDB wire protocol on top of PostgreSQL. From Payload's perspective it **is** MongoDB, so you use the existing `@payloadcms/db-mongodb` adapter unchanged.

### 1. Create the database

Visit [layerbase.com/create/ferretdb](https://layerbase.com/create/ferretdb), name it, click **Sign in and create**. The dashboard will give you a Mongo-style connection string:

```text
mongodb://layerbase:<password>@your-host.cloud.layerbase.dev:27017/app?tls=true
```

### 2. Install the Mongo adapter

```bash
pnpm add @payloadcms/db-mongodb
```

The Mongo adapter, not a FerretDB-specific one. There is no FerretDB-specific adapter because the wire protocol is identical.

### 3. Configure `payload.config.ts`

```ts
import { buildConfig } from 'payload'
import { mongooseAdapter } from '@payloadcms/db-mongodb'

export default buildConfig({
  db: mongooseAdapter({
    url: process.env.DATABASE_URL,
  }),
  collections: [
    /* your collections */
  ],
})
```

And `.env`:

```text
DATABASE_URL=mongodb://layerbase:...@your-host.cloud.layerbase.dev:27017/app?tls=true
```

### 4. Run

```bash
pnpm dev
```

That is the entire integration. Payload talks to FerretDB the same way it talks to MongoDB.

## Why we recommend FerretDB over MongoDB

If you reach for "the document database," you are usually reaching for the developer experience: flexible schemas, expressive queries, the `mongosh` shell, the Node and Python drivers, the ecosystem. None of that requires MongoDB the product. FerretDB gives you all of it without the trade-offs that come with hosting real MongoDB.

### Licensing: Apache 2.0 instead of SSPL

MongoDB ships under the Server Side Public License (SSPL), which restricts how managed providers can offer it. That is why every "MongoDB-compatible" managed service that is not MongoDB Atlas itself has had to either license MongoDB directly from MongoDB Inc. or run a fork. FerretDB is Apache 2.0. You can host it, embed it, redistribute it, fork it, ship it inside an on-prem product. No license review required.

### Drop-in compatibility

Same wire protocol means the same drivers work:

- `mongoose`, `mongodb` Node.js drivers
- `pymongo`
- `mongo-go-driver`
- The Java, C#, Rust, and Ruby official drivers
- `mongosh` for ad-hoc queries
- Mongo Compass for browsing
- The Payload `@payloadcms/db-mongodb` adapter

You do not change a single line of application code to switch from MongoDB to FerretDB.

### A flat bill instead of a metered one

Atlas has since replaced its Serverless tier with Flex, which bills by an operations-per-second band and adds storage, backups, and egress on top; the dedicated M-tiers above it bill by the hour. Either way the number moves with what your app does, which is hard to forecast for a CMS whose traffic is lumpy. Layerbase Cloud charges a flat monthly fee per database plus optional add-ons (storage, always-on connections, larger plans), and the free tier covers small projects with no card. Atlas rates verified 2026-08-26 from [mongodb.com/pricing](https://www.mongodb.com/pricing).

### Backed by Postgres under the hood

FerretDB stores your documents as JSONB inside a PostgreSQL table. Practical benefits:

- ACID transactions handled by Postgres (not FerretDB-specific code)
- Backups via `pg_dump` and managed snapshots, not Mongo-specific tooling
- The full PostgreSQL extension ecosystem is available if you need it
- One database engine to learn for ops if your stack already includes Postgres

For 90% of document workloads (CRUD, indexes, core aggregation stages, transactions) this is invisible. For the other 10%, you get visibility into what is actually happening on disk.

### When real MongoDB is the right call

A few Mongo-only features are not in FerretDB: text indexes and the `$text` operator, `$lookup`, change streams, Atlas Search, sharded clusters with chunk balancing, BSON-specific edge cases, and time-series collections as a first-class feature. The [MongoDB vs FerretDB comparison](/blog/mongodb-vs-ferretdb) has the full list. If your app depends on any of those, host real MongoDB on [Layerbase Desktop](https://layerbase.com/desktop) or [the Layerbase CLI](https://layerbase.com/docs/cli) for development, and stick with MongoDB Atlas in production.

## Local development with Layerbase Desktop

Cloud databases are great for staging and production. For local development, you want a database that runs on your machine without a network round-trip.

[Layerbase Desktop](https://layerbase.com/desktop) ships PostgreSQL, FerretDB, MongoDB (yes, real MongoDB for local), and other engines as one-click installs on macOS, Windows, and Linux. The dashboard, query console, and connection panel are the same as the cloud experience. Free for personal use.

For a CLI workflow, [the Layerbase CLI](https://layerbase.com/docs/cli) (formerly SpinDB) is the command-line version:

```bash
npm i -g layerbase
lbase create payload-dev --engine postgresql --start
lbase url payload-dev    # prints the connection string
```

Swap `postgresql` for `ferretdb` or `mongodb` for the document path. Point Payload's `DATABASE_URL` at the printed URL and you have a local development database in seconds.

## FAQ

### Which database should I use with PayloadCMS?

PostgreSQL, for most projects. It handles relational data cleanly, `jsonb` covers the schema-flexible cases when they come up, and the tooling around Postgres is unmatched: `pg_dump`, point-in-time recovery, every ORM and BI tool you already own. Reach for FerretDB when your data is genuinely document-shaped or your team already lives in MongoDB drivers and `mongosh`.

### Is there a FerretDB adapter for Payload?

There is not, and you do not need one. FerretDB implements the MongoDB wire protocol, so you install `@payloadcms/db-mongodb` and configure `mongooseAdapter` with a `mongodb://` URL exactly as you would against MongoDB. Not a line of application code changes.

### Can I run PayloadCMS on the free tier?

With Postgres, yes: create it at [layerbase.com/create/postgresql](https://layerbase.com/create/postgresql), no card. FerretDB is not one of the free-tier engines, so a document-backed Payload install starts on the lowest paid plan.

### What do I give up by choosing FerretDB over real MongoDB?

Text indexes and `$text`, `$lookup`, change streams, Atlas Search, sharded clusters with chunk balancing, some BSON edge cases, and first-class time-series collections. Payload itself does not need any of those, so the question is whether your own collections and hooks do. If they do, develop against real MongoDB locally and stay on Atlas in production.

### Should I use SQLite behind PayloadCMS?

For local development and small single-machine deployments, it is fine. For anything a team depends on, it is not what you want behind a production Payload install, and the migration to Postgres later is work you can skip by starting there.

## Wrapping up

For a new Payload project, this is the shortest path to a production-ready database:

- **Default**: PostgreSQL via [`/create/postgresql`](https://layerbase.com/create/postgresql) and `@payloadcms/db-postgres`
- **Document model**: FerretDB via [`/create/ferretdb`](https://layerbase.com/create/ferretdb) and `@payloadcms/db-mongodb`
- **Local dev**: [Layerbase Desktop](https://layerbase.com/desktop) or [the Layerbase CLI](https://layerbase.com/docs/cli)

Postgres starts on the free tier with no credit card; FerretDB starts on our lowest paid plan. Both run the upstream binary directly. Both stay portable: the same connection string format works on every host, so you are never locked in.
