ACID Transactions

    A transaction is a sequence of operations performed as a single logical unit of work. A transaction has four key properties - Atomicity, Consistency, Isolation and Durability - commonly abbreviated as ACID.

    • Atomicity All the work in a transaction is treated as a single atomic unit - either all of it is performed or none of it is.

    • Consistency A completed transaction leaves the database in a consistent internal state. This can either be all the operations in the transactions succeeding or none of them succeeding.

    • Isolation This property determines how/when changes made by one transaction become visible to the other. For example, a serializable isolation level guarantees that two concurrent transactions appear as if one executed after the other (i.e. as if they occur in a completely isolated fashion). Currently, YugabyteDB supports Snapshot Isolation, and Serializable isolation level is in progress. Read more about the different levels of isolation.

    Here is an example of how to create a simple key-value table which has two columns with transactions enabled.

    1. String create_stmt =
    2.   String.format("CREATE TABLE IF NOT EXISTS %s (k varchar, v varchar, primary key (k)) " +
    3.                 "WITH transactions = { 'enabled' : true };",
    4.                 tablename);

    You can insert data by performing the sequence of commands inside a BEGIN TRANSACTION and END TRANSACTION block.

    Here is a code snippet of how you would insert data into this table.

    1. // Insert two key values, (key1, value1) and (key2, value2) as a transaction.
    2. String create_stmt = 
    3.   String.format("BEGIN TRANSACTION" +
    5.                 "  INSERT INTO %s (k, v) VALUES (%s, %s);" +
    6.                 "END TRANSACTION;",
    7.                 tablename, key2, value2;

    You can prepare statements with transactions and bind variables to the prepared statements when executing the query.

    You can find a working example of using transactions with Yugabyte in our sample applications. This application writes out string keys in pairs, with each pair of keys having the same value written as a transaction. There are multiple readers and writers that update and read these pair of keys. The number of reads and writes to perform can be specified as a parameter.

    1. Usage:
    2.   java -jar yb-sample-apps.jar \
    3.     --workload CassandraTransactionalKeyValue \
    4.     --nodes 127.0.0.1:9042
    7.       [ --num_unique_keys 1000000 ]
    8.       [ --num_reads -1 ]
    9.       [ --num_writes -1 ]
    10.       [ --value_size 0 ]
    11.       [ --num_threads_write 2 ]

    Browse the to see how everything fits together.

    By default, the original Cassandra Java driver and the YugabyteDB Cassandra Java driver use com.datastax.driver.core.policies.DefaultRetryPolicywhich can retry requests upon timeout on client side.

    Automatic retries can break linearizability of operations from the client point of view.Therefore we have added com.yugabyte.driver.core.policies.NoRetryOnClientTimeoutPolicy which inherits behavior from DefaultRetryPolicy with oneexception - it results in an error in case the operation times out (with the OperationTimedOutException).

    Under network partitions, this can lead to the case when client gets a successful response to retried request and treatsthe operation as completed, but the value might get overwritten by an older operation due to retries.

    To avoid such linearizability issues, use and handleclient timeouts in the application layer.