docs: add warning about unique fields with drafts enabled

[efe-arv]

What

Adds documentation about a known limitation where unique: true fields on collections with versions.drafts enabled cause silent document creation failures.

The Problem

When a drafts-enabled collection has fields with unique: true, creating new documents can fail silently:

1. User clicks "Save" or "Publish" on a new document
2. Payload attempts to write to both the main table and the versions table (_collection_v)
3. The database-level UNIQUE constraint conflicts during the draft creation process
4. The Admin UI redirects to ?notFound=<id> with no visible error message

This affects all database adapters (PostgreSQL/Drizzle and MongoDB) and has been reported multiple times:

• [Bug](Versions): Autosave fails when there exists a unique field #953 (Aug 2022)
• UNIQUE constraint failed: No proper error message in the ui #12628 (May 2025)
• Validate does not work with drafts enabled #3576 (Discussion)

What This PR Adds

1. Warning banner in the "Database changes" section of the Drafts docs
2. New section: "Unique fields with Drafts" with:
   • Clear problem explanation
   • Recommended workaround: replace unique: true with index: true + application-level validate function
   • Complete code example

The Workaround

{
  name: 'slug',
  type: 'text',
  // Use index instead of unique
  index: true,
  validate: async (value, { req, id }) => {
    if (!value) return true
    const existing = await req.payload.find({
      collection: 'my-collection',
      where: {
        slug: { equals: value },
        id: { not_equals: id || 0 },
      },
      limit: 1,
    })
    if (existing.totalDocs > 0) return 'This value is already in use'
    return true
  },
}

Context

We hit this in production on a legal CMS (Payload 3.64.0 + PostgreSQL on Fly.io) with 5,000+ tags. The collection had versions.drafts enabled with unique: true on both name and slug fields. Tag creation was completely broken with no error feedback — just a ?notFound= redirect. Replacing the DB-level unique constraint with an application-level validate function resolved it immediately.

Ideally Payload would handle this gracefully at the framework level (e.g., deferring unique validation for draft documents, or surfacing a clear error), but until then, this documentation helps others avoid the same trap.

[jhb-dev]

I think this should just be a count operation or at least set depth to 0 and select to {}, to prevent fetching and populating data that is not needed here.

[efe-arv]

Good call — updated to use count() instead of find(). No document population needed, just the existence check. Also dropped the redundant limit: 1 since count doesn't paginate.

[efe-arv]

Updated to use count() in commit a2f6c2c — no document data is fetched at all, just the total count. The limit: 1 was also removed since count() doesn't paginate. This addresses @jhb-dev's review — both the performance concern and the unnecessary population issue.

[efe-arv]

Hi @jhb-dev — just a gentle ping. The count() change from your feedback is in commit a2f6c2c. No document data fetched at all, limit: 1 also removed. Happy to address any further concerns if you have a moment to re-review. Thanks!

[jhb-dev]

Hi @efe-arv, nice you added the perf improvement! Unfortunately I am not a maintainer of this project, so you have to wait for a review of a team member.