Transactions

GridGain supports two types of transactions, each optimized for different workloads. The type of transaction you use determines how GridGain handles locks, replication, and coordination across partitions.

GridGain transactions provide full ACID guarantees. Atomicity ensures that either all operations within a transaction succeed or none do - there are no partial updates. Consistency means that transactions maintain all data integrity constraints defined in your schema. Isolation prevents concurrent transactions from interfering with each other, and durability guarantees that once a transaction commits, its changes survive any subsequent failures.

GridGain uses Hybrid Logical Clock (HLC) to assign timestamps to transactions. HLC combines physical clock time with a logical counter, providing consistent timestamp ordering without requiring a centralized timestamp service.

Here is how HLC mechanism works:

This design eliminates the need for a centralized timestamp coordinator, which would be a single point of failure and a performance bottleneck. Instead, timestamps are assigned locally while still maintaining global ordering through the HLC protocol.

Transaction protocol provides bounded tolerance for clock skew. The cluster is configured with a maximum allowed clock skew through the schemaSync.maxClockSkewMillis parameter. All nodes in the cluster must have their clocks synchronized within this threshold, typically through NTP or a similar time synchronization service. If clock skew exceeds this threshold, transaction operations may fail.

GridGain’s MVCC system is what enables read-only transactions to run without acquiring locks. Every time a row is updated, GridGain does not immediately overwrite the old version. Instead, it adds a new version with a timestamp, creating a version chain. When a read-only transaction reads a row, GridGain finds the appropriate version based on the transaction’s read timestamp. This allows read-only transactions to see consistent historical data without blocking concurrent writes.

Old versions are retained for a configurable period and then removed by garbage collection. The default retention is 10 minutes, which you need to consider when planning long-running read-only transactions. If your analytical queries regularly exceed this period, increase the retention time accordingly:

For detailed information about how version chains are stored, managed, and garbage collected, see the Version Storage section of the Data Partitions documentation.

GridGain uses row-level locks to control concurrent access to data. When a read-write transaction modifies a row, it acquires an exclusive lock on that row. This prevents other transactions from reading or modifying that row until the lock is released at commit or rollback time. The locks are managed automatically - your application doesn’t need to explicitly request or release them.

When multiple transactions try to access the same rows, GridGain needs to determine which transaction proceeds and which must wait or abort. The system uses a priority-based scheme where older transactions (those with earlier begin timestamps) have higher priority. If a younger transaction tries to modify a row that an older transaction has locked, the younger transaction is immediately aborted. This prevents deadlocks - circular waits where transactions are each waiting for locks held by the other.

To prevent transactions from holding resources indefinitely, GridGain enforces configurable timeouts. Read-write transactions default to a 30-second timeout, which is appropriate for short-lived transactional operations. Read-only transactions default to a 10-minute timeout to accommodate longer analytical queries.

When a transaction exceeds its timeout, GridGain automatically aborts it, releases all locks, removes any write intents, and returns an error to the application. The timeout values can be adjusted based on your workload characteristics. For example, if you have a fast OLTP workload where all transactions should complete quickly, you might reduce the read-write timeout to 5 seconds to quickly identify problematic queries:

Conversely, if you have long-running analytical queries, you might increase the read-only timeout:

It’s important to keep the timeout configuration aligned with garbage collection settings. The dataAvailabilityTimeMillis should be at least as large as readOnlyTimeoutMillis to ensure that old data versions are not garbage collected while read-only transactions that might need them are still active.

When a transaction modifies data in multiple partitions, GridGain must coordinate the commit across all of them to maintain atomicity. This coordination happens through partition enlistment and the two-phase commit protocol.

As a transaction executes, each partition it writes to is enlisted - added to the list of partitions involved in the transaction. The first partition enlisted becomes the commit partition, which has special responsibilities. It stores the durable transaction state and serves as the authoritative source if the transaction coordinator fails.

During the commit process, the coordinator first generates a commit timestamp and verifies that all the primary replicas involved in the transaction are still valid. This verification checks that the leases have not expired and that the transaction is working with the current partition leaders. Then the coordinator writes the transaction state (committed or aborted) to the commit partition, where it’s replicated through RAFT to ensure durability. If any primary replica involved in the transaction expires, it becomes impossible to commit the transaction.

Once the transaction is durable (either commit or rollback was performed), the coordinator enters the cleanup phase. It sends messages to each enlisted partition instructing them to process their write intents and release locks. For committed transactions, write intents are converted to committed versions. For rolled back transactions, write intents are deleted. This cleanup happens asynchronously - the application receives confirmation as soon as the transaction finish is durable, without waiting for all cleanup operations to complete.

The consensus-based transaction finishing protocol ensures atomicity even in the face of failures. If the coordinator crashes before completing the commit, other nodes detect the failure and query the commit partition to determine the transaction’s final state. If the transaction was committed, the changes are applied everywhere. If it wasn’t committed, the transaction is rolled back and all write intents are removed.

GridGain handles various failure scenarios automatically without requiring administrator intervention. Understanding these failure modes helps you design resilient applications.

If a transaction coordinator node fails while a transaction is in progress, other nodes eventually detect the coordinator is offline and mark the transaction as abandoned. They then query the commit partition to determine what should happen to the transaction. If the transaction reached the point where its final state was written to the commit partition, that state is honored - committed transactions stay committed, aborted transactions stay aborted. If the transaction never reached that point, it’s rolled back to maintain consistency.

If a replica that holds data for a transaction fails, the RAFT protocol automatically handles the failover. The remaining replicas elect a new leader, and because the transaction’s write intents were replicated to the majority, the new leader has all the necessary data to continue. The transaction proceeds normally from the application’s perspective.

If a commit partition group involved in the transaction fails (for example, by losing the quorum), the transaction cannot be finished until the partition group is operational.

When a transaction times out, GridGain automatically cleans up all resources associated with it. The coordinator releases locks, removes write intents, and marks the transaction as aborted. The application receives a timeout error, and depending on your application logic, you can retry the transaction with a longer timeout if needed.

You can monitor active transactions by querying the system views. The system.transactions view shows all currently active transactions, including their begin timestamps and which partitions they’ve enlisted:

GridGain also provides metrics for transaction monitoring. These metrics track the count of active, committed, and aborted transactions, measure lock wait times, and calculate conflict rates. You can use these metrics to identify patterns in transaction behavior and spot potential issues.

Common issues include high abort rates, which typically indicate lock contention between transactions. Review your transaction access patterns to see if transactions are consistently accessing the same hot rows. Timeout errors suggest either that your timeout configuration is too aggressive or that queries need optimization. Slow commits can indicate network latency issues or problems with replication health.