tabshift/payload
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(db-*): support atomic array $push db updates (#13453)

Browse Source 
This PR adds **atomic** `$push` **support for array fields**. It makes
it possible to safely append new items to arrays, which is especially
useful when running tasks in parallel (like job queues) where multiple
processes might update the same record at the same time. By handling
pushes atomically, we avoid race conditions and keep data consistent -
especially on postgres, where the current implementation would nuke the
entire array table before re-inserting every single array item.

The feature works for both localized and unlocalized arrays, and
supports pushing either single or multiple items at once.

This PR is a requirement for reliably running parallel tasks in the job
queue - see https://github.com/payloadcms/payload/pull/13452.

Alongside documenting `$push`, this PR also adds documentation for
`$inc`.

## Changes to updatedAt behavior

https://github.com/payloadcms/payload/pull/13335 allows us to override
the updatedAt property instead of the db always setting it to the
current date.

However, we are not able to skip updating the updatedAt property
completely. This means, usage of $push results in 2 postgres db calls:
1. set updatedAt in main row
2. append array row in arrays table

This PR changes the behavior to only automatically set updatedAt if it's
undefined. If you explicitly set it to `null`, this now allows you to
skip the db adapter automatically setting updatedAt.

=> This allows us to use $push in just one single db call

## Usage Examples

### Pushing a single item to an array

```ts
const post = (await payload.db.updateOne({
  data: {
    array: {
      $push: {
        text: 'some text 2',
        id: new mongoose.Types.ObjectId().toHexString(),
      },
    },
  },
  collection: 'posts',
  id: post.id,
}))
```

### Pushing a single item to a localized array

```ts
const post = (await payload.db.updateOne({
  data: {
    arrayLocalized: {
      $push: {
        en: {
          text: 'some text 2',
          id: new mongoose.Types.ObjectId().toHexString(),
        },
        es: {
          text: 'some text 2 es',
          id: new mongoose.Types.ObjectId().toHexString(),
        },
      },
    },
  },
  collection: 'posts',
  id: post.id,
}))
```

### Pushing multiple items to an array

```ts
const post = (await payload.db.updateOne({
  data: {
    array: {
      $push: [
        {
          text: 'some text 2',
          id: new mongoose.Types.ObjectId().toHexString(),
        },
        {
          text: 'some text 3',
          id: new mongoose.Types.ObjectId().toHexString(),
        },
      ],
    },
  },
  collection: 'posts',
  id: post.id,
}))
```

### Pushing multiple items to a localized array

```ts
const post = (await payload.db.updateOne({
  data: {
    arrayLocalized: {
      $push: {
        en: {
          text: 'some text 2',
          id: new mongoose.Types.ObjectId().toHexString(),
        },
        es: [
          {
            text: 'some text 2 es',
            id: new mongoose.Types.ObjectId().toHexString(),
          },
          {
            text: 'some text 3 es',
            id: new mongoose.Types.ObjectId().toHexString(),
          },
        ],
      },
    },
  },
  collection: 'posts',
  id: post.id,
}))
```

---
- To see the specific tasks where the Asana app for GitHub is being
used, see below:
  - https://app.asana.com/0/0/1211110462564647
This commit is contained in:
Alessio Gravili
2025-08-27 11:11:08 -07:00
committed by GitHub
parent a67043854e
commit 5ded64eaaf
14 changed files with 685 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
test/database/getConfig.ts
View File

@@ -257,6 +257,22 @@ export const getConfig: () => Partial<Config> = () => ({
{
name: 'arrayWithIDs',
type: 'array',
fields: [
{
name: 'text',
type: 'text',
},
{
name: 'textLocalized',
type: 'text',
localized: true,
},
],
},
{
name: 'arrayWithIDsLocalized',
type: 'array',
localized: true,
fields: [
{
name: 'text',

366
test/database/int.spec.ts
View File

@@ -1,5 +1,5 @@
import type { MongooseAdapter } from '@payloadcms/db-mongodb'
import type { PostgresAdapter } from '@payloadcms/db-postgres/types'
import type { PostgresAdapter } from '@payloadcms/db-postgres'
import type { NextRESTClient } from 'helpers/NextRESTClient.js'
import type {
DataFromCollectionSlug,
@@ -29,7 +29,7 @@ import {
import { assert } from 'ts-essentials'
import { fileURLToPath } from 'url'
import type { Global2 } from './payload-types.js'
import type { Global2, Post } from './payload-types.js'
import { devUser } from '../credentials.js'
import { initPayloadInt } from '../helpers/initPayloadInt.js'
@@ -339,6 +339,57 @@ describe('database', () => {
})
})
it('ensure updatedAt is automatically set when using db.updateOne', async () => {
const post = await payload.create({
collection: postsSlug,
data: {
title: 'hello',
},
})
const result: any = await payload.db.updateOne({
collection: postsSlug,
id: post.id,
data: {
title: 'hello2',
},
})
expect(result.updatedAt).not.toStrictEqual(post.updatedAt)
// Cleanup, as this test suite does not use clearAndSeedEverything
await payload.db.deleteMany({
collection: postsSlug,
where: {},
})
})
it('ensure updatedAt is not automatically set when using db.updateOne if it is explicitly set to `null`', async () => {
const post = await payload.create({
collection: postsSlug,
data: {
title: 'hello',
},
})
const result: any = await payload.db.updateOne({
collection: postsSlug,
id: post.id,
data: {
updatedAt: null,
title: 'hello2',
},
})
expect(result.updatedAt).toStrictEqual(post.updatedAt)
// Cleanup, as this test suite does not use clearAndSeedEverything
await payload.db.deleteMany({
collection: postsSlug,
where: {},
})
})
it('should allow createdAt to be set in updateVersion', async () => {
const category = await payload.create({
collection: 'categories',
@@ -3327,7 +3378,7 @@ describe('database', () => {
it('should allow incremental number update', async () => {
const post = await payload.create({ collection: 'posts', data: { number: 1, title: 'post' } })
const res = await payload.db.updateOne({
const res = (await payload.db.updateOne({
data: {
number: {
$inc: 10,
@@ -3335,11 +3386,11 @@ describe('database', () => {
},
collection: 'posts',
where: { id: { equals: post.id } },
})
})) as unknown as Post
expect(res.number).toBe(11)
const res2 = await payload.db.updateOne({
const res2 = (await payload.db.updateOne({
data: {
number: {
$inc: -3,
@@ -3347,11 +3398,314 @@ describe('database', () => {
},
collection: 'posts',
where: { id: { equals: post.id } },
})
})) as unknown as Post
expect(res2.number).toBe(8)
})
describe('array $push', () => {
it('should allow atomic array updates and $inc', async () => {
const post = await payload.create({
collection: 'posts',
data: {
number: 10,
arrayWithIDs: [
{
text: 'some text',
},
],
title: 'post',
},
})
const res = (await payload.db.updateOne({
data: {
arrayWithIDs: {
$push: {
text: 'some text 2',
id: new mongoose.Types.ObjectId().toHexString(),
},
},
number: {
$inc: 5,
},
},
collection: 'posts',
id: post.id,
})) as unknown as Post
expect(res.arrayWithIDs).toHaveLength(2)
expect(res.arrayWithIDs?.[0]?.text).toBe('some text')
expect(res.arrayWithIDs?.[1]?.text).toBe('some text 2')
expect(res.number).toBe(15)
})
it('should allow atomic array updates using $push with single value, unlocalized', async () => {
const post = await payload.create({
collection: 'posts',
data: {
arrayWithIDs: [
{
text: 'some text',
},
],
title: 'post',
},
})
const res = (await payload.db.updateOne({
data: {
arrayWithIDs: {
$push: {
text: 'some text 2',
id: new mongoose.Types.ObjectId().toHexString(),
},
},
},
collection: 'posts',
id: post.id,
})) as unknown as Post
expect(res.arrayWithIDs).toHaveLength(2)
expect(res.arrayWithIDs?.[0]?.text).toBe('some text')
expect(res.arrayWithIDs?.[1]?.text).toBe('some text 2')
})
it('should allow atomic array updates using $push with single value, localized field within array', async () => {
const post = await payload.create({
collection: 'posts',
data: {
arrayWithIDs: [
{
text: 'some text',
textLocalized: 'Some text localized',
},
],
title: 'post',
},
})
const res = (await payload.db.updateOne({
data: {
// Locales used => no optimized row update => need to pass full data, incuding title
title: 'post',
arrayWithIDs: {
$push: {
text: 'some text 2',
id: new mongoose.Types.ObjectId().toHexString(),
textLocalized: {
en: 'Some text 2 localized',
es: 'Algun texto 2 localizado',
},
},
},
},
collection: 'posts',
id: post.id,
})) as unknown as Post
expect(res.arrayWithIDs).toHaveLength(2)
expect(res.arrayWithIDs?.[0]?.text).toBe('some text')
expect(res.arrayWithIDs?.[0]?.textLocalized).toEqual({
en: 'Some text localized',
})
expect(res.arrayWithIDs?.[1]?.text).toBe('some text 2')
expect(res.arrayWithIDs?.[1]?.textLocalized).toEqual({
en: 'Some text 2 localized',
es: 'Algun texto 2 localizado',
})
})
it('should allow atomic array updates using $push with single value, localized array', async () => {
const post = await payload.create({
collection: 'posts',
data: {
arrayWithIDsLocalized: [
{
text: 'some text',
},
],
title: 'post',
},
})
const res = (await payload.db.updateOne({
data: {
// Locales used => no optimized row update => need to pass full data, incuding title
title: 'post',
arrayWithIDsLocalized: {
$push: {
en: {
text: 'some text 2',
id: new mongoose.Types.ObjectId().toHexString(),
},
es: {
text: 'some text 2 es',
id: new mongoose.Types.ObjectId().toHexString(),
},
},
},
},
collection: 'posts',
id: post.id,
})) as unknown as any
expect(res.arrayWithIDsLocalized?.en).toHaveLength(2)
expect(res.arrayWithIDsLocalized?.en?.[0]?.text).toBe('some text')
expect(res.arrayWithIDsLocalized?.en?.[1]?.text).toBe('some text 2')
expect(res.arrayWithIDsLocalized?.es).toHaveLength(1)
expect(res.arrayWithIDsLocalized?.es?.[0]?.text).toBe('some text 2 es')
})
it('should allow atomic array updates using $push with multiple values, unlocalized', async () => {
const post = await payload.create({
collection: 'posts',
data: {
arrayWithIDs: [
{
text: 'some text',
},
],
title: 'post',
},
})
const res = (await payload.db.updateOne({
data: {
arrayWithIDs: {
$push: [
{
id: new mongoose.Types.ObjectId().toHexString(),
text: 'some text 2',
},
{
id: new mongoose.Types.ObjectId().toHexString(),
text: 'some text 3',
},
],
},
},
collection: 'posts',
id: post.id,
})) as unknown as Post
expect(res.arrayWithIDs).toHaveLength(3)
expect(res.arrayWithIDs?.[0]?.text).toBe('some text')
expect(res.arrayWithIDs?.[1]?.text).toBe('some text 2')
expect(res.arrayWithIDs?.[2]?.text).toBe('some text 3')
})
it('should allow atomic array updates using $push with multiple values, localized field within array', async () => {
const post = await payload.create({
collection: 'posts',
data: {
arrayWithIDs: [
{
text: 'some text',
textLocalized: 'Some text localized',
},
],
title: 'post',
},
})
const res = (await payload.db.updateOne({
data: {
// Locales used => no optimized row update => need to pass full data, incuding title
title: 'post',
arrayWithIDs: {
$push: [
{
id: new mongoose.Types.ObjectId().toHexString(),
text: 'some text 2',
textLocalized: {
en: 'Some text 2 localized',
es: 'Algun texto 2 localizado',
},
},
{
id: new mongoose.Types.ObjectId().toHexString(),
text: 'some text 3',
textLocalized: {
en: 'Some text 3 localized',
es: 'Algun texto 3 localizado',
},
},
],
},
},
collection: 'posts',
id: post.id,
})) as unknown as Post
expect(res.arrayWithIDs).toHaveLength(3)
expect(res.arrayWithIDs?.[0]?.text).toBe('some text')
expect(res.arrayWithIDs?.[1]?.text).toBe('some text 2')
expect(res.arrayWithIDs?.[2]?.text).toBe('some text 3')
expect(res.arrayWithIDs?.[0]?.textLocalized).toEqual({
en: 'Some text localized',
})
expect(res.arrayWithIDs?.[1]?.textLocalized).toEqual({
en: 'Some text 2 localized',
es: 'Algun texto 2 localizado',
})
expect(res.arrayWithIDs?.[2]?.textLocalized).toEqual({
en: 'Some text 3 localized',
es: 'Algun texto 3 localizado',
})
})
it('should allow atomic array updates using $push with multiple values, localized array', async () => {
const post = await payload.create({
collection: 'posts',
data: {
arrayWithIDsLocalized: [
{
text: 'some text',
},
],
title: 'post',
},
})
const res = (await payload.db.updateOne({
data: {
// Locales used => no optimized row update => need to pass full data, incuding title
title: 'post',
arrayWithIDsLocalized: {
$push: {
en: {
text: 'some text 2',
id: new mongoose.Types.ObjectId().toHexString(),
},
es: [
{
text: 'some text 2 es',
id: new mongoose.Types.ObjectId().toHexString(),
},
{
text: 'some text 3 es',
id: new mongoose.Types.ObjectId().toHexString(),
},
],
},
},
},
collection: 'posts',
id: post.id,
})) as unknown as any
expect(res.arrayWithIDsLocalized?.en).toHaveLength(2)
expect(res.arrayWithIDsLocalized?.en?.[0]?.text).toBe('some text')
expect(res.arrayWithIDsLocalized?.en?.[1]?.text).toBe('some text 2')
expect(res.arrayWithIDsLocalized?.es).toHaveLength(2)
expect(res.arrayWithIDsLocalized?.es?.[0]?.text).toBe('some text 2 es')
expect(res.arrayWithIDsLocalized?.es?.[1]?.text).toBe('some text 3 es')
})
})
it('should support x3 nesting blocks', async () => {
const res = await payload.create({
collection: 'posts',

70
test/database/payload-types.ts
View File

@@ -180,27 +180,11 @@ export interface NoTimeStamp {
export interface Category {
id: string;
title?: string | null;
updatedAt: string;
createdAt: string;
_status?: ('draft' | 'published') | null;
}
/**
* This interface was referenced by `Config`'s JSON-Schema
* via the `definition` "simple".
*/
export interface Simple {
id: string;
text?: string | null;
number?: number | null;
updatedAt: string;
createdAt: string;
}
/**
* This interface was referenced by `Config`'s JSON-Schema
* via the `definition` "categories-custom-id".
*/
export interface CategoriesCustomId {
id: number;
hideout?: {
camera1?: {
time1Image?: (string | null) | Post;
};
};
updatedAt: string;
createdAt: string;
_status?: ('draft' | 'published') | null;
@@ -242,6 +226,13 @@ export interface Post {
hasTransaction?: boolean | null;
throwAfterChange?: boolean | null;
arrayWithIDs?:
| {
text?: string | null;
textLocalized?: string | null;
id?: string | null;
}[]
| null;
arrayWithIDsLocalized?:
| {
text?: string | null;
id?: string | null;
@@ -264,6 +255,27 @@ export interface Post {
updatedAt: string;
createdAt: string;
}
/**
* This interface was referenced by `Config`'s JSON-Schema
* via the `definition` "categories-custom-id".
*/
export interface CategoriesCustomId {
id: number;
updatedAt: string;
createdAt: string;
_status?: ('draft' | 'published') | null;
}
/**
* This interface was referenced by `Config`'s JSON-Schema
* via the `definition` "simple".
*/
export interface Simple {
id: string;
text?: string | null;
number?: number | null;
updatedAt: string;
createdAt: string;
}
/**
* This interface was referenced by `Config`'s JSON-Schema
* via the `definition` "error-on-unnamed-fields".
@@ -770,6 +782,15 @@ export interface NoTimeStampsSelect<T extends boolean = true> {
*/
export interface CategoriesSelect<T extends boolean = true> {
title?: T;
hideout?:
| T
| {
camera1?:
| T
| {
time1Image?: T;
};
};
updatedAt?: T;
createdAt?: T;
_status?: T;
@@ -842,6 +863,13 @@ export interface PostsSelect<T extends boolean = true> {
hasTransaction?: T;
throwAfterChange?: T;
arrayWithIDs?:
| T
| {
text?: T;
textLocalized?: T;
id?: T;
};
arrayWithIDsLocalized?:
| T
| {
text?: T;

52
test/database/postgres-logs.int.spec.ts
View File

@@ -2,9 +2,12 @@ import type { Payload } from 'payload'
/* eslint-disable jest/require-top-level-describe */
import assert from 'assert'
import mongoose from 'mongoose'
import path from 'path'
import { fileURLToPath } from 'url'
import type { Post } from './payload-types.js'
import { initPayloadInt } from '../helpers/initPayloadInt.js'
const filename = fileURLToPath(import.meta.url)
@@ -169,6 +172,53 @@ describePostgres('database - postgres logs', () => {
})
expect(allPosts.docs).toHaveLength(1)
expect(allPosts.docs[0].id).toEqual(doc1.id)
expect(allPosts.docs[0]?.id).toEqual(doc1.id)
})
it('ensure array update using $push is done in single db call', async () => {
const post = await payload.create({
collection: 'posts',
data: {
arrayWithIDs: [
{
text: 'some text',
},
],
title: 'post',
},
})
const consoleCount = jest.spyOn(console, 'log').mockImplementation(() => {})
await payload.db.updateOne({
data: {
// Ensure db adapter does not automatically set updatedAt - one less db call
updatedAt: null,
arrayWithIDs: {
$push: {
text: 'some text 2',
id: new mongoose.Types.ObjectId().toHexString(),
},
},
},
collection: 'posts',
id: post.id,
returning: false,
})
// 1 Update:
// 1. (updatedAt for posts row.) - skipped because we explicitly set updatedAt to null
// 2. arrayWithIDs.$push for posts row
expect(consoleCount).toHaveBeenCalledTimes(1)
consoleCount.mockRestore()
const updatedPost = (await payload.db.findOne({
collection: 'posts',
where: { id: { equals: post.id } },
})) as unknown as Post
expect(updatedPost.title).toBe('post')
expect(updatedPost.arrayWithIDs).toHaveLength(2)
expect(updatedPost.arrayWithIDs?.[0]?.text).toBe('some text')
expect(updatedPost.arrayWithIDs?.[1]?.text).toBe('some text 2')
})
})