[Request]: How does strapi entity service work with transactions?

[deltaboukensha]

Summary

I would like to know if strapi entity service works with transactions?

Why is it needed?

Transactions are important

Suggested solution(s)

Document how transactions work with entitity service. And if it does not then please document that.

Related issue(s)/PR(s)

No response

[pwizla]

Hi @deltaboukensha and thank you for the request.
Could you please elaborate on what you mean by "transactions"?
Is it something like this? https://docs.strapi.io/dev-docs/database-transactions

By the way since you mention Entity Service, I wanted to highlight that the Entity Service API will be deprecated in the upcoming Strapi 5.

Meaning that if you want your project to be future-proof, I would like to encourage you to start considering the Document Service API instead. You'll find more info here: https://docs.strapi.io/dev-docs/migration/v4-to-v5/breaking-changes/entity-service-deprecated

However, Strapi v4 will still be supported for roughly 1 year after Strapi 5 is out.

[MaxDiMart]

Hello I would also like to know how to work with transactions correctly. Is it possible to get information or documentation?

[pwizla]

Hi @MaxDiMart, same answer and same question as in my reply to deltaboukensha:

Here's the existing database transactions documentation: https://docs.strapi.io/dev-docs/database-transactions Could you please elaborate on what you need? Do you need this for Strapi v4 or v5?

[saintego]

How Document Service API works with Database transactions?
Is it done, or is there any plan to make it work?
Should I use just strapi.db.query and avoid entityService while it is depricated?
Is there any way how to trigger custom middlewares, while updating in db.transcation?

[github-actions]

🤖 I've analyzed your question and here's what I found:

Thanks a lot for raising this and for thinking about data integrity — you’re absolutely right that transactions are important, and it’s great you’re asking how this works with Strapi’s APIs.

Does the Entity Service work with transactions?

In Strapi v5, transactions are handled through the experimental strapi.db.transaction helper. Any strapi.entityService (and strapi.db.query) calls executed inside a strapi.db.transaction block will automatically participate in that transaction. [Database transactions]

From the docs:

“Every strapi.entityService or strapi.db.query operation performed in a transaction block will implicitly use the transaction.” [Database transactions]

So yes: when you wrap your logic in strapi.db.transaction, your Entity Service operations are executed in a single transaction that will either fully commit or fully roll back.

Basic example

await strapi.db.transaction(async ({ trx, rollback, commit, onCommit, onRollback }) => {
  // All of these will implicitly use the same transaction
  await strapi.entityService.create('api::article.article', {
    data: { title: 'First article in a transaction' },
  });

  await strapi.entityService.create('api::article.article', {
    data: { title: 'Second article in a transaction' },
  });

  // If any of the above throws, the whole transaction is rolled back automatically
});

If any entityService call inside the handler throws an error, Strapi will roll back the transaction and restore the previous state. [Database transactions]

You can also mix in lower-level knex queries by using .transacting(trx) if needed:

await strapi.db.transaction(async ({ trx }) => {
  await strapi.entityService.create('api::article.article', {
    data: { title: 'Created via Entity Service' },
  });

  await knex('some_table')
    .where('id', 1)
    .update({ name: 'foo' })
    .transacting(trx);
});

Using transactions in migrations (Entity Service + services)

The same pattern is used in database migrations when you choose to use the Strapi instance instead of raw knex. The docs explicitly recommend wrapping your migration logic in strapi.db.transaction so that it rolls back correctly on error: [Creating a migration file]

// ./database/migrations/2022.05.10T00.00.00.name-of-my-migration.js
module.exports = {
  async up() {
    await strapi.db.transaction(async () => {
      // Example: creating new entries
      await strapi.entityService.create('api::article.article', {
        data: {
          title: 'My Article',
        },
      });

      // Example: calling a custom service method
      await strapi.service('api::article.article').updateRelatedArticles();
    });
  },
};

Things to keep in mind

• Transactions are experimental in Strapi 5 and the API may evolve. [Database transactions]
• Long or complex transactions can cause locking or stalled connections if they’re not committed/rolled back properly, so they should be used thoughtfully. [Potential problems of transactions]

About documentation

You’re absolutely right that this behavior should be clearly documented in relation to the Entity Service. Right now, the main explanation lives in the Database transactions page rather than on the Entity Service page itself. [Database transactions; Entity Service API]

As a next step, it would be very helpful if you could also add this as a documentation/feature request on our public feedback board so it’s tracked and visible to the team:
https://feedback.strapi.io

If you’d like more real-world examples or want to discuss patterns, the community on the Forum and Discord is also a great place to continue the conversation. [Community & Support]

Thanks again for taking the time to ask for clarification — feedback like this helps us improve both the product and the docs.

📚 Relevant documentation:

• Community & Support
• Creating components and dynamic zones with the Entity Service API
• CRUD operations with the Entity Service API
• CRUD operations with the Entity Service API - update()
• Database migrations
• Database migrations - Creating a migration file
• Database transactions
• Database transactions - Potential problems of transactions
• Entity Service API
• Entity Service deprecated
• Filtering with the Entity Service API
• Ordering and Paginating with the Entity Service API
• Populating with the Entity Service API
• Services - Usage
• Strapi Support Policy - Community resources

---

ℹ️ This response was generated automatically. If this doesn't fully answer your question or if you need further assistance, please mention @pwizla in a comment and a human maintainer will help you.

You can also try our interactive AI chat for more detailed assistance.

💡 For feature requests or product feedback, visit feedback.strapi.io.