Database lifecycle hooks are triggered differently with the Document Service API methods

In Strapi 5, database lifecycle hooks are triggered differently with the various Document Service API methods, mainly due to the new way the Draft & Publish feature works.

The majority of use cases should only use the Document Service. The Document Service API handles Draft & Publish, i18n, and any underlying strapi logic.

However, the Document Service API might not suit all your use cases; the database layer is therefore exposed allowing you to do anything on the database without any restriction. Users would then need to resort to the database lifecycle hooks as a system to extend the database behaviour.

This page is part of the breaking changes database and provides information about the breaking change and additional instructions to migrate from Strapi v4 to Strapi 5.

🔌 Is this breaking change affecting plugins?	Yes

🤖 Is this breaking change automatically handled by a codemod?	No

Breaking change description

In Strapi v4

In Strapi v4, lifecycle hooks work as documented in the Strapi v4 documentation.

In Strapi 5

Lifecycle hooks work the same way as in Strapi v4 but are triggered differently, based on which Document Service API methods are triggered. A complete reference is available (see notes).

Migration

This section regroups useful notes and procedures about the introduced breaking change.

Notes

Database lifecycle hooks triggered by the Document Service API methods

Depending on the Document Service API methods called, the following database lifecycle hooks are triggered:

Document Service API method	Triggered database lifecycle hook(s)
findOne()	before(after) findOne
findFirst()	before(after) findOne
findMany()	before(after) findMany
create()	before(after) Create
create({ status: 'published' })	before(after) Create️ Triggered twice as it creates both the draft and published versions before(after) Delete Deletes previous draft versions of a document Can be triggered multiple times if deleting multiple locales (one per each locale)
update()	before(after) Create when creating a new locale on a document before(after) Update when updating an existing version of a document
update({ status: 'published' })	before(after) Create Can be triggered multiple times if deleting multiple locales (one per each locale) before(after) Update when updating an existing version of a document before(after) Delete Deletes previous published versions of a document Can be triggered multiple times if deleting multiple locales (one per each locale)
delete()	before(after) Delete Can be triggered multiple times if deleting multiple locales (one per each locale)
publish()	before(after) Create Can be triggered multiple times if deleting multiple locales (one per each locale) before(after) Delete Deletes previous published versions of a document Can be triggered multiple times if deleting multiple locales (one per each locale)
unpublish()	before(after) Delete Deletes all published versions of a document Can be triggered multiple times if deleting multiple locales (one per each locale)
discardDraft()	before(after) Create Creates new draft versions Can be triggered multiple times if deleting multiple locales (one per each locale) before(after) Delete Deletes previous draft versions of a document Can be triggered multiple times if deleting multiple locales (one per each locale)
count()	before(after) Count

✏️ Note

Bulk actions lifecycles (createMany, updateMany, deleteMany) will never be triggered by a Document Service API method.

Manual procedure

Users might need to adapt their custom code to how lifecycle hooks are triggered by Document Service API methods in Strapi 5.