PayloadCMS Setup: PostgreSQL or FerretDB

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 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?
• PayloadCMS with PostgreSQL
• PayloadCMS with FerretDB
• Why we recommend FerretDB over MongoDB
• Local development with Layerbase Desktop
• FAQ
• 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, 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:

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

2. Install the Payload adapter

pnpm add @payloadcms/db-postgres

3. Configure payload.config.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:

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

4. Run

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, name it, click Sign in and create. The dashboard will give you a Mongo-style connection string:

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

2. Install the Mongo adapter

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

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:

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

4. Run

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.

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 has the full list. If your app depends on any of those, host real MongoDB on Layerbase Desktop or the Layerbase 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 ships PostgreSQL, FerretDB, MongoDB (yes, real MongoDB for local), and 18 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 (formerly SpinDB) is the command-line version:

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, 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 and @payloadcms/db-postgres
• Document model: FerretDB via /create/ferretdb and @payloadcms/db-mongodb
• Local dev: Layerbase Desktop or the Layerbase 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.