import Intro from '/docs/snippets/breaking-change-page-intro.md'
import MigrationIntro from '/docs/snippets/breaking-change-page-migration-intro.md'

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

In Strapi 5, database lifecycle hooks are triggered differently when using Document Service API methods, varying by operation type and status changes due to the new Draft & Publish system.

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.

Breaking change description#

In Strapi v4

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

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#

Notes#

Database lifecycle hooks triggered by the Document Service API methods {#table}#

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

Manual procedure#

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

:::strapi Additional resources
You might find additional information about lifecycle hooks in .
:::

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

In Strapi 5, database lifecycle hooks are triggered differently when using Document Service API methods, varying by operation type and status changes due to the new Draft & Publish system.

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.

Migration#

Notes#

Database lifecycle hooks triggered by the Document Service API methods {#table}#

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

Manual procedure#

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

:::strapi Additional resources
You might find additional information about lifecycle hooks in .
:::