feat!: add database copy method (#18453)

Adds a low-level database adapter method for copying one stored
collection document.

## Summary

`payload.db.copy` selects a source document with a `where` query,
applies optional top-level data overrides, and creates one new stored
record. It assigns new IDs to the document and copied array and block
rows. It does not copy version history.

Use `payload.duplicate` for normal application duplication.
`payload.db.copy` is intended for internal storage operations that must
skip the Local API create flow.

## How

- The operation uses existing adapter `findOne` and `create` methods.
- It leaves transaction ownership with the caller through the supplied
request.
- It throws `NotFound` when the source query does not match a document.
- It does not run Local API access control, hooks, field validation, or
upload handling.
- Custom-ID collections require `data.id` with the configured ID type.
The operation throws a clear error when it is missing or invalid.
- `createDatabaseAdapter` supplies the default implementation.

## Before and after

Before this change, callers had to read a stored document, remove its
ID, regenerate nested row IDs, and create the copy themselves.

After this change, callers can use:

```ts
await payload.db.copy({
  collection: "posts",
  data: { title: "Copied post" },
  req,
  where: { id: { equals: sourcePostID } },
})
```

For a custom-ID collection, the caller must supply a unique destination
ID:

```ts
await payload.db.copy({
  collection: "posts-with-custom-ids",
  data: {
    id: "copied-post",
    title: "Copied post",
  },
  req,
  where: { id: { equals: sourcePostID } },
})
```

## Breaking changes

`BaseDatabaseAdapter` now requires `copy`. Adapters created with
`createDatabaseAdapter` receive the default implementation
automatically. Direct `BaseDatabaseAdapter` implementations must add
this method.

## Validation

Real integration tests cover custom IDs, data overrides, fresh nested
row IDs, missing sources, and caller-owned rollback. The custom-ID
behaviour passes on MongoDB, Postgres, and SQLite. The Payload package
build also passes.

Written with AI

Author: paulpopus

docs/database/overview.mdx

@@ -98,3 +98,31 @@ The default implementation uses existing adapter methods. Custom adapters create
 It's important to note that nearly every Payload feature is available in all of our officially supported Database Adapters, including [Localization](../configuration/localization), [Arrays](../fields/array), [Blocks](../fields/blocks), etc. The only thing that is not supported in SQLite yet is the [Point Field](/docs/fields/point), but that should be added soon.
 
 It's up to you to choose which database you would like to use based on the requirements of your project. Payload has no opinion on which database you should ultimately choose.
+
+## Copying a stored document
+
+Use `payload.db.copy` to copy one stored collection document. The method selects the source with a `where` query and creates a new database record. Use `data` to replace top-level source values. Payload also assigns new IDs to copied array and block rows.
+
+```ts
+const copiedPost = await payload.db.copy({
+  collection: 'posts',
+  data: {
+    title: 'Copied post',
+  },
+  req,
+  where: {
+    id: {
+      equals: sourcePostID,
+    },
+  },
+})
+```
+
+### Key differences
+
+- `payload.db.copy` makes a one-to-one storage copy: one current source document becomes one new database record. It does not copy version history.
+- It copies stored values as-is, except document, array, and block row IDs. Unique fields and custom database indexes can reject the new record. Use `data` overrides or handle these conflicts yourself.
+- Custom-ID collections require `data.id` with the configured ID type. ID hooks do not run, so the caller must supply a unique destination ID.
+- It does not run access control, hooks, field validation, or upload handling. Use [`payload.duplicate`](/docs/local-api/overview#collection-create) for normal application duplication.
+
+The default implementation uses existing adapter methods. Custom adapters created with `createDatabaseAdapter` receive this implementation automatically. Direct implementations of `BaseDatabaseAdapter` must provide `copy` after this change.

packages/payload/src/database/createDatabaseAdapter.ts

@@ -8,6 +8,7 @@ import type {
 } from './types.js'
 
 import { defaultBatchProcessing } from './defaultBatchProcessing.js'
+import { defaultCopy } from './defaultCopy.js'
 import { createMigration } from './migrations/createMigration.js'
 import { migrate } from './migrations/migrate.js'
 import { migrateDown } from './migrations/migrateDown.js'
@@ -27,6 +28,7 @@ export function createDatabaseAdapter<T extends BaseDatabaseAdapter>(
     | 'allowIDOnCreate'
     | 'batchProcessing'
     | 'bulkOperationsSingleTransaction'
+    | 'copy'
     | 'createMigration'
     | 'migrate'
     | 'migrateDown'
@@ -44,6 +46,7 @@ export function createDatabaseAdapter<T extends BaseDatabaseAdapter>(
     beginTransaction,
     // @ts-expect-error - vestiges of when tsconfig was not strict. Feel free to improve
     commitTransaction,
+    copy: defaultCopy,
     createMigration,
     migrate,
     migrateDown,

packages/payload/src/database/defaultCopy.ts

@@ -0,0 +1,101 @@
+import { v4 as uuid } from 'uuid'
+
+import type { SanitizedConfig } from '../config/types.js'
+import type { Field } from '../fields/config/types.js'
+import type { Copy } from './types.js'
+
+import { NotFound } from '../errors/NotFound.js'
+import { deepCopyObjectSimple } from '../utilities/deepCopyObject.js'
+import { traverseFields } from '../utilities/traverseFields.js'
+
+export const defaultCopy: Copy = async function defaultCopy({ collection, data = {}, req, where }) {
+  const collectionConfig = this.payload.collections[collection]!
+  const { customIDType } = collectionConfig
+  const hasValidCustomID =
+    customIDType === 'number' ? typeof data.id === 'number' : typeof data.id === 'string'
+
+  if (customIDType && !hasValidCustomID) {
+    throw new TypeError(
+      `Database copy for collection "${collection}" requires data.id to match its custom ${customIDType} ID type`,
+    )
+  }
+
+  const sourceDocument = await this.findOne({
+    collection,
+    req,
+    where,
+  })
+
+  if (!sourceDocument) {
+    throw new NotFound(req?.t)
+  }
+
+  const { id: _sourceID, ...sourceData } = sourceDocument
+  const copiedData = copyDataWithFreshRowIDs({
+    config: this.payload.config,
+    data: {
+      ...sourceData,
+      ...data,
+    },
+    fields: collectionConfig.config.fields,
+  })
+
+  return this.create({
+    collection,
+    ...(customIDType ? { customID: data.id as number | string } : {}),
+    data: copiedData,
+    req,
+  })
+}
+
+const copyDataWithFreshRowIDs = ({
+  config,
+  data,
+  fields,
+}: {
+  config: SanitizedConfig
+  data: Record<string, unknown>
+  fields: Field[]
+}): Record<string, unknown> => {
+  const copiedData = deepCopyObjectSimple(data)
+
+  traverseFields({
+    callback: ({ field, ref }) => {
+      if (
+        (field.type !== 'array' && field.type !== 'blocks') ||
+        !field.name ||
+        !ref ||
+        typeof ref !== 'object'
+      ) {
+        return
+      }
+
+      const fieldValue = (ref as Record<string, unknown>)[field.name]
+      const assignFreshRowIDs = (rows: unknown) => {
+        if (!Array.isArray(rows)) {
+          return
+        }
+
+        for (const row of rows) {
+          if (row && typeof row === 'object') {
+            ;(row as Record<string, unknown>).id = uuid()
+          }
+        }
+      }
+
+      if (Array.isArray(fieldValue)) {
+        assignFreshRowIDs(fieldValue)
+      } else if (fieldValue && typeof fieldValue === 'object') {
+        for (const localeValue of Object.values(fieldValue as Record<string, unknown>)) {
+          assignFreshRowIDs(localeValue)
+        }
+      }
+    },
+    config,
+    fields,
+    fillEmpty: false,
+    ref: copiedData,
+  })
+
+  return copiedData
+}

packages/payload/src/database/types.ts

@@ -43,6 +43,10 @@ export interface BaseDatabaseAdapter {
    * Open the connection to the database
    */
   connect?: Connect
+  /**
+   * Copy one stored collection document without running Local API operations.
+   */
+  copy: Copy
   count: Count
   countGlobalVersions: CountGlobalVersions
   countVersions: CountVersions
@@ -235,6 +239,20 @@ export type BatchProcessing = (
   args: BatchProcessingArgs,
 ) => Promise<BatchProcessingResult[]>
 
+export type CopyArgs = {
+  collection: CollectionSlug
+  /**
+   * Top-level field values that replace values from the source document.
+   * Custom-ID collections require an `id` that matches the configured ID type.
+   */
+  data?: Record<string, unknown>
+  req?: Partial<PayloadRequest>
+  /** Selects the stored source document. */
+  where: Where
+}
+
+export type Copy = (this: BaseDatabaseAdapter, args: CopyArgs) => Promise<Document>
+
 export type CreateMigration = (args: {
   file?: string
   forceAcceptWarning?: boolean

packages/payload/src/index.ts

@@ -1594,6 +1594,8 @@ export type {
   BeginTransaction,
   CommitTransaction,
   Connect,
+  Copy,
+  CopyArgs,
   Count,
   CountArgs,
   CountGlobalVersionArgs,

test/database/copy.int.spec.ts

@@ -0,0 +1,131 @@
+/* eslint vitest/no-standalone-expect: ["error", { "additionalTestBlockFunctions": ["test", "test.options"] }] -- Tests use the shared fixture wrapper. */
+
+import type { PayloadRequest } from 'payload'
+
+import { initTransaction, killTransaction } from 'payload'
+import { expect } from 'vitest'
+
+import { test } from '../__helpers/int/vitest.js'
+import { customIDsSlug, postsSlug } from './shared.js'
+
+type CopyTestPost = {
+  arrayWithIDs?: { id?: string; text?: string }[]
+  blocksWithIDs?: { blockType: string; id?: string; text?: string }[]
+  id: number | string
+  title: string
+}
+
+test.suite('Database copy', { config: './config.ts' }, () => {
+  test('should copy stored data with overrides and new row IDs', async ({ payload }) => {
+    const source = (await payload.create({
+      collection: postsSlug,
+      data: {
+        arrayWithIDs: [{ text: 'source array row' }],
+        blocksWithIDs: [{ blockType: 'block-first', text: 'source block row' }],
+        title: 'source title',
+      },
+      overrideAccess: true,
+    })) as CopyTestPost
+
+    const copied = (await payload.db.copy({
+      collection: postsSlug,
+      data: { title: 'copied title' },
+      req: { payload },
+      where: { id: { equals: source.id } },
+    })) as CopyTestPost
+
+    expect(copied.id).not.toBe(source.id)
+    expect(copied.title).toBe('copied title')
+    expect(copied.arrayWithIDs?.[0]?.text).toBe('source array row')
+    expect(copied.arrayWithIDs?.[0]?.id).not.toBe(source.arrayWithIDs?.[0]?.id)
+    expect(copied.blocksWithIDs?.[0]?.text).toBe('source block row')
+    expect(copied.blocksWithIDs?.[0]?.id).not.toBe(source.blocksWithIDs?.[0]?.id)
+  })
+
+  test('should reject a missing source document', async ({ payload }) => {
+    await expect(
+      payload.db.copy({
+        collection: postsSlug,
+        req: { payload },
+        where: { id: { equals: 'missing-document' } },
+      }),
+    ).rejects.toMatchObject({ name: 'NotFound' })
+  })
+
+  test('should require a destination ID for a custom-ID collection', async ({ payload }) => {
+    const source = await payload.create({
+      collection: customIDsSlug,
+      data: { title: 'custom ID source' },
+      overrideAccess: true,
+    })
+
+    await expect(
+      payload.db.copy({
+        collection: customIDsSlug,
+        req: { payload },
+        where: { id: { equals: source.id } },
+      }),
+    ).rejects.toThrow('requires data.id')
+  })
+
+  test('should copy a custom-ID document when given a destination ID', async ({ payload }) => {
+    const source = await payload.create({
+      collection: customIDsSlug,
+      data: { title: 'custom ID source' },
+      overrideAccess: true,
+    })
+
+    const copied = await payload.db.copy({
+      collection: customIDsSlug,
+      data: {
+        id: 'copied-custom-id',
+        title: 'custom ID copy',
+      },
+      req: { payload },
+      where: { id: { equals: source.id } },
+    })
+
+    expect(copied.id).toBe('copied-custom-id')
+    expect(copied.title).toBe('custom ID copy')
+  })
+
+  test.options(
+    'should leave rollback to the caller transaction',
+    { db: (adapter) => adapter === 'mongodb' || adapter === 'postgres' },
+    async ({ payload }) => {
+      const source = await payload.create({
+        collection: postsSlug,
+        data: { title: 'transaction source' },
+        overrideAccess: true,
+      })
+      const req = { payload } as PayloadRequest
+      const didStartTransaction = await initTransaction(req)
+      const callerTransactionID = await req.transactionID
+      let copiedID: number | string | undefined
+
+      expect(didStartTransaction).toBe(true)
+
+      try {
+        const copied = await payload.db.copy({
+          collection: postsSlug,
+          req,
+          where: { id: { equals: source.id } },
+        })
+
+        copiedID = copied.id
+        expect(req.transactionID).toBe(callerTransactionID)
+      } finally {
+        if (req.transactionID) {
+          await killTransaction(req)
+        }
+      }
+
+      const copyAfterRollback = await payload.db.findOne({
+        collection: postsSlug,
+        where: { id: { equals: copiedID } },
+      })
+
+      expect(copyAfterRollback).toBeNull()
+    },
+  )
+})