Skip to main content
Version: 3.12

Getting Started with ScalarDB by Using Kotlin

This getting started tutorial explains how to configure your preferred database in ScalarDB and set up a basic electronic money application by using Kotlin. Since Kotlin has Java interoperability, you can use ScalarDB directly from Kotlin.

warning

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

Prerequisites for this sample application​

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

note

This sample application only works with Java 8. However, ScalarDB itself works with Java LTS versions, which means that you can use Java LTS versions for your application that uses ScalarDB. For details on the requirements of ScalarDB, such as which Java versions can be used, see Requirements.

In addition, since you'll be using Docker Compose to run the databases, you must have Docker 20.10 or later with Docker Compose V2 or later installed.

Clone the ScalarDB samples repository​

Open Terminal, then clone the ScalarDB samples repository by running the following command:

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

Then, go to the directory that contains the sample application by running the following command:

cd scalardb-samples/scalardb-kotlin-sample

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 Databases.

Run MySQL locally

You can run MySQL in Docker Compose by using the docker-compose.yml file in the scalardb-samples/scalardb-kotlin-sample directory.

To start MySQL, run the following command:

docker compose up -d mysql

Configure ScalarDB

The database.properties file in the scalardb-samples/scalardb-kotlin-sample directory contains database configurations for ScalarDB. Please uncomment the properties for MySQL in the database.properties file so that the configuration looks as follows:

# For MySQL
scalar.db.storage=jdbc
scalar.db.contact_points=jdbc:mysql://localhost:3306/
scalar.db.username=root
scalar.db.password=mysql

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, a file named schema.json already exists in the scalardb-samples/scalardb-kotlin-sample directory. 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 scalardb-samples/scalardb-kotlin-sample directory.

Then, based on your database, 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 database.properties --schema-file schema.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
...

Stop the database​

To stop the database, stop the Docker container by running the following command:

docker compose down

Reference​

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