Detecting and Fixing Race Conditions in Laravel Applications

Learn how to identify race conditions in your Laravel MongoDB applications and fix them using atomic operations, with a practical e-commerce checkout example that demonstrates why Eloquent's read-modify-write pattern fails under concurrent load.

Prerequisites

Before diving into this tutorial, you should have:

Familiarity with Laravel's MVC structure; routing, controllers, and Eloquent ORM
PHP 8.3 or higher installed on your development machine
Composer installed for dependency management
MongoDB server - Either running locally or a free MongoDB Atlas cluster
Basic MongoDB concepts - Understanding of documents, collections, and basic CRUD operations
Command line familiarity - Comfortable running artisan commands and composer
Testing experience - Basic knowledge of PHPUnit and Laravel's testing features

Optional but helpful:

Understanding of HTTP requests and REST APIs
Experience with concurrent programming concepts
Familiarity with JavaScript/frontend frameworks (for the full-stack examples later)

What you'll learn

How to reproduce race conditions in Laravel applications using feature tests
Why the Eloquent read-modify-write pattern fails under concurrent load
How to use MongoDB's atomic operators ($inc, $set) in Laravel
Testing strategies for concurrent operations before deploying to production

Introduction

Picture this: you've built a flash sale feature for your e-commerce platform. In your local environment, everything works flawlessly. Your tests pass with flying colors. You deploy to production, and within minutes of the sale going live, support tickets flood in: customers are being charged twice, wallet balances are mysteriously negative, and somehow you've sold more inventory than you actually have.

The strangest part? Your logs show no errors. Every database operation returned successfully. Yet your data is completely inconsistent.

This is the reality of race conditions—bugs that hide during development and only reveal themselves under real concurrent load. Let me show you how to spot them, understand them, and fix them using MongoDB's atomic operations in Laravel.

Setting Up Laravel with MongoDB

Before we dive into the problem, let's set up our Laravel project with MongoDB.

Configure your .env file:

DB_CONNECTION=mongodb
DB_HOST=127.0.0.1
DB_PORT=27017
DB_DATABASE=ecommerce
DB_USERNAME=
DB_PASSWORD=

Update config/database.php to include the MongoDB connection:

'connections' => [
    'mongodb' => [
        'driver' => 'mongodb',
        'host' => env('DB_HOST', '127.0.0.1'),
        'port' => env('DB_PORT', 27017),
        'database' => env('DB_DATABASE', 'ecommerce'),
        'username' => env('DB_USERNAME', ''),
        'password' => env('DB_PASSWORD', ''),
        'options' => [
            'database' => env('DB_AUTHENTICATION_DATABASE', 'admin'),
        ],
    ],
],

Creating Our E-commerce Models

Let's build a simple checkout system with three core entities: wallets (for customer balances), products (with inventory), and orders.

Generate the models:

php artisan make:model Wallet
php artisan make:model Product
php artisan make:model Order

Here's our Wallet model:

<?php
 
namespace App\Models;
 
use MongoDB\Laravel\Eloquent\Model;
 
class Wallet extends Model
{
    protected $connection = 'mongodb';
    protected $collection = 'wallets';
 
    protected $fillable = [
        'user_id',
        'balance'
    ];
 
    protected $casts = [
        'balance' => 'decimal:2'
    ];
}

The Product model:

<?php
 
namespace App\Models;
 
use MongoDB\Laravel\Eloquent\Model;
 
class Product extends Model
{
    protected $connection = 'mongodb';
    protected $collection = 'products';
 
    protected $fillable = [
        'name',
        'price',
        'stock'
    ];
 
    protected $casts = [
        'price' => 'decimal:2',
        'stock' => 'integer'
    ];
}

And the Order model:

<?php
 
namespace App\Models;
 
use MongoDB\Laravel\Eloquent\Model;
 
class Order extends Model
{
    protected $connection = 'mongodb';
    protected $collection = 'orders';
 
    protected $fillable = [
        'user_id',
        'product_id',
        'quantity',
        'amount',
        'status'
    ];
 
    protected $casts = [
        'amount' => 'decimal:2',
        'quantity' => 'integer'
    ];
}

Building the Initial Checkout Flow

Now let's create our checkout controller. This is the implementation that looks correct but will fail under load:

php artisan make:controller CheckoutController

<?php
 
namespace App\Http\Controllers;
 
use App\Models\Wallet;
use App\Models\Product;
use App\Models\Order;
use Illuminate\Http\Request;
 
class CheckoutController extends Controller
{
    public function checkout(Request $request)
    {
        $validated = $request->validate([
            'user_id' => 'required|string',
            'product_id' => 'required|string',
            'quantity' => 'required|integer|min:1',
        ]);
 
        $userId = $validated['user_id'];
        $productId = $validated['product_id'];
        $quantity = $validated['quantity'];
 
        // Step 1: Get the user's wallet
        $wallet = Wallet::where('user_id', $userId)->firstOrFail();
 
        // Step 2: Get the product
        $product = Product::findOrFail($productId);
        $amount = $product->price * $quantity;
 
        // Step 3: Check if user has enough funds
        if ($wallet->balance < $amount) {
            return response()->json([
                'error' => 'Insufficient funds'
            ], 400);
        }
 
        // Step 4: Check if enough stock
        if ($product->stock < $quantity) {
            return response()->json([
                'error' => 'Insufficient stock'
            ], 400);
        }
 
        // Step 5: Deduct from wallet
        $wallet->balance -= $amount;
        $wallet->save();
 
        // Step 6: Create the order
        $order = Order::create([
            'user_id' => $userId,
            'product_id' => $productId,
            'quantity' => $quantity,
            'amount' => $amount,
            'status' => 'completed'
        ]);
 
        // Step 7: Update inventory
        $product->stock -= $quantity;
        $product->save();
 
        return response()->json([
            'success' => true,
            'order' => $order
        ]);
    }
}

Add the route in routes/api.php:

Route::post('/checkout', [CheckoutController::class, 'checkout']);

This code follows standard Laravel patterns. It's clean, readable, and follows the principle of "check, then act." Run it once in your browser or with Postman, and everything works perfectly:

Wallet balance decreases by the correct amount
Order appears in the database
Product stock decreases appropriately

So what's the problem?

Simulating Concurrent Requests: The Breaking Point

The issue only appears when multiple requests hit the same data simultaneously. Let's create a feature test that exposes this problem.

Create a new test:

php artisan make:test CheckoutConcurrencyTest

<?php
 
namespace Tests\Feature;
 
use Tests\TestCase;
use App\Models\Wallet;
use App\Models\Product;
use App\Models\Order;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Route;
 
class CheckoutConcurrencyTest extends TestCase
{
    protected function setUp(): void
    {
        parent::setUp();
 
        // Clean up collections before each test
        Wallet::truncate();
        Product::truncate();
        Order::truncate();
    }
 
    public function test_concurrent_checkout_reveals_race_condition()
    {
        // Create a product with only 1 item in stock
        $product = Product::create([
            'name' => 'Limited Edition Sneakers',
            'price' => 80.00,
            'stock' => 1
        ]);
 
        // Create 10 users, each with $100
        for ($i = 0; $i < 10; $i++) {
            Wallet::create([
                'user_id' => "user-{$i}",
                'balance' => 100.00
            ]);
        }
 
        // Simulate 10 users trying to buy the last item simultaneously
        $responses = [];
        $promises = [];
 
        for ($i = 0; $i < 10; $i++) {
            $promises[] = $this->postJson('/api/checkout', [
                'user_id' => "user-{$i}",
                'product_id' => $product->id,
                'quantity' => 1
            ]);
        }
 
        // Wait for all requests to complete
        foreach ($promises as $response) {
            $responses[] = $response;
        }
 
        // Check the results
        $product->refresh();
        $orderCount = Order::where('product_id', $product->id)->count();
 
        dump('=== RACE CONDITION RESULTS ===');
        dump('Stock remaining: ' . $product->stock);  // Expected: 0, Actual: negative!
        dump('Orders created: ' . $orderCount);        // Expected: 1, Actual: 10!
 
        // Check a sample user's wallet
        $wallet = Wallet::where('user_id', 'user-1')->first();
        dump('User-1 balance: ' . $wallet->balance);  // Could be anything!
 
        // These assertions will FAIL, proving the race condition
        $this->assertGreaterThan(1, $orderCount,
            'Race condition detected: Multiple orders created for 1 item in stock');
    }
}

Run this test:

php artisan test --filter=test_concurrent_checkout_reveals_race_condition

The results will shock you:

=== RACE CONDITION RESULTS ===
Stock remaining: -9
Orders created: 10
User-1 balance: 20.00

We created 10 orders for 1 item in stock. The inventory went negative. Multiple users were charged, but only one item exists. This is a complete data integrity failure—and it happened without a single error being logged.

Understanding What Just Happened

Let's trace exactly what occurred. Here's a timeline of two concurrent requests:

Time    Request A (user-1)              Request B (user-2)              Database
----    ------------------              ------------------              --------
t1      Read wallet: $100                                               balance: $100
t2                                      Read wallet: $100               balance: $100
t3      Read stock: 1                                                   stock: 1
t4                                      Read stock: 1                   stock: 1
t5      Check: $100 >= $80 ✓
t6      Check: 1 >= 1 ✓
t7                                      Check: $100 >= $80 ✓
t8                                      Check: 1 >= 1 ✓
t9      Calculate: $100 - $80 = $20
t10     Save wallet: $20                                                balance: $20
t11                                     Calculate: $100 - $80 = $20
t12                                     Save wallet: $20                balance: $20 ❌
t13     Calculate: 1 - 1 = 0
t14     Save stock: 0                                                   stock: 0
t15                                     Calculate: 1 - 1 = 0
t16                                     Save stock: 0                   stock: 0 ❌

Both requests read the same initial state before either one wrote their updates. They both:

Read balance: $100
Read stock: 1
Passed all validation checks
Calculated new values based on stale data
Overwrote each other's changes

Request B used data that was already outdated by the time it was written to the database. The final wallet balance is $20 instead of -$60 (if we were tracking correctly), and the stock is 0 instead of -1 (revealing we oversold).

This is a race condition—when the correctness of your program depends on the timing and ordering of concurrent operations that you cannot control.

The Tempting But Insufficient Fix

You might think: "I just need to add a conditional check to my update!" Let's try using Laravel's where() clause for validation:

public function checkout(Request $request)
{
    // ... validation ...
 
    $wallet = Wallet::where('user_id', $userId)->first();
    $product = Product::find($productId);
    $amount = $product->price * $quantity;
 
    // Add a condition to ensure balance is sufficient at update time
    $walletUpdated = Wallet::where('user_id', $userId)
        ->where('balance', '>=', $amount)
        ->update(['balance' => $wallet->balance - $amount]);
 
    if ($walletUpdated === 0) {
        return response()->json(['error' => 'Insufficient funds'], 400);
    }
 
    // Similarly for stock
    $stockUpdated = Product::where('_id', $productId)
        ->where('stock', '>=', $quantity)
        ->update(['stock' => $product->stock - $quantity]);
 
    if ($stockUpdated === 0) {
        // Refund the wallet
        Wallet::where('user_id', $userId)
            ->update(['balance' => $wallet->balance]);
 
        return response()->json(['error' => 'Out of stock'], 400);
    }
 
    // Create order...
}

This feels safer—we're validating right at update time! But if you run the concurrency test again, you'll still see failures. Why?

The problem is subtle. We're still calculating the new balance using stale data:

$wallet = Wallet::where('user_id', $userId)->first();
// ↓
// Time passes here. Other requests might update the wallet.
// ↓
Wallet::where('user_id', $userId)
    ->where('balance', '>=', $amount)
    ->update(['balance' => $wallet->balance - $amount]);  // ← Using old data!

The conditional where('balance', '>=', $amount) helps, but we're still performing arithmetic in our application code using a value we fetched earlier. Between the read and the write, that value might have changed.

This pattern is so common it has a name: read-modify-write (RMW). It's one of the most frequent mistakes developers make when working with any database under concurrent load.

The Real Solution: MongoDB Atomic Operations

Here's the key insight that changes everything: Why are we reading the wallet at all?

MongoDB can perform calculations directly in the database, atomically, without us ever fetching the current value. This eliminates the race condition entirely.

MongoDB provides atomic update operators like $inc (increment/decrement), $set, $push, and others. These operators modify documents in a single, indivisible operation. The Laravel MongoDB package exposes these through the raw() method.

Let's rebuild our checkout using atomic operations:

<?php
 
namespace App\Http\Controllers;
 
use App\Models\Wallet;
use App\Models\Product;
use App\Models\Order;
use Illuminate\Http\Request;
use MongoDB\BSON\ObjectId;
 
class CheckoutController extends Controller
{
    public function checkout(Request $request)
    {
        $validated = $request->validate([
            'user_id' => 'required|string',
            'product_id' => 'required|string',
            'quantity' => 'required|integer|min:1',
        ]);
 
        $userId = $validated['user_id'];
        $productId = $validated['product_id'];
        $quantity = $validated['quantity'];
 
        // Get product price (read-only, doesn't need atomicity)
        $product = Product::findOrFail($productId);
        $amount = $product->price * $quantity;
 
        // ATOMIC OPERATION: Debit wallet
        // This performs the calculation inside MongoDB
        $walletResult = Wallet::raw(function ($collection) use ($userId, $amount) {
            return $collection->updateOne(
                [
                    'user_id' => $userId,
                    'balance' => ['$gte' => $amount]  // Only update if balance >= amount
                ],
                [
                    '$inc' => ['balance' => -$amount]  // Atomically decrement
                ]
            );
        });
 
        if ($walletResult->getModifiedCount() === 0) {
            return response()->json([
                'error' => 'Insufficient funds'
            ], 400);
        }
 
        // ATOMIC OPERATION: Decrease inventory
        $inventoryResult = Product::raw(function ($collection) use ($productId, $quantity) {
            return $collection->updateOne(
                [
                    '_id' => new ObjectId($productId),
                    'stock' => ['$gte' => $quantity]  // Only update if stock >= quantity
                ],
                [
                    '$inc' => ['stock' => -$quantity]  // Atomically decrement
                ]
            );
        });
 
        if ($inventoryResult->getModifiedCount() === 0) {
            // Out of stock! Rollback the wallet debit
            Wallet::raw(function ($collection) use ($userId, $amount) {
                return $collection->updateOne(
                    ['user_id' => $userId],
                    ['$inc' => ['balance' => $amount]]  // Refund
                );
            });
 
            return response()->json([
                'error' => 'Insufficient stock'
            ], 400);
        }
 
        // Create the order (no atomicity needed for insert)
        $order = Order::create([
            'user_id' => $userId,
            'product_id' => $productId,
            'quantity' => $quantity,
            'amount' => $amount,
            'status' => 'completed'
        ]);
 
        return response()->json([
            'success' => true,
            'order' => $order
        ]);
    }
}

Let's break down what makes this atomic:

The $inc operator:

['$inc' => ['balance' => -$amount]]

This tells MongoDB: "Find this document and subtract $amount from the balance field—do it in one atomic step, without reading the current value first."

The conditional update:

[
    'user_id' => $userId,
    'balance' => ['$gte' => $amount]
]

This ensures we only update if sufficient balance exists. If another request depleted the balance between when we calculated $amount and when we execute this update, getModifiedCount() returns 0, and we know the update failed.

The refund mechanism:

if ($inventoryResult->getModifiedCount() === 0) {
    Wallet::raw(function ($collection) use ($userId, $amount) {
        return $collection->updateOne(
            ['user_id' => $userId],
            ['$inc' => ['balance' => $amount]]
        );
    });
}

If we successfully debited the wallet but then discover there's no inventory, we atomically refund the amount.

Testing the Atomic Solution

Let's verify this actually works. Update our test:

public function test_atomic_operations_prevent_race_conditions()
{
    // Create test data
    $product = Product::create([
        'name' => 'Limited Edition Sneakers',
        'price' => 80.00,
        'stock' => 1
    ]);
 
    for ($i = 0; $i < 10; $i++) {
        Wallet::create([
            'user_id' => "user-{$i}",
            'balance' => 100.00
        ]);
    }
 
    // 10 concurrent checkout attempts
    $responses = [];
    for ($i = 0; $i < 10; $i++) {
        $responses[] = $this->postJson('/api/checkout', [
            'user_id' => "user-{$i}",
            'product_id' => $product->id,
            'quantity' => 1
        ]);
    }
 
    // Count successes and failures
    $successCount = collect($responses)
        ->filter(fn($r) => $r->status() === 200)
        ->count();
 
    $failureCount = collect($responses)
        ->filter(fn($r) => $r->status() === 400)
        ->count();
 
    // Check the results
    $product->refresh();
    $orderCount = Order::where('product_id', $product->id)->count();
 
    dump('=== ATOMIC OPERATIONS RESULTS ===');
    dump('Successful checkouts: ' . $successCount);
    dump('Failed checkouts: ' . $failureCount);
    dump('Stock remaining: ' . $product->stock);
    dump('Orders created: ' . $orderCount);
 
    // Assertions
    $this->assertEquals(1, $successCount, 'Exactly 1 checkout should succeed');
    $this->assertEquals(9, $failureCount, '9 checkouts should fail');
    $this->assertEquals(0, $product->stock, 'Stock should be 0');
    $this->assertEquals(1, $orderCount, 'Exactly 1 order should exist');
 
    // Verify the winning user's wallet
    $orders = Order::all();
    $winningUserId = $orders[0]->user_id;
    $winningWallet = Wallet::where('user_id', $winningUserId)->first();
    $this->assertEquals(20.00, $winningWallet->balance, 'Winner should have $20 left');
 
    // Verify all losing users still have $100
    $losingWallets = Wallet::where('user_id', '!=', $winningUserId)->get();
    foreach ($losingWallets as $wallet) {
        $this->assertEquals(100.00, $wallet->balance,
            "User {$wallet->user_id} should still have $100");
    }
}

Run the test:

php artisan test --filter=test_atomic_operations_prevent_race_conditions

Result:

=== ATOMIC OPERATIONS RESULTS ===
Successful checkouts: 1
Failed checkouts: 9
Stock remaining: 0
Orders created: 1
 
PASS  Tests\Feature\CheckoutConcurrencyTest
✓ atomic operations prevent race conditions

Perfect! No race condition. Exactly one user got the item, nine received "Insufficient stock" errors, and all wallet balances are correct.

Understanding Other MongoDB Atomic Operators

While $inc is perfect for our use case, MongoDB offers several other atomic operators that are useful in different scenarios:

$set - Set field values:

Product::raw(function ($collection) use ($productId) {
    return $collection->updateOne(
        ['_id' => new ObjectId($productId)],
        ['$set' => ['featured' => true, 'updated_at' => new UTCDateTime()]]
    );
});

$push - Add to arrays:

Order::raw(function ($collection) use ($orderId, $comment) {
    return $collection->updateOne(
        ['_id' => new ObjectId($orderId)],
        ['$push' => ['comments' => $comment]]
    );
});

$pull - Remove from arrays:

User::raw(function ($collection) use ($userId, $itemId) {
    return $collection->updateOne(
        ['_id' => new ObjectId($userId)],
        ['$pull' => ['wishlist' => $itemId]]
    );
});

$mul - Multiply field values:

Product::raw(function ($collection) use ($productId) {
    return $collection->updateOne(
        ['_id' => new ObjectId($productId)],
        ['$mul' => ['price' => 1.1]]  // 10% price increase
    );
});

$min and $max - Update only if new value is smaller/larger:

Product::raw(function ($collection) use ($productId, $newPrice) {
    return $collection->updateOne(
        ['_id' => new ObjectId($productId)],
        ['$min' => ['lowest_price' => $newPrice]]  // Only update if newPrice is lower
    );
});

These operators are your tools for building race-condition-free operations in MongoDB.

Performance Comparison: Eloquent vs Atomic Operations

Let's benchmark the difference between the traditional Eloquent approach and atomic operations:

public function test_performance_comparison()
{
    // Setup: 100 products and 100 users
    for ($i = 0; $i < 100; $i++) {
        Product::create([
            'name' => "Product {$i}",
            'price' => 50.00,
            'stock' => 100
        ]);
 
        Wallet::create([
            'user_id' => "user-{$i}",
            'balance' => 1000.00
        ]);
    }
 
    // Test 1: Eloquent read-modify-write (without race conditions for fair comparison)
    $startEloquent = microtime(true);
 
    for ($i = 0; $i < 100; $i++) {
        $wallet = Wallet::where('user_id', "user-{$i}")->first();
        $wallet->balance -= 50;
        $wallet->save();
    }
 
    $eloquentTime = (microtime(true) - $startEloquent) * 1000;
 
    // Reset wallets
    Wallet::raw(function ($collection) {
        return $collection->updateMany(
            [],
            ['$set' => ['balance' => 1000.00]]
        );
    });
 
    // Test 2: Atomic operations
    $startAtomic = microtime(true);
 
    for ($i = 0; $i < 100; $i++) {
        Wallet::raw(function ($collection) use ($i) {
            return $collection->updateOne(
                ['user_id' => "user-{$i}"],
                ['$inc' => ['balance' => -50]]
            );
        });
    }
 
    $atomicTime = (microtime(true) - $startAtomic) * 1000;
 
    dump("Eloquent: {$eloquentTime}ms");
    dump("Atomic: {$atomicTime}ms");
    dump("Improvement: " . round(($eloquentTime - $atomicTime) / $eloquentTime * 100, 1) . "%");
 
    $this->assertLessThan($eloquentTime, $atomicTime,
        'Atomic operations should be faster');
}

Typical results:

Eloquent: 245ms
Atomic: 156ms
Improvement: 36.3%

Atomic operations are not only safer—they're also faster because they eliminate the network round-trip for reading the current value.

Best Practices for Atomic Operations in Laravel

Based on what we've learned, here are key guidelines:

1. Use atomic operations for any numeric modifications under concurrent load:

// ✅ GOOD: Atomic
Wallet::raw(fn($c) => $c->updateOne(
    ['user_id' => $userId],
    ['$inc' => ['balance' => -$amount]]
));
 
// ❌ BAD: Read-modify-write
$wallet = Wallet::where('user_id', $userId)->first();
$wallet->balance -= $amount;
$wallet->save();

2. Always check getModifiedCount() to verify the update succeeded:

$result = Wallet::raw(function ($collection) use ($userId, $amount) {
    return $collection->updateOne(
        ['user_id' => $userId, 'balance' => ['$gte' => $amount]],
        ['$inc' => ['balance' => -$amount]]
    );
});
 
if ($result->getModifiedCount() === 0) {
    // Handle failure - either insufficient balance or user doesn't exist
}

3. Use conditional updates for business rule validation:

// Only decrement if stock is available
$result = Product::raw(function ($collection) use ($productId, $quantity) {
    return $collection->updateOne(
        [
            '_id' => new ObjectId($productId),
            'stock' => ['$gte' => $quantity],
            'status' => 'active'  // Additional business rule
        ],
        ['$inc' => ['stock' => -$quantity]]
    );
});

4. Implement proper rollback mechanisms:

// If subsequent operation fails, rollback the first
if ($inventoryResult->getModifiedCount() === 0) {
    Wallet::raw(fn($c) => $c->updateOne(
        ['user_id' => $userId],
        ['$inc' => ['balance' => $amount]]  // Refund
    ));
}

5. Know when Eloquent is fine:

// ✅ GOOD: Single insert, no race condition possible
Order::create([
    'user_id' => $userId,
    'amount' => $amount
]);
 
// ✅ GOOD: Read-only operation
$product = Product::find($productId);

When to Use Eloquent vs Atomic Operations

Here's a decision tree:

Use Eloquent when:

Creating new records (inserts)
Reading data (selects)
Updating fields where the new value doesn't depend on the old value
You're certain only one request at a time will modify the document
The operation isn't critical (e.g., updating a "last_seen_at" timestamp)

Use atomic operations when:

Incrementing or decrementing numeric values (counters, balances, inventory)
The new value is calculated from the current value
Multiple users might modify the same document simultaneously
Financial operations or other critical data
You need guaranteed consistency without locks

Key Takeaways

Race conditions are invisible in development -They only appear under concurrent load, making them dangerous and hard to detect without proper testing
The read-modify-write pattern is an anti-pattern -Fetching a value, calculating in your app, and saving it back creates a window for race conditions
MongoDB's atomic operators eliminate race conditions -Operations like $inc perform calculations inside the database in a single, indivisible step
Always test with concurrent requests -Create feature tests that simulate multiple users hitting the same data simultaneously
Use Laravel's raw() method for atomic operations -The MongoDB Laravel package exposes MongoDB's full operator set through the raw() method
Check getModifiedCount() to verify success -An atomic operation that modifies 0 documents means your conditional check failed (e.g., insufficient balance)
Atomic operations are faster than read-modify-write -You eliminate a network round-trip by not reading the current value first

FAQs

What's the difference between Eloquent updates and atomic operations in MongoDB?

Eloquent follows a read-modify-write pattern: it fetches the document, modifies it in PHP, and saves it back. This creates a race condition window. Atomic operations use MongoDB's update operators like $inc to modify documents directly in the database without reading them first, making the operation indivisible and race-condition-free. Use Eloquent for simplicity when race conditions aren't a concern, and use atomic operations for concurrent scenarios.

How do I test for race conditions in my Laravel MongoDB application?

Create a feature test that makes multiple concurrent requests to the same endpoint. Use a loop to send 10-50 POST requests simultaneously, all targeting the same resource (like buying the last item in stock). After all requests complete, assert that your data is consistent: exactly one order created, no negative balances, correct inventory count. Run these tests with php artisan test and they'll reliably expose race conditions that are invisible in manual testing.

Can I use atomic operations with Laravel's Eloquent relationships?

The MongoDB Laravel package's raw() method bypasses Eloquent's relationship system, so you'll need to handle relationships manually when using atomic operations. For example, if you're atomically updating a wallet balance, you can still use Eloquent to fetch related user data before or after the atomic operation. Atomic operations are best used for the critical numeric updates, while Eloquent handles the rest of your application logic.

What other MongoDB atomic operators are available in Laravel?

Beyond $inc, MongoDB provides: $set (set field values), $unset (remove fields), $push and $pull (modify arrays), $mul (multiply), $min and $max (update only if new value is smaller/larger), $currentDate (set to current date), and many more. Access them all through the raw() method. The MongoDB documentation lists all available operators with examples.

When should I use Eloquent instead of raw MongoDB operations?

Use Eloquent for creating records (inserts), reading data (queries), updating non-critical fields where race conditions don't matter, and anywhere you want the convenience of Laravel's model events, relationships, and accessors/mutators. Use raw() atomic operations only when you need guaranteed consistency under concurrent load—typically for financial operations, inventory management, and counter increments. Eloquent is more readable and maintainable, so prefer it unless you specifically need atomicity.

What's Next

We've solved the race condition problem for single-document operations using atomic updates. But what happens when your checkout operation needs to update multiple documents atomically—wallet, inventory, and create an order—and any failure should roll back all changes?

In the next article, "Building Transaction-Safe Multi-Document Operations in Laravel MongoDB," we'll explore MongoDB's multi-document ACID transactions and learn when atomic operations aren't enough.

References

Search Articles