Eliminating Race Conditions in Clustered Spring Boot with PostgreSQL Advisory Locks

It’s 02:14 AM. Your alert manager fires: an account balance dropped below zero, or a user received two trial credits instead of one.

You trace the logs across your Kubernetes cluster. Two pods received near-simultaneous webhook calls for the exact same entity—5 milliseconds apart. Both pods executed:

Pod A: Reads balance ($100) -> Validates -> Dispatches payout -> Updates balance ($0)
Pod B: Reads balance ($100) -> Validates -> Dispatches payout -> Updates balance ($0)

Both pods saw the balance before either could update it. Two payouts occurred; the business took the loss.

If you have spent any time maintaining distributed systems, you know this story. But when teams sit down to fix it, they often leap straight into architectural extremes—either slapping a useless synchronized keyword onto a Spring service method, or dragging in an entire Redis cluster with Redisson just to serialize one critical action.

There is a sweet spot right in front of you. If PostgreSQL is your primary datastore, you already possess a robust distributed lock manager: PostgreSQL Advisory Locks.

Table of Contents

• Why Standard Concurrency Tools Break in a Cluster
• What Are PostgreSQL Advisory Locks?
  • Session-Level vs. Transaction-Level
  • The HikariCP Connection Trap
• The Lock Functions You Need to Know
• Designing a Production-Ready Implementation
  • 1. Generating 64-Bit Keys from Arbitrary Strings
  • 2. The Advisory Lock Repository
  • 3. A Clean Functional Lock Template
  • 4. A Realistic Scenario: First-Time Welcome Reward
• The "Secret Weapon": Lock Timeouts in PostgreSQL
• Verifying Concurrency with Testcontainers
• Production Gotchas and When NOT to Use Them
• Architectural Comparison: Picking the Right Tool
• Summary

Why Standard Concurrency Tools Break in a Cluster

Before looking at advisory locks, let's understand why traditional tools fall short.

sequenceDiagram
    autonumber
    participant Client
    participant Pod1 as Spring Boot (Pod 1)
    participant Pod2 as Spring Boot (Pod 2)
    participant DB as PostgreSQL

    Client->>Pod1: POST /rewards/claim (User 42)
    Client->>Pod2: POST /rewards/claim (User 42)
    Note over Pod1,Pod2: JVM locks (synchronized) only protect within the same node
    Pod1->>DB: SELECT has_claimed FROM rewards WHERE user_id = 42
    Pod2->>DB: SELECT has_claimed FROM rewards WHERE user_id = 42
    DB-->>Pod1: false
    DB-->>Pod2: false
    Pod1->>DB: INSERT INTO rewards (user_id) VALUES (42)
    Pod2->>DB: INSERT INTO rewards (user_id) VALUES (42)
    Note over DB: Race condition! Without constraints, duplicate rows occur.

1. In-Memory JVM Locks (synchronized, ReentrantLock)

Java's native synchronization primitives coordinate threads within a single JVM. The moment you run two pods behind an Application Load Balancer, your in-memory lock table is completely partitioned. Pod 1 knows nothing about Pod 2’s monitors.

2. Pessimistic Row Locking (SELECT ... FOR UPDATE)

Row-level locks are powerful, but they come with two severe limitations:

• The row must already exist. If your task is "create this user’s default ledger account if it doesn't exist yet," there is no row to lock. You get a classic "check-then-act" race.
• Table bloat and domain coupling. Locking a row acquires locks within PostgreSQL’s tuple storage system, locking out concurrent readers/writers on adjacent columns, creating MVCC churn, and coupling business workflows directly to table rows.

3. Redis / Redisson Distributed Locks

Spinning up Redis to handle distributed locking is common, but it introduces:

• Extra operational complexity (failover clusters, sentinel/cluster topology, backup, patching).
• The dual-system failure problem: network partitions between your app, Redis, and PostgreSQL can leave locks dangling or create split-brain states unless you implement fencing tokens correctly.
• Unnecessary infrastructure cost if your PostgreSQL database is already provisioned and has plenty of capacity.

What Are PostgreSQL Advisory Locks?

PostgreSQL advisory locks are application-defined locks managed directly in the database server's memory (shared_buffers / lock table).

The key insight: PostgreSQL doesn’t attach any data semantics to an advisory lock. It doesn't lock a row, a page, or a table. It simply holds an integer key in memory that other connections can check or wait on.

graph TD
    subgraph PostgreSQL Server
        A[Lock Manager Shared Memory]
        B[(Tuples / Tables)]
    end

    subgraph Clients
        P1[Pod 1 Connection]
        P2[Pod 2 Connection]
    end

    P1 -->|pg_try_advisory_xact_lock: 9481029| A
    P2 -.->|pg_try_advisory_xact_lock: 9481029 rejected!| A
    P1 -->|Only writes data after lock is granted| B

Session-Level vs. Transaction-Level

PostgreSQL provides two flavors of advisory locks. Confusing them in a connection-pooled application like Spring Boot will cause catastrophic bugs.

The HikariCP Connection Trap

With HikariCP (Spring Boot’s default pool), physical database connections are reused across different HTTP requests and threads.

If you acquire a session-level lock (pg_advisory_lock) on Connection A and an unhandled exception prevents your unlock code from running, Connection A goes back into the Hikari pool while still holding the lock in Postgres.

Later, another thread picks up Connection A, inheriting the lock. Worse, other threads requesting the lock on other connections hang indefinitely.

For Spring Boot applications, transaction-level advisory locks (pg_advisory_xact_lock) are almost always the correct choice. When Spring’s transaction commits or rolls back, PostgreSQL automatically frees the lock. Even if your pod crashes mid-execution with kill -9, the TCP socket drops, the transaction aborts, and PostgreSQL clears the lock immediately.

The Lock Functions You Need to Know

PostgreSQL exposes a compact family of advisory functions:

1. pg_advisory_xact_lock(bigint): Blocks until the lock is acquired. Automatically released at the end of the current transaction.
2. pg_try_advisory_xact_lock(bigint): Non-blocking. Returns true if acquired immediately, false if another transaction holds it.
3. pg_advisory_xact_lock(integer, integer): 2-part key variant. Useful for composite IDs like (tenant_id, entity_id).

Designing a Production-Ready Implementation

Let's build a clean, idiomatic locking mechanism for Spring Boot.

1. Generating 64-Bit Keys from Arbitrary Strings

PostgreSQL advisory locks accept either a single 64-bit integer (bigint / Java long) or two 32-bit integers (int).

In enterprise applications, we usually want to lock on domain identifiers: "wallet:claim:user_99214" or "order:settle:ORD-2026-901". We need a deterministic, low-collision function to map any String to a long.

A truncated SHA-256 hash or MurmurHash3 works well here:

package com.example.locking.util;

import java.nio.ByteBuffer;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

public final class LockKeyGenerator {

    private LockKeyGenerator() {}

    /**
     * Hashes a string identifier to a 64-bit signed long for PostgreSQL advisory locks.
     */
    public static long toLongKey(String businessKey) {
        if (businessKey == null || businessKey.isBlank()) {
            throw new IllegalArgumentException("Lock key must not be blank");
        }
        try {
            MessageDigest digest = MessageDigest.getInstance("SHA-256");
            byte[] hash = digest.digest(businessKey.getBytes(StandardCharsets.UTF_8));
            // Read the first 8 bytes of the SHA-256 hash as a long
            return ByteBuffer.wrap(hash).getLong();
        } catch (NoSuchAlgorithmException e) {
            throw new IllegalStateException("SHA-256 algorithm missing from JVM", e);
        }
    }
}

What about hash collisions?

A 64-bit space allows for $1.8 \times 10^{19}$ possible values. If two completely unrelated keys collide (which is exceptionally rare), the consequence is benign: one process briefly waits for the other, or fails fast. Data corruption never occurs.

2. The Advisory Lock Repository

Instead of fighting JPA's entity lifecycle, use JdbcTemplate for raw advisory lock calls. It ensures the query runs on the exact physical connection bound to Spring’s active transaction.

package com.example.locking.repository;

import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Repository;

@Repository
public class PostgresAdvisoryLockRepository {

    private final JdbcTemplate jdbcTemplate;

    public PostgresAdvisoryLockRepository(JdbcTemplate jdbcTemplate) {
        this.jdbcTemplate = jdbcTemplate;
    }

    /**
     * Non-blocking attempt to acquire a transaction-scoped advisory lock.
     * Returns true if granted, false if already held by another transaction.
     */
    public boolean tryAcquireTransactionLock(long lockKey) {
        Boolean acquired = jdbcTemplate.queryForObject(
            "SELECT pg_try_advisory_xact_lock(?)",
            Boolean.class,
            lockKey
        );
        return Boolean.TRUE.equals(acquired);
    }

    /**
     * Blocking call to acquire a transaction-scoped advisory lock.
     * Waits until the lock is available.
     */
    public void acquireTransactionLock(long lockKey) {
        jdbcTemplate.queryForObject(
            "SELECT pg_advisory_xact_lock(?)",
            Void.class,
            lockKey
        );
    }
}

3. A Clean Functional Lock Template

Annotations (like @AdvisoryLocked) look nice on paper, but aspect-oriented locks often obscure transaction boundaries. If the lock is acquired before @Transactional begins, or released after it commits, race conditions sneak back in.

A functional template makes the transaction and lock scope explicit:

package com.example.locking.service;

import com.example.locking.exception.LockAcquisitionException;
import com.example.locking.repository.PostgresAdvisoryLockRepository;
import com.example.locking.util.LockKeyGenerator;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;

import java.util.function.Supplier;

@Component
public class AdvisoryLockTemplate {

    private static final Logger log = LoggerFactory.getLogger(AdvisoryLockTemplate.class);

    private final PostgresAdvisoryLockRepository lockRepository;

    public AdvisoryLockTemplate(PostgresAdvisoryLockRepository lockRepository) {
        this.lockRepository = lockRepository;
    }

    /**
     * Executes the supplier within a MANDATORY or NEW transaction holding an advisory lock.
     * Fails fast if the lock cannot be acquired immediately.
     */
    @Transactional(propagation = Propagation.REQUIRED)
    public <T> T executeWithTryLock(String lockKey, Supplier<T> task) {
        long numericKey = LockKeyGenerator.toLongKey(lockKey);
        log.debug("Attempting to acquire lock for key '{}' (hash: {})", lockKey, numericKey);

        boolean acquired = lockRepository.tryAcquireTransactionLock(numericKey);
        if (!acquired) {
            log.warn("Failed to acquire lock for key: {}. Another process is executing.", lockKey);
            throw new LockAcquisitionException("Unable to acquire lock for: " + lockKey);
        }

        log.debug("Lock successfully acquired for key: {}", lockKey);
        try {
            return task.get();
        } finally {
            // Note: pg_advisory_xact_lock is freed automatically when the transaction completes.
            log.debug("Task completed. Lock for key '{}' will release on TX commit/rollback.", lockKey);
        }
    }
}

Custom exception for clean HTTP 409 (Conflict) mappings:

package com.example.locking.exception;

public class LockAcquisitionException extends RuntimeException {
    public LockAcquisitionException(String message) {
        super(message);
    }
}

4. A Realistic Scenario: First-Time Welcome Reward

Let’s look at a realistic use case: granting a first-time signup bonus or wallet reward.

Two requests hit different pods at the same time. The user record has no reward row yet, so SELECT ... FOR UPDATE cannot help us.

sequenceDiagram
    autonumber
    participant Pod1 as Pod 1 (Lock Acquired)
    participant Pod2 as Pod 2 (Lock Denied)
    participant DB as Postgres Lock Manager

    Pod1->>DB: SELECT pg_try_advisory_xact_lock(hash("wallet:reward:user-100"))
    DB-->>Pod1: true (Lock Granted)

    Pod2->>DB: SELECT pg_try_advisory_xact_lock(hash("wallet:reward:user-100"))
    DB-->>Pod2: false (Locked by Pod 1)
    Pod2-->>Pod2: Throw LockAcquisitionException (Fast Fail)

    Pod1->>Pod1: Check if already rewarded (false)
    Pod1->>Pod1: Credit Wallet & Insert Audit Log
    Pod1->>DB: COMMIT Transaction
    DB-->>Pod1: Lock automatically dropped!

Here is the service implementation:

package com.example.rewards.service;

import com.example.locking.service.AdvisoryLockTemplate;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import java.math.BigDecimal;

@Service
public class RewardClaimService {

    private static final Logger log = LoggerFactory.getLogger(RewardClaimService.class);

    private final AdvisoryLockTemplate lockTemplate;
    private final RewardRepository rewardRepository;
    private final WalletService walletService;

    public RewardClaimService(AdvisoryLockTemplate lockTemplate,
                              RewardRepository rewardRepository,
                              WalletService walletService) {
        this.lockTemplate = lockTemplate;
        this.rewardRepository = rewardRepository;
        this.walletService = walletService;
    }

    public RewardClaimResult claimWelcomeBonus(String userId) {
        String lockKey = "reward:claim:welcome:" + userId;

        return lockTemplate.executeWithTryLock(lockKey, () -> {
            // Safe critical section across the entire cluster!
            if (rewardRepository.existsByUserIdAndType(userId, "WELCOME_BONUS")) {
                log.info("User {} already received the welcome bonus", userId);
                return RewardClaimResult.alreadyClaimed();
            }

            log.info("Granting bonus to user {}", userId);
            walletService.credit(userId, new BigDecimal("25.00"));
            rewardRepository.recordClaim(userId, "WELCOME_BONUS");

            return RewardClaimResult.success(new BigDecimal("25.00"));
        });
    }
}

The "Secret Weapon": Lock Timeouts in PostgreSQL

What if you don't want to fail immediately with try_lock, but you also don't want your threads to wait indefinitely and starve your HikariCP pool?

PostgreSQL doesn’t have a pg_advisory_lock_with_timeout(key, duration) function. However, it does have SET LOCAL lock_timeout.

When set inside a transaction, lock_timeout applies to all lock requests in that transaction—including advisory locks!

public void acquireTransactionLockWithTimeout(long lockKey, int timeoutMillis) {
    // 1. Set local timeout for this transaction only
    jdbcTemplate.execute("SET LOCAL lock_timeout = '" + timeoutMillis + "ms'");

    // 2. Will wait up to timeoutMillis; throws PSQLException with SQLState 55P03 if exceeded
    jdbcTemplate.queryForObject("SELECT pg_advisory_xact_lock(?)", Void.class, lockKey);
}

If the lock cannot be acquired within the specified duration, Postgres aborts the lock request with:
ERROR: canceling statement due to lock timeout (SQLState: 55P03)

This gives you a bounded, distributed queue without needing complex polling or backoff logic in Java.

Verifying Concurrency with Testcontainers

You should never trust distributed concurrency code without an integration test that actually fires simultaneous threads against a real PostgreSQL instance.

Here is a full Testcontainers-based test verifying that concurrent requests for the same lock key are cleanly serialized or rejected:

package com.example.locking;

import com.example.locking.exception.LockAcquisitionException;
import com.example.locking.service.AdvisoryLockTemplate;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.DynamicPropertyRegistry;
import org.springframework.test.context.DynamicPropertySource;
import org.testcontainers.containers.PostgreSQLContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

import java.util.concurrent.*;
import java.util.concurrent.atomic.AtomicInteger;

import static org.assertj.core.api.Assertions.assertThat;

@SpringBootTest
@Testcontainers
class AdvisoryLockIntegrationTest {

    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine");

    @DynamicPropertySource
    static void configureProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", postgres::getJdbcUrl);
        registry.add("spring.datasource.username", postgres::getUsername);
        registry.add("spring.datasource.password", postgres::getPassword);
    }

    @Autowired
    private AdvisoryLockTemplate lockTemplate;

    @Test
    @DisplayName("Simultaneous threads on the same key must only allow one execution")
    void testConcurrentAccess() throws Exception {
        int threadCount = 8;
        ExecutorService executor = Executors.newFixedThreadPool(threadCount);
        CountDownLatch readyLatch = new CountDownLatch(threadCount);
        CountDownLatch startLatch = new CountDownLatch(1);

        AtomicInteger successCounter = new AtomicInteger(0);
        AtomicInteger lockDeniedCounter = new AtomicInteger(0);

        String sharedResourceKey = "account:sync:USR-123";

        for (int i = 0; i < threadCount; i++) {
            executor.submit(() -> {
                readyLatch.countDown();
                try {
                    startLatch.await(); // Synchronize thread release

                    lockTemplate.executeWithTryLock(sharedResourceKey, () -> {
                        successCounter.incrementAndGet();
                        // Hold lock briefly to force collision
                        Thread.sleep(100);
                        return null;
                    });
                } catch (LockAcquisitionException e) {
                    lockDeniedCounter.incrementAndGet();
                } catch (Exception e) {
                    // unexpected
                }
            });
        }

        // Wait until all threads are prepped
        readyLatch.await(5, TimeUnit.SECONDS);
        // Fire all threads simultaneously
        startLatch.countDown();

        executor.shutdown();
        boolean completed = executor.awaitTermination(5, TimeUnit.SECONDS);
        assertThat(completed).isTrue();

        // Exactly one thread should succeed; remaining 7 must be rejected
        assertThat(successCounter.get()).isEqualTo(1);
        assertThat(lockDeniedCounter.get()).isEqualTo(threadCount - 1);
    }
}

Production Gotchas and When NOT to Use Them

PostgreSQL advisory locks are powerful, but senior engineers understand where tools fail. Keep these three points in mind:

1. Connection Starvation During Slow External I/O

If your locked critical section makes a slow third-party API call (e.g., waiting 5 seconds for Stripe or PayPal), your application keeps the underlying database connection checked out from HikariCP for that entire duration.

graph LR
    subgraph Anti-Pattern
        A[Acquire Advisory Lock] --> B[Hold DB Connection]
        B --> C[Wait for Slow 3rd Party HTTP API 3-5s]
        C --> D[HikariCP Pool Starvation!]
    end

Rule of thumb: Keep advisory-locked transactions lean. Execute validation, DB writes, and state transitions inside the lock. If you must call an external API, consider optimistic state transitions (e.g., status = PENDING_PAYMENT) committed to the database, or use an external lock manager like Redis if the database connection pool cannot absorb the latency.

2. PgBouncer and Transaction Pooling

If you use PgBouncer in front of PostgreSQL:

• Session-level locks (pg_advisory_lock) are broken in pool_mode = transaction. PgBouncer may assign subsequent queries in the same client session to different Postgres server backends!
• Transaction-level locks (pg_advisory_xact_lock) work flawlessly because PgBouncer pins the client to a single physical backend connection for the exact lifetime of the transaction.

3. Postgres Shared Memory Limits

Advisory locks are stored in PostgreSQL's shared memory, governed by max_locks_per_transaction (default typically 64) multiplied by max_connections.

While tens of thousands of active transaction locks are rarely an issue, do not treat advisory locks as long-term persistent flags. They are transient execution guards.

Architectural Comparison: Picking the Right Tool

Summary

Before introducing Redis, ZooKeeper, or Hazelcast to solve distributed race conditions in your Spring Boot services, look closely at your existing PostgreSQL database.

By combining pg_try_advisory_xact_lock with Spring’s @Transactional boundaries:

1. You get true cluster-wide serialization across any number of pods.
2. You eliminate dangling locks through automatic transaction-scoped cleanup.
3. You save your organization from operating and monitoring an additional distributed caching cluster.

Simplicity is an architectural superpower. Sometimes the most resilient solution is the one already running in your stack.