Payload DB Memory Adapter

A data-agnostic, in-memory database adapter for Payload 3.x.

It lets you develop an app or website without a real database. The adapter keeps Payload documents in process memory and implements the Payload database interface for collections, globals, versions, drafts, counts, distinct queries, and jobs.

This package does not include built-in seeding or hot reload. If you want to preload data, use a separate plugin such as @websolutespa/payload-plugin-seed or write to the adapter through Payload APIs or the exposed in-memory models.

• Main Repository
• Payload Docs

Why

• Zero infrastructure: no MongoDB or Postgres required for local development.
• Data agnostic: works with any collection or global schema and stores documents in Payload's database shape.
• Full adapter: implements the Payload BaseDatabaseAdapter interface.
• Ecosystem compatible: exposes lightweight collection and version models for tools that call payload.db.collections[slug].bulkWrite(...) or .countDocuments().

Installation

npm install @websolutespa/payload-db-memory

Usage

import { buildConfig } from 'payload'
import { memoryAdapter } from '@websolutespa/payload-db-memory'

export default buildConfig({
  // ...rest of config
  db: memoryAdapter(),
})

You can also customize how IDs are generated for newly created documents:

memoryAdapter({
  defaultIDType: 'number',
  allowIDOnCreate: true,
})

Data model

Documents are stored in Payload's database shape, like the SQL and Mongo adapters:

• Localized fields are stored as locale-keyed objects, for example { en: 'Hello', it: 'Ciao' }.
• Relationships are stored as an id, or as { relationTo, value } for polymorphic relations.

Payload still resolves locale flattening on read.

Populating data

This adapter starts empty. You can populate it in three ways:

1. Use normal Payload operations such as payload.create, payload.update, and payload.updateGlobal.
2. Use a dedicated seeding plugin such as @websolutespa/payload-plugin-seed.
3. Use the Mongo-like in-memory models exposed on payload.db.collections[slug] and payload.db.versions[slug].

Example:

await payload.create({
  collection: 'posts',
  data: {
    title: 'Hello',
  },
})

Options

memoryAdapter({
  /** 'text' (default) or 'number' generated IDs. */
  defaultIDType?: 'number' | 'text'
  /** Allow caller-provided ids on create. Default false. */
  allowIDOnCreate?: boolean
})

defaultIDType

• 'text' generates a Mongo-like 24 character hex id.
• 'number' generates progressive numeric ids scoped per slug.

allowIDOnCreate

When true, explicit ids passed to create flows are accepted.

Ecosystem compatibility

Some Payload ecosystem utilities write directly to the underlying model instead of using high-level Payload CRUD APIs. This adapter exposes lightweight in-memory models on payload.db.collections and payload.db.versions with:

• bulkWrite(...)
• countDocuments()

That keeps utilities such as static i18n collection loaders and cron-related jobs from crashing when they expect a Mongo-like model surface.

Unregistered slugs resolve to undefined gracefully.

Supported query features

The in-memory query engine supports Payload where clauses (and / or and the operators equals, not_equals, in, not_in, all, exists, like, contains, greater_than[_equal], less_than[_equal]), locale-aware field resolution, relationship id matching, sorting (sort / -sort), pagination, select projections, and findDistinct.

Not supported: geospatial operators (near, within, intersects) are treated as no-ops, and relationship join queries are not resolved.

Advanced / internal API

Power users and tests can import the internal building blocks:

import {
  buildWhere,
  clone,
  createStore,
  paginate,
  sortDocs,
} from '@websolutespa/payload-db-memory/internal'

Limitations

• Data lives in process memory and is lost on restart.
• No real transactions: begin, commit, and rollback are no-ops.
• No persistent migrations: createMigration is a no-op.
• migrateFresh clears the in-memory store; it does not reseed anything.

Intended for development and testing, not production.