Distributed Transactions and Sagas: Managing Consistency in Laravel

Previously in this course, we explored Event-Driven Architecture to decouple our services. While events provide great flexibility, they introduce the "dual write" problem: how do we ensure a database update and an event dispatch happen atomically? When your operations span multiple microservices, you cannot use standard database transactions.

This lesson introduces the Saga pattern as the primary solution for maintaining consistency in distributed systems without relying on the brittle and non-scalable two-phase commit (2PC) protocol.

Understanding the Saga Pattern

In a monolithic application, you wrap multiple database operations in a single DB::transaction. In a distributed environment, your services own separate databases. A "Distributed Transaction" is effectively impossible to enforce across network boundaries.

A Saga is a sequence of local transactions. Each local transaction updates a database and publishes an event or message to trigger the next local transaction in the saga. If a local transaction fails, the saga executes a series of compensating actions that undo the changes made by the preceding local transactions.

The Saga Lifecycle

1. Execution: The saga coordinator triggers local transactions sequentially.
2. Failure: If a step fails, the coordinator initiates the rollback sequence.
3. Compensation: Each completed step is "undone" by a specific compensating action (e.g., if you charged a credit card, the compensation is a refund).

Implementing a Saga in Laravel

For our SaaS platform, let’s consider a common workflow: User Subscription.

1. Create a User record.
2. Provision a Cloud Workspace.
3. Charge the User's credit card.

If the payment fails, we must delete the workspace and remove the user.

Defining the Orchestrator

We’ll use an Orchestrator class to manage the state and flow.

PHP
namespace App\Modules\Billing\Sagas;

use App\Modules\Billing\Actions\CreateUser;
use App\Modules\Billing\Actions\ProvisionWorkspace;
use App\Modules\Billing\Actions\ChargeCustomer;

class SubscriptionSaga
{
    public function execute(array $data)
    {
        try {
            $user = CreateUser::run($data);
            $workspace = ProvisionWorkspace::run($user);
            ChargeCustomer::run($user, $data['amount']);
        } catch (\Exception $e) {
            $this->compensate($user, $workspace ?? null);
            throw $e;
        }
    }

    protected function compensate($user, $workspace)
    {
        if ($workspace) {
            #6A9955">// Logic to delete workspace
        }
        if ($user) {
            #6A9955">// Logic to delete user
        }
    }
}

Worked Example: Compensating Actions

In production, you don't run these synchronously in a controller. You use a state machine or a job-based orchestrator. Let’s refine our ChargeCustomer failure scenario using a dedicated Job.

PHP
#6A9955">// Inside our SubscriptionSaga orchestrator
public function handleFailure($step, $payload)
{
    match($step) {
        'payment' => $this->refundPayment($payload),
        'workspace' => $this->deprovisionWorkspace($payload),
        'user' => $this->deleteUser($payload),
    };
}

Every action must have a corresponding "anti-action." If you cannot guarantee the compensation will succeed (e.g., an API is down), you must queue the compensation to retry until it succeeds, ensuring eventual consistency. Refer to Idempotency keys in databases to ensure that retrying a compensation doesn't result in double-refunds.

Hands-on Exercise

1. Create a CompensatableAction interface with a compensate() method.
2. Refactor the SubscriptionSaga to iterate through an array of actions.
3. If an action throws an exception, loop backward through the completed actions and trigger their compensate() methods.

Common Pitfalls

• Non-Idempotent Compensations: If your compensation logic (like an API call) isn't idempotent, a network retry might cause a secondary failure. Always check the state of the target resource before acting.
• Lack of Monitoring: Sagas can get "stuck." Without a dashboard to track the status of a saga (e.g., Pending, Failed, Compensating), you will lose visibility into orphaned data.
• The "Dirty Read" Problem: Because Sagas are eventually consistent, other parts of your system might see a "Provisioned Workspace" before the "Payment" has actually cleared. Design your UI to handle "Pending" states rather than showing immediate success.

Recap

The Saga pattern replaces distributed transactions by breaking complex flows into discrete, reversible steps. By defining clear compensating actions, you ensure your system returns to a consistent state even when individual services fail. As we move forward, we will look at how to make these events reliable even if the broker goes down.

Up next: Eventual Consistency Patterns — where we implement the Outbox pattern to guarantee event delivery.