How to Get Started with Scalar DB

In Scalar DB: Universal transaction manager, we explained an overview of Scalar DB and its transaction protocol called Consensus Commit. This article explains how to use Scalar DB using the Java interface.

Sample Application

You are building a simple EC application where you can order items and pay with a credit card using Scalar DB. In this article, you create the application on Cassandra. Even though Cassandra does not provide ACID transaction capability, you can achieve ACID transactions on Cassandra by accessing Cassandra through Scalar DB. Please note that application-specific error handling, authentication processing, etc., are omitted in the sample application since this article focuses on explaining how to use Scalar DB.

You can get all the source code and configuration files on the following page. Please take a look if you want to run the application.

https://github.com/scalar-labs/scalardb-samples/tree/main/scalardb-sample

Schema

The schema for the sample application is as follows:

ER diagram for the schema

All tables are created in the sample namespace.

The customers table manages customers’ information. The credit_limit is the maximum amount of money a lender will allow each customer to spend using a credit card. The credit_total is the amount of money each customer has already spent using the credit card.

The orders table manages orders’ information, and the statements table manages the statements’ information of the orders. Finally, the items table manages items’ information to be ordered.

Transactions

You are going to create the following transactions:

1. Getting customer information
2. Placing an order. An order is paid by a credit card. It first checks if the amount of the money of the order exceeds the credit limit. If the check passes, it records order histories and updates the credit_total
3. Repayment. It reduces the amount of credit_total

Getting Started with Scalar DB

This section explains the steps to create the sample application.

Step 1. Create a configuration file

First, you need to create a configuration file (the file name is “database.properties” in this case) to connect to the database. We assume that Cassandra is set up on the localhost. The configuration file is as follows:

database.properties

You use Consensus Commit with Snapshot Isolation which is the default, so you don’t need to include those settings.

Step 2. Create the schema

The next step is to create the schema. Scalar DB uses a tool called Schema Loader to create the schema. We can download Schema Loader in the following GitHub release page. You will use Scalar DB 3.6.0 here.

https://github.com/scalar-labs/scalardb/releases

Then you need to create a schema file (the file name is “schema.json” in this case) to define the schema. The schema file is written in JSON format. This article will not discuss data modeling for Scalar DB, but we will introduce it at another time. The schema file is as follows:

schema.json

Then you run the Schema Loader to create the schema as follows:

# java -jar scalardb-schema-loader-3.6.0.jar --config database.properties --schema-file schema.json --coordinator --replication-factor 1

For more information about the Schema Loader, please see the following document:

https://github.com/scalar-labs/scalardb/blob/master/schema-loader/README.md

Step 3. Implement the transactions

The Java library for Scalar DB is available on Maven Central. When you use it from Gradle or Maven, you can specify the dependency as follows (you use Scalar DB 3.6.0):

For Gradle:

For Maven:

Once you have specified the dependency, you are ready to implement the transactions.

Create a transaction manager instance

You first need to create an instance of the transaction manager to execute transactions in Scalar DB. The following code allows you to create an instance of the transaction manager (DistributedTransactionManager). Here, you create an instance of the transaction manager with the configuration file created in Step 1.

Implement the transactions

1. Getting customer information

The “Getting customer information” transaction is as follows:

In a Scalar DB transaction, you can have multiple CRUD operations between `start()` and `commit()`, and the operations are atomically executed. You can also abort the transaction to roll back already issued operations if an error occurs during the transactions. Please see the following documentation for more details about how to handle exceptions in Scalar DB:

https://github.com/scalar-labs/scalardb/blob/master/docs/api-guide.md#handle-exceptions

Note that you need to commit a transaction even if it is a read-only transaction due to the transaction protocol. This is a little tricky part of Scalar DB because some of the commercial databases don’t force users to do it.

2. Placing an order

The “Placing an order” transaction is as follows. The arguments of the placeOrder method are a customer ID (customerId), which items to order (itemIds), and how many items to order (itemCounts):

This transaction performs read operations and write operations to multiple tables. Performing these operations against Cassandra without Scalar DB may produce unexpected outcomes. For example, if one of the write operations fails halfway through, the database could go to inconsistent states. Moreover, if multiple orders were placed simultaneously, a credit total could exceed the corresponding credit limit.

3. Repayment

Finally, the “Repayment” transaction is as follows:

This transaction retrieves the current credit total usage from the customers table and updates it by subtracting the repayment amount. If Scalar DB is not used and multiple repayment operations are executed concurrently, some of the repayment operations could be overwritten by the others, which is known as lost update.

Summary

In this article, we explained how to use Scalar DB using the Java interface through the development of an example EC application. We also discussed some of the issues (anomalies) you could face if you don’t use ACID transactions.

Apart from the Java interface described in this article, you can use Scalar DB Server, which provides gRPC and GraphQL interfaces (commercial license). Since gRPC and GraphQL are language-agnostic, you can choose your favorite language to create a Scalar DB application. Also, Scalar DB SQL interface is currently under development. We will introduce these interfaces at another time.