Run Transactions Through the ScalarDB Core Library

This guide explains how to configure your ScalarDB properties file and create schemas to run transactions through a one-phase or a two-phase commit interface by using the ScalarDB Core library.

Preparation

For the purpose of this guide, you will set up a database and ScalarDB by using a sample in the ScalarDB samples repository.

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 necessary files by running the following command:

cd scalardb-samples/scalardb-sample

Set up a database

Follow the instructions below to configure your database for ScalarDB.

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

Relational databases

Select your relational database.

Db2

Run Db2 locally

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

To start IBM Db2, run the following command:

docker compose up -d db2

Configure ScalarDB

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

# For Db2
scalar.db.storage=jdbc
scalar.db.contact_points=jdbc:db2://localhost:50000/sample
scalar.db.username=db2inst1
scalar.db.password=db2inst1

MariaDB

Run MariaDB locally

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

To start MariaDB, run the following command:

docker compose up -d mariadb

Configure ScalarDB

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

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

MySQL

Run MySQL locally

You can run MySQL in Docker Compose by using the docker-compose.yml file in the scalardb-samples/scalardb-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-sample directory contains database configurations. 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

Oracle Database

Run Oracle Database locally

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

To start Oracle Database, run the following command:

docker compose up -d oracle

Configure ScalarDB

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

# For Oracle
scalar.db.storage=jdbc
scalar.db.contact_points=jdbc:oracle:thin:@//localhost:1521/FREEPDB1
scalar.db.username=SYSTEM
scalar.db.password=Oracle

PostgreSQL

Run PostgreSQL locally

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

To start PostgreSQL, run the following command:

docker compose up -d postgres

Configure ScalarDB

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

# For PostgreSQL
scalar.db.storage=jdbc
scalar.db.contact_points=jdbc:postgresql://localhost:5432/
scalar.db.username=postgres
scalar.db.password=postgres

SQL Server

Run SQL Server locally

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

To start SQL Server, run the following command:

docker compose up -d sqlserver

Configure ScalarDB

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

# For SQL Server
scalar.db.storage=jdbc
scalar.db.contact_points=jdbc:sqlserver://localhost:1433;encrypt=true;trustServerCertificate=true
scalar.db.username=sa
scalar.db.password=SqlServer22

SQLite

Configure ScalarDB

SQLite is an embedded, file-based database, so there is no separate server to start. ScalarDB creates the database file automatically when it is first used. The database.properties file in the scalardb-samples/scalardb-sample directory contains database configurations. Please uncomment the properties for SQLite in the database.properties file so that the configuration looks as follows:

# For Sqlite
scalar.db.storage=jdbc
scalar.db.contact_points=jdbc:sqlite:scalardb-sample.sqlite3?busy_timeout=10000
scalar.db.username=
scalar.db.password=

NewSQL databases

Select your NewSQL database.

YugabyteDB

Run YugabyteDB locally

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

To start YugabyteDB, run the following command:

docker compose up -d yugabyte

Configure ScalarDB

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

# For Yugabyte
scalar.db.storage=jdbc
scalar.db.contact_points=jdbc:yugabytedb://localhost:5433/postgres
scalar.db.username=yugabyte
scalar.db.password=yugabyte

NoSQL databases

Select your NoSQL database.

Cassandra

Run Cassandra locally

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

To start Apache Cassandra, run the following command:

docker compose up -d cassandra

Configure ScalarDB

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

# For Cassandra
scalar.db.storage=cassandra
scalar.db.contact_points=localhost
scalar.db.username=cassandra
scalar.db.password=cassandra

Cosmos DB for NoSQL

To use Azure Cosmos DB for NoSQL, you must have an Azure account. If you don't have an Azure account, visit Create an Azure Cosmos DB account.

Configure Cosmos DB for NoSQL

Set the default consistency level to Strong according to the official document at Configure the default consistency level.

Configure ScalarDB

The database.properties file in the scalardb-samples/scalardb-sample directory contains database configurations. Be sure to change the values for scalar.db.contact_points and scalar.db.password as described.

# For Cosmos DB
scalar.db.storage=cosmos
scalar.db.contact_points=<COSMOS_DB_FOR_NOSQL_URI>
scalar.db.password=<COSMOS_DB_FOR_NOSQL_KEY>

note

You can use the primary key or the secondary key in your Azure Cosmos DB account as the value for scalar.db.password.

DynamoDB

Run Amazon DynamoDB Local

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

To start Amazon DynamoDB Local, run the following command:

docker compose up -d dynamodb

Configure ScalarDB

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

# For DynamoDB Local
scalar.db.storage=dynamo
scalar.db.contact_points=sample
scalar.db.username=sample
scalar.db.password=sample
scalar.db.dynamo.endpoint_override=http://localhost:8000

For a comprehensive list of configurations for ScalarDB, see ScalarDB Configurations.

Create or import a schema

ScalarDB has its own data model and schema that maps to the implementation-specific data model and schema.

• Need to create a database schema? See ScalarDB Schema Loader.
• Need to import an existing database? See Importing Existing Tables to ScalarDB by Using ScalarDB Schema Loader.

Load initial data as necessary

ScalarDB Data Loader is a utility for importing and exporting data with ScalarDB.

• Need to import data into your database? See Importing data.
• Need to export data from your database? See Exporting data.

Run transactions by using Java

• Want to run transactions by using a one-phase commit interface? See the ScalarDB Java API Guide.
• Want to run transactions by using a two-phase commit interface? See Transactions with a Two-Phase Commit Interface.