Skip to main content
Version: 3.8

Getting Started with ScalarDB

This getting started tutorial explains how to configure your preferred database in ScalarDB and set up a basic electronic money application.

warning

The electronic money application is simplified for this tutorial and isn't suitable for a production environment.

Install a JDK​

Because ScalarDB is written in Java, you must have one of the following Java Development Kits (JDKs) installed in your environment:

note

We recommend using the LTS versions mentioned above, but other non-LTS versions may work.

In addition, other JDKs should work with ScalarDB, but we haven't tested them.

Clone the scalardb repository​

Open a terminal window, and go to your working directory. Then, clone the scalardb repository by running the following command:

$ git clone https://github.com/scalar-labs/scalardb

Then, go to the scalardb/docs/getting-started directory in the cloned repository by running the following command:

$ cd scalardb/docs/getting-started

Set up your database for ScalarDB​

Select your database, and follow the instructions to configure it for ScalarDB.

For a list of databases that ScalarDB supports, see Supported Databases.

Confirm that you have Cassandra installed. If Cassandra isn't installed, visit Downloading Cassandra.

Configure Cassandra​

Open cassandra.yaml in your preferred IDE. Then, change commitlog_sync from periodic to batch so that you don't lose data if a quorum of replica nodes goes down.

Configure ScalarDB​

The following instructions assume that you have properly installed and configured the JDK and Cassandra in your local environment, and Cassandra is running on your localhost.

The scalardb.properties file in the docs/getting-started directory holds database configurations for ScalarDB. The following is a basic configuration for Cassandra. Be sure to change the values for scalar.db.username and scalar.db.password as described.

# The Cassandra storage implementation is used for Consensus Commit.
scalar.db.storage=cassandra

# Comma-separated contact points.
scalar.db.contact_points=localhost

# The port number for all the contact points.
scalar.db.contact_port=9042

# The username and password to access the database.
scalar.db.username=<USER_NAME>
scalar.db.password=<USER_PASSWORD>

Create and load the database schema​

You need to define the database schema (the method in which the data will be organized) in the application. For details about the supported data types, see Data type mapping between ScalarDB and other databases.

For this tutorial, create a file named emoney.json in the scalardb/docs/getting-started directory. Then, add the following JSON code to define the schema.

{
  "emoney.account": {
    "transaction": true,
    "partition-key": [
      "id"
    ],
    "clustering-key": [],
    "columns": {
      "id": "TEXT",
      "balance": "INT"
    }
  }
}

To apply the schema, go to the scalardb Releases page and download the ScalarDB Schema Loader that matches the version of ScalarDB that you are using to the getting-started folder.

Then, run the following command, replacing <VERSION> with the version of the ScalarDB Schema Loader that you downloaded:

$ java -jar scalardb-schema-loader-<VERSION>.jar --config scalardb.properties --schema-file emoney.json --coordinator
note

The --coordinator option is specified because a table with transaction set to true exists in the schema. For details about configuring and loading a schema, see ScalarDB Schema Loader.

Execute transactions and retrieve data in the basic electronic money application​

After loading the schema, you can execute transactions and retrieve data in the basic electronic money application that is included in the repository that you cloned.

The application supports the following types of transactions:

  • Create an account.
  • Add funds to an account.
  • Send funds between two accounts.
  • Get an account balance.
note

When you first execute a Gradle command, Gradle will automatically install the necessary libraries.

Create an account with a balance​

You need an account with a balance so that you can send funds between accounts.

To create an account for customer1 that has a balance of 500, run the following command:

$ ./gradlew run --args="-action charge -amount 500 -to customer1"

Create an account without a balance​

After setting up an account that has a balance, you need another account for sending funds to.

To create an account for merchant1 that has a balance of 0, run the following command:

$ ./gradlew run --args="-action charge -amount 0 -to merchant1"

Add funds to an account​

You can add funds to an account in the same way that you created and added funds to an account in Create an account with a balance.

To add 500 to the account for customer1, run the following command:

$ ./gradlew run --args="-action charge -amount 500 -to customer1"

The account for customer1 will now have a balance of 1000.

Send electronic money between two accounts​

Now that you have created two accounts, with at least one of those accounts having a balance, you can send funds from one account to the other account.

To have customer1 pay 100 to merchant1, run the following command:

$ ./gradlew run --args="-action pay -amount 100 -from customer1 -to merchant1"

Get an account balance​

After sending funds from one account to the other, you can check the balance of each account.

To get the balance of customer1, run the following command:

$ ./gradlew run --args="-action getBalance -id customer1"

You should see the following output:

...
The balance for customer1 is 900
...

To get the balance of merchant1, run the following command:

$ ./gradlew run --args="-action getBalance -id merchant1"

You should see the following output:

...
The balance for merchant1 is 100
...

Reference​

To see the source code for the electronic money application used in this tutorial, see ElectronicMoney.java.