From 81260f58d8f91b72b02ab2204549d120a8728c36 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Mon, 22 Sep 2025 17:20:34 +0200 Subject: [PATCH] Explain `unique` parameter behavior with Draft & Publish (#2716) * docs(cms): clarify unique constraint with draft publish * Fix wrong link * Update docusaurus/docs/cms/backend-customization/models.md * Update docusaurus/docs/cms/backend-customization/models.md * Update docusaurus/docs/cms/backend-customization/models.md * Update docusaurus/docs/cms/backend-customization/models.md --- docusaurus/docs/cms/backend-customization/models.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docusaurus/docs/cms/backend-customization/models.md b/docusaurus/docs/cms/backend-customization/models.md index c411878c45..bb42117fde 100644 --- a/docusaurus/docs/cms/backend-customization/models.md +++ b/docusaurus/docs/cms/backend-customization/models.md @@ -186,10 +186,20 @@ Database validations and settings are custom options passed directly onto the `t | `defaultTo` | string | Sets the database `defaultTo`, typically used with `notNullable` | - | | `notNullable` | boolean | Sets the database `notNullable`, ensures that columns cannot be null | `false` | | `unsigned` | boolean | Only applies to number columns, removes the ability to go negative but doubles maximum length | `false` | -| `unique` | boolean | Enforces database level unique, caution when using with draft & publish feature | `false` | +| `unique` | boolean | Enforces database-level uniqueness on published entries. Draft saves skip the check when Draft & Publish is enabled, so duplicates fail only at publish time. | `false` | | `type` | string | Changes the database type, if `type` has arguments, you should pass them in `args` | - | | `args` | array | Arguments passed into the Knex.js function that changes things like `type` | `[]` | +:::caution Draft & Publish and `unique` +When [Draft & Publish](/cms/features/draft-and-publish) is enabled, Strapi intentionally skips `unique` validations while an entry is saved as a draft. Duplicates therefore remain undetected until publication, at which point the database constraint triggers an error even though the UI previously displayed “Saved document” for the drafts. + +To avoid unexpected publication failures: + +- disable Draft & Publish on content-types that must stay globally unique, +- or add custom validation (e.g. lifecycle hooks or middleware) that checks for draft duplicates before saving, +- or rely on automatically generated unique identifiers such as a `uid` field and document editorial conventions. +::: + ```json title="./src/api/[api-name]/content-types/restaurant/schema.json" {