AdonisJS: When to Use Lucid Transactions for Multi-Step Writes

The Problem: Partial State After a Failed Multi-Step Write

When a single HTTP request creates several related database rows—an order, its line items, and a stock decrement—a failure halfway through leaves orphaned records and inconsistent data. The useful takeaway is to wrap only those related writes in a database transaction, and to keep that boundary inside a service layer, not inside the controller.

Requirements Before Adding a Transaction

Define atomicity for the feature. Ask: if step three fails, must steps one and two be undone? If the answer is no, a transaction adds lock contention and complexity without benefit. Simple creates, updates, or deletes that touch one table can stay outside a transaction.

Smallest Suitable Design

Start with one model per write. Introduce a transaction only when the business rule requires all-or-nothing behavior across multiple models. In AdonisJS with Lucid, a database transaction is a unit of work that either fully commits or fully rolls back. The transaction object is passed through the query client so every statement in the group shares the same database connection.

Example: Creating an Order with Line Items

Run node ace make:service Order from the project root. No special permissions are required. The generated file lives in app/services/. This example assumes AdonisJS 6 with Lucid ORM; verify the exact transaction API against your installed Lucid version.

import { inject } from '@adonisjs/core'
import { Database } from '@adonisjs/lucid/database'
import Order from '#models/order'
import OrderItem from '#models/order_item'

@inject()
export default class OrderService {
  constructor(protected db: Database) {}

  async createOrder(input: {
    customerId: string
    items: { productId: string; quantity: number }[]
  }) {
    return this.db.transaction(async (trx) => {
      const order = await Order.create(
        { customerId: input.customerId },
        { client: trx }
      )

      await Promise.all(
        input.items.map((item) =>
          OrderItem.create(
            { orderId: order.id, productId: item.productId, quantity: item.quantity },
            { client: trx }
          )
        )
      )

      return order
    })
  }
}

The controller should never call db.transaction directly. It validates the request, then hands the sanitized input to the service. If the service throws, the transaction rolls back automatically; if it resolves, the transaction commits.

Trust and Data Boundaries

The trust boundary sits between the HTTP layer and the service layer. The controller treats the request body as untrusted and runs it through AdonisJS validators. The service layer treats the validated input as trusted but still enforces database constraints. The transaction boundary is the service boundary: the controller does not know whether a transaction is used.

Operational Checks

• Watch for database deadlock errors when concurrent requests touch the same rows inside transactions. Lock contention happens when multiple operations wait for the same row or table lock.
• Log transaction duration. Long-running transactions hold connections and can exhaust the connection pool.
• Check that failed requests do not leave partial rows by querying the related tables after a known failure.

Failure Modes

Conditions That Change the Design

Limitations and How to Check the Result

Transactions do not fix invalid business logic; they only guarantee that the database moves from one consistent state to another or stays put. They also do not protect against errors in non-database systems, such as a third-party API call made inside the transaction block.

Practical check: write a test that makes the second insert fail—for example, by violating a foreign key—and assert that the first insert is not visible afterward. If the first row persists, the transaction boundary is misplaced or the query client was not passed correctly.