feat: add KV storage adapters #9913
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
r1tsuu force-pushed the feat/kv branch 2 times, most recently from 084d143 to 5f29665 Compare r1tsuu added a commit that referenced this pull request Dec 12, 2024
…ating existing ones (#9916) ### What? `payload.db.updateOne` (and so `payload.db.upsert`) with drizzle adapters used incoming `where` incorrectly and worked properly only either if you passed `id` or some where query path required table joins (like `where: { 'array.title'`) which is also the reason why `upsert` _worked_ with user preferences specifically, because we need to join the `preferences_rels` table to query by `user.relationTo` and `user.value` Fixes #9915 This was found here - #9913, the database KV adapter uses `upsert` with `where` by unique fields.
r1tsuu force-pushed the feat/kv branch 2 times, most recently from 16f614e to 2f146f0 Compare 
kendelljoseph pushed a commit that referenced this pull request Feb 21, 2025
…ating existing ones (#9916) ### What? `payload.db.updateOne` (and so `payload.db.upsert`) with drizzle adapters used incoming `where` incorrectly and worked properly only either if you passed `id` or some where query path required table joins (like `where: { 'array.title'`) which is also the reason why `upsert` _worked_ with user preferences specifically, because we need to join the `preferences_rels` table to query by `user.relationTo` and `user.value` Fixes #9915 This was found here - #9913, the database KV adapter uses `upsert` with `where` by unique fields.
Contributor
📦 esbuild Bundle Analysis for payloadThis analysis was generated by esbuild-bundle-analyzer. 🤖
Largest pathsThese visualization shows top 20 largest paths in the bundle.Meta file: packages/next/meta_index.json, Out file: esbuild/index.js
Meta file: packages/payload/meta_index.json, Out file: esbuild/index.js
Meta file: packages/payload/meta_shared.json, Out file: esbuild/exports/shared.js
Meta file: packages/richtext-lexical/meta_client.json, Out file: esbuild/exports/client_optimized/index.js
Meta file: packages/ui/meta_client.json, Out file: esbuild/exports/client_optimized/index.js
Meta file: packages/ui/meta_shared.json, Out file: esbuild/exports/shared_optimized/index.js
DetailsNext to the size is how much the size has increased or decreased compared with the base branch of this PR.
|
Contributor
There was a problem hiding this comment.
Pull Request Overview
Adds a Key-Value (KV) storage capability to Payload using an adapter pattern, supporting database, in-memory, and Redis backends for data storage needs.
- Introduces
KVAdapterinterface and three implementations: database, in-memory, and Redis adapters - Adds configuration support via the
kvproperty in root config - Includes comprehensive test coverage and GitHub Actions CI integration for Redis
Reviewed Changes
Copilot reviewed 28 out of 31 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/payload/src/kv/index.ts | Defines the KVAdapter interface and type definitions |
| packages/payload/src/kv/adapters/DatabaseKVAdapter.ts | Implements KV storage using Payload's database |
| packages/payload/src/kv/adapters/InMemoryKVAdapter.ts | Implements in-memory KV storage |
| packages/kv-redis/src/index.ts | Implements Redis-based KV storage adapter |
| packages/payload/src/config/defaults.ts | Adds default KV adapter configuration |
| packages/payload/src/index.ts | Exports KV types and initializes KV adapter |
| test/kv/int.spec.ts | Integration tests for all KV adapters |
| .github/workflows/main.yml | Adds Redis service to CI pipeline |
Files not reviewed (1)
- pnpm-lock.yaml: Language not supported
Comments suppressed due to low confidence (1)
packages/payload/src/config/types.ts:1
- The function name in the documentation example is
createDatabaseKVAdapter, but the actual exported function isdatabaseKVAdapter.
import type { Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
DanRibbens approved these changes Oct 30, 2025
Contributor
DanRibbens left a comment
DanRibbens left a comment There was a problem hiding this comment.
Need one more approval for the new package from @denolfe
denolfe approved these changes Oct 30, 2025
Member
denolfe left a comment
denolfe left a comment There was a problem hiding this comment.
LGTM 👍
We'll want to get an initial version published, so it can go out in the next release.
Contributor
| 🚀 This is included in version v3.62.0 |
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Add this suggestion to a batch that can be applied as a single commit. This suggestion is invalid because no changes were made to the code. Suggestions cannot be applied while the pull request is closed. Suggestions cannot be applied while viewing a subset of changes. Only one suggestion per line can be applied in a batch. Add this suggestion to a batch that can be applied as a single commit. Applying suggestions on deleted lines is not supported. You must change the existing code in this line in order to create a valid suggestion. Outdated suggestions cannot be applied. This suggestion has been applied or marked resolved. Suggestions cannot be applied from pending reviews. Suggestions cannot be applied on multi-line comments. Suggestions cannot be applied while the pull request is queued to merge. Suggestion cannot be applied right now. Please check back later.
Adds KV storage support to Payload Local API with an adapter pattern, includes 3 adapters. We'll use it for the Realtime API.
You can access it via
payload.kv:To configure the adapter you can use the
kvproperty of the root config.Database KV adapter (default)
No need to configure, as Payload uses it by default. It generates new collection
payload-kvand uses the current database adapter to access it. The collection is hidden in the admin panel and access locked.If you want to override the generated collection:
In Memory KV adapter
Simple and very fast storage using memory. Don't use it on Vercel / multiple instances or if you need data persistence.
Redis KV Adapter
Uses Redis. Probably the best option as it's faster than database, persistent and works with Vercel / multiple instances, but requires additional setup