Why Consistency Decisions Should Start From the Business Invariant

package com.bank.model;

/**
 * Business invariants for National Bank of India.
 * Each one determines the consistency model for its data.
 */
public class BusinessInvariants {

    // HARD INVARIANTS (strong consistency required)
    // "The available balance must never go negative."
    // "A loan must not be disbursed twice."
    // "The last item in stock must not be sold to two customers."

    // SOFT/COSMETIC (eventual consistency acceptable)
    // "The activity feed can lag a few seconds."
    // "The profile picture can be stale briefly after an update."
    // "The like count can be approximate."
    // "Recently viewed items can be eventually consistent."
}

package com.bank.service;

import java.math.BigDecimal;
import java.sql.*;
import java.util.logging.Logger;

/**
 * Wrong: using eventual consistency for balance.
 * Two concurrent withdrawals can both succeed,
 * driving the balance negative.
 */
public class UnsafeWithdrawalService {

    private static final Logger LOG = Logger.getLogger(
        UnsafeWithdrawalService.class.getName());

    public void withdraw(Connection conn, String accountId, BigDecimal amount)
            throws SQLException {
        // Read from a (potentially stale) replica
        BigDecimal balance = readFromReplica(accountId);

        if (balance.compareTo(amount) >= 0) {
            // Both threads pass this check with stale balance
            String sql = "UPDATE accounts SET balance = balance - ? "
                       + "WHERE account_id = ?";
            try (PreparedStatement ps = conn.prepareStatement(sql)) {
                ps.setBigDecimal(1, amount);
                ps.setString(2, accountId);
                ps.executeUpdate();
            }
        }
        // BUG: balance can go negative under concurrent access
    }

    private BigDecimal readFromReplica(String accountId) {
        // Simulated stale read from an AP replica
        return new BigDecimal("50000.00");
    }
}

package com.bank.service;

import java.math.BigDecimal;
import java.sql.*;
import java.util.logging.Logger;

/**
 * Correct: strong consistency for balance.
 * Uses the primary with a CHECK constraint.
 */
public class SafeWithdrawalService {

    private static final Logger LOG = Logger.getLogger(
        SafeWithdrawalService.class.getName());

    public boolean withdraw(Connection conn, String accountId, BigDecimal amount)
            throws SQLException {
        // Read-and-write on the primary with FOR UPDATE lock
        String sql = "UPDATE accounts SET balance = balance - ? "
                   + "WHERE account_id = ? AND balance >= ?";
        try (PreparedStatement ps = conn.prepareStatement(sql)) {
            ps.setBigDecimal(1, amount);
            ps.setString(2, accountId);
            ps.setBigDecimal(3, amount);
            int rows = ps.executeUpdate();
            if (rows == 0) {
                LOG.warning("Insufficient balance for " + accountId);
                return false;
            }
            return true;
        }
        // The CHECK (balance >= 0) constraint on the table
        // is the final safety net even if the WHERE is bypassed.
    }
}

-- Strong consistency: balance ledger on PostgreSQL
CREATE TABLE accounts (
    account_id   VARCHAR(20) PRIMARY KEY,
    holder_name  VARCHAR(100) NOT NULL,
    balance      NUMERIC(15,2) NOT NULL DEFAULT 0.00,
    CONSTRAINT chk_balance_non_negative CHECK (balance >= 0)
);

-- The CHECK constraint is the database-level invariant enforcement.
-- No amount of application logic can bypass it.

package com.bank.service;

import java.math.BigDecimal;
import java.sql.*;
import java.util.logging.Logger;

public class TransferWithSplitConsistency {

    private static final Logger LOG = Logger.getLogger(
        TransferWithSplitConsistency.class.getName());

    private final Connection primaryConn;  // CP: strong consistency

    public TransferWithSplitConsistency(Connection primaryConn) {
        this.primaryConn = primaryConn;
    }

    public void transfer(String sourceId, String targetId, BigDecimal amount)
            throws SQLException {
        // STEP 1: Strongly consistent (CP)
        // Debit and credit in one ACID transaction on the primary
        primaryConn.setAutoCommit(false);
        try {
            debit(sourceId, amount);
            credit(targetId, amount);
            insertOutboxEvent(sourceId, targetId, amount);
            primaryConn.commit();
            LOG.info("Transfer committed: " + amount);
        } catch (SQLException e) {
            primaryConn.rollback();
            throw e;
        }

        // STEP 2: Eventually consistent (AP)
        // Outbox event is picked up by a Kafka publisher
        // Feed, notification, and analytics services consume it
        // A few seconds of lag is acceptable
    }

    private void debit(String accountId, BigDecimal amount) throws SQLException {
        String sql = "UPDATE accounts SET balance = balance - ? "
                   + "WHERE account_id = ? AND balance >= ?";
        try (PreparedStatement ps = primaryConn.prepareStatement(sql)) {
            ps.setBigDecimal(1, amount);
            ps.setString(2, accountId);
            ps.setBigDecimal(3, amount);
            if (ps.executeUpdate() == 0) {
                throw new SQLException("Insufficient balance: " + accountId);
            }
        }
    }

    private void credit(String accountId, BigDecimal amount) throws SQLException {
        String sql = "UPDATE accounts SET balance = balance + ? WHERE account_id = ?";
        try (PreparedStatement ps = primaryConn.prepareStatement(sql)) {
            ps.setBigDecimal(1, amount);
            ps.setString(2, accountId);
            ps.executeUpdate();
        }
    }

    private void insertOutboxEvent(String source, String target, BigDecimal amount)
            throws SQLException {
        String sql = "INSERT INTO outbox (event_type, payload) VALUES (?, ?)";
        try (PreparedStatement ps = primaryConn.prepareStatement(sql)) {
            ps.setString(1, "TRANSFER_COMPLETED");
            ps.setString(2, source + ":" + target + ":" + amount);
            ps.executeUpdate();
        }
    }
}