Project: ScalarDB (App Definition and Development / Database)
File: getting-started-with-scalardb.md

This getting started tutorial explains how to configure your preferred database in ScalarDB and set up a basic electronic money application. {% capture notice--warning %} Warning The electronic money application is simplified for this tutorial and isn't suitable for a production environment. {% endcapture %} <div class="notice--warning">{{ notice--warning | markdownify }}</div> Because ScalarDB is written in Java, you must have one of the following Java Development Kits (JDKs) installed in your environment: LTS version (8, 11, or 17) LTS version (8, 11, or 17) {% capture notice--info %} 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. {% endcapture %} <div class="notice--info">{{ notice--info | markdownify }}</div> Open a terminal window, and go to your working directory. Then, clone the repository by running the following command: ```shell $ 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: ```shell $ cd scalardb/docs/getting-started ``` Select your database, and follow the instructions to configure it for ScalarDB. For a list of databases that ScalarDB supports, see . <div id="tabset-1"> <div class="tab"> <button class="tablinks" onclick="openTab(event, 'Cassandra', 'tabset-1')" id="defaultOpen-1">Cassandra</button> <button class="tablinks" onclick="openTab(event, 'CosmosDBfor_NoSQL', 'tabset-1')">Cosmos DB for NoSQL</button> <button class="tablinks" onclick="openTab(event, 'DynamoDB', 'tabset-1')">DynamoDB</button> <button class="tablinks" onclick="openTab(event, 'JDBC_databases', 'tabset-1')">JDBC databases</button> </div> <div id="Cassandra" class="tabcontent" markdown="1"> Confirm that you have Cassandra installed. If Cassandra isn't installed, visit . {:.no_toc} 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. {:.no_toc} 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. ```properties scalar.db.storage=cassandra scalar.db.contact_points=localhost scalar.db.contact_port=9042 scalar.db.username=<USER_NAME> scalar.db.password=<USER_PASSWORD> ``` </div> <div id="CosmosDBfor_NoSQL" class="tabcontent" markdown="1"> To use Azure Cosmos DB for NoSQL, you must have an Azure account. If you don't have an Azure account, visit . {:.no_toc} Set the default consistency level to Strong according to the official document at . {:.no_toc} The following instructions assume that you have properly installed and configured the JDK in your local environment and properly configured your Cosmos DB for NoSQL account in Azure. The scalardb.properties file in the `docs/getting-started` directory holds database configurations for ScalarDB. Be sure to change the values for `scalar.db.contact_points` and `scalar.db.password` as described. ```properties scalar.db.storage=cosmos scalar.db.contactpoints=<COSMOSDBFORNOSQL_URI> scalar.db.password=<COSMOSDBFORNOSQLKEY> ``` {% capture notice--info %} Note You can use a primary key or a secondary key as the value for `scalar.db.password`. {% endcapture %} <div class="notice--info">{{ notice--info | markdownify }}</div> </div> <div id="DynamoDB" class="tabcontent" markdown="1"> To use Amazon DynamoDB, you must have an AWS account. If you don't have an AWS account, visit .

The following instructions assume that you have properly installed and configured the JDK in your local environment. The scalardb.properties file in the `docs/getting-started` directory holds database configurations for ScalarDB. Be sure to change the values for `scalar.db.contact_points`, `scalar.db.username`, and `scalar.db.password` as described. ```properties scalar.db.storage=dynamo scalar.db.contact_points=<REGION> scalar.db.username=<ACCESSKEYID> scalar.db.password=<SECRETACCESSKEY> ``` </div> <div id="JDBC_databases" class="tabcontent" markdown="1"> Confirm that you have a JDBC database installed. For a list of supported JDBC databases, see . {:.no_toc} The following instructions assume that you have properly installed and configured the JDK and JDBC database in your local environment, and the JDBC database 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 JDBC databases. {% capture notice--info %} Note Be sure to uncomment the `scalar.db.contact_points` variable and change the value of the JDBC database you are using, and change the values for `scalar.db.username` and `scalar.db.password` as described. {% endcapture %} <div class="notice--info">{{ notice--info | markdownify }}</div> ```properties scalar.db.storage=jdbc scalar.db.username=<USER_NAME> scalar.db.password=<PASSWORD> ``` </div> </div> 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 . 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. ```json { "emoney.account": { "transaction": true, "partition-key": [ "id" ], "clustering-key": [], "columns": { "id": "TEXT", "balance": "INT" } } } ``` To apply the schema, go to the page and download the ScalarDB Schema Loader that matches the version of ScalarDB that you are using to the `getting-started` folder. Then, based on your database, run the following command, replacing `<VERSION>` with the version of the ScalarDB Schema Loader that you downloaded: <div id="tabset-2"> <div class="tab"> <button class="tablinks" onclick="openTab(event, 'Cassandra2', 'tabset-2')" id="defaultOpen-2">Cassandra</button> <button class="tablinks" onclick="openTab(event, 'CosmosDBfor_NoSQL2', 'tabset-2')">Cosmos DB for NoSQL</button> <button class="tablinks" onclick="openTab(event, 'DynamoDB2', 'tabset-2')">DynamoDB</button> <button class="tablinks" onclick="openTab(event, 'JDBC_databases2', 'tabset-2')">JDBC databases</button> </div> <div id="Cassandra2" class="tabcontent" markdown="1"> ```shell $ java -jar scalardb-schema-loader-<VERSION>.jar --config scalardb.properties --schema-file emoney.json --coordinator --replication-factor=1 ``` {% capture notice--info %} 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 . In addition, the `--replication-factor=1` option has an effect only when using Cassandra. The default replication factor is `3`, but to facilitate the setup in this tutorial, `1` is used so that you only need to prepare a cluster with one node instead of three nodes. However, keep in mind that a replication factor of `1` is not suited for production. {% endcapture %} <div class="notice--info">{{ notice--info | markdownify }}</div> </div> <div id="CosmosDBfor_NoSQL2" class="tabcontent" markdown="1"> ```shell $ java -jar scalardb-schema-loader-<VERSION>.jar --config scalardb.properties --schema-file emoney.json --coordinator ``` {% capture notice--info %} 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

{% endcapture %} <div class="notice--info">{{ notice--info | markdownify }}</div> </div> <div id="DynamoDB2" class="tabcontent" markdown="1"> ```shell $ java -jar scalardb-schema-loader-<VERSION>.jar --config scalardb.properties --schema-file emoney.json --coordinator ``` {% capture notice--info %} 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 . {% endcapture %} <div class="notice--info">{{ notice--info | markdownify }}</div> </div> <div id="JDBC_databases2" class="tabcontent" markdown="1"> ```shell $ java -jar scalardb-schema-loader-<VERSION>.jar --config scalardb.properties --schema-file emoney.json --coordinator ``` {% capture notice--info %} 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 . {% endcapture %} <div class="notice--info">{{ notice--info | markdownify }}</div> </div> </div> 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. {% capture notice--info %} Note When you first execute a Gradle command, Gradle will automatically install the necessary libraries. {% endcapture %} <div class="notice--info">{{ notice--info | markdownify }}</div> 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: ```shell $ ./gradlew run --args="-action charge -amount 500 -to customer1" ``` 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: ```shell $ ./gradlew run --args="-action charge -amount 0 -to merchant1" ``` You can add funds to an account in the same way that you created and added funds to an account in . To add 500 to the account for customer1, run the following command: ```shell $ ./gradlew run --args="-action charge -amount 500 -to customer1" ``` The account for customer1 will now have a balance of 1000. 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: ```shell $ ./gradlew run --args="-action pay -amount 100 -from customer1 -to merchant1" ``` 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: ```shell $ ./gradlew run --args="-action getBalance -id customer1" ``` You should see the following output: ```shell ... The balance for customer1 is 900 ... ``` To get the balance of merchant1, run the following command: ```shell $ ./gradlew run --args="-action getBalance -id merchant1" ``` You should see the following output: ```shell ... The balance for merchant1 is 100 ... ``` To see the source code for the electronic money application used in this tutorial, see .