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

ScalarDB Server is a gRPC server that implements ScalarDB interface. With ScalarDB Server, you can use ScalarDB features from multiple programming languages that are supported by gRPC. Currently, we provide only a Java client officially, and we will support other language clients officially in the future. Of course, you can generate language-specific client stubs by yourself. However, note that it is not necessarily straightforward to implement a client since it's using a bidirectional streaming RPC in gRPC, and you need to be familiar with it. This document explains how to install and use ScalarDB Server. ScalarDB Server is written in Java. So the following software is required to run it. (OpenJDK 8) or higher We have Docker images in and zip archives of ScalarDB Server available in . If you are interested in building from source, run the following command: ```shell $ ./gradlew installDist ``` Of course, you can archive the jar and libraries by `./gradlew distZip` and so on. Also, you can build a Docker image from the source as follows. ```shell $ ./gradlew :server:docker ``` You need a property file holding the configuration for ScalarDB Server. The property file must contain two sections: ScalarDB Server configurations and transaction manager configurations. ```properties scalar.db.server.port=60051 scalar.db.server.prometheusexporterport=8080 scalar.db.server.grpc.maxinboundmessage_size= scalar.db.server.grpc.maxinboundmetadata_size= scalar.db.server.decommissioningdurationsecs=30 scalar.db.transaction_manager=consensus-commit scalar.db.storage=cassandra scalar.db.contact_points=localhost scalar.db.username=cassandra scalar.db.password=cassandra scalar.db.consensuscommit.isolationlevel=SNAPSHOT scalar.db.consensuscommit.serializablestrategy= ``` You can set some sensitive data (e.g., credentials) as the values of properties using environment variables. ```properties scalar.db.username=${env:SCALARDBUSERNAME} scalar.db.password=${env:SCALARDBPASSWORD} ``` For details about transaction manager configurations, see . For Docker images, you need to pull the ScalarDB Server image first: ```shell $ docker pull ghcr.io/scalar-labs/scalardb-server:<version> ``` And then, you can start ScalarDB Server with the following command: ```shell $ docker run -v <your local property file path>:/scalardb/server/database.properties -d -p 60051:60051 -p 8080:8080 ghcr.io/scalar-labs/scalardb-server:<version> ``` You can also start it with DEBUG logging as follows: ```shell $ docker run -v <your local property file path>:/scalardb/server/database.properties -e SCALARDBLOG_LEVEL=DEBUG -d -p 60051:60051 -p 8080:8080 ghcr.io/scalar-labs/scalardb-server:<version> ```` You can also start it with your custom log configuration as follows: ```shell $ docker run -v <your local property file path>:/scalardb/server/database.properties -v <your custom log4j2 configuration file path>:/scalardb/server/log4j2.properties -d -p 60051:60051 -p 8080:8080 ghcr.io/scalar-labs/scalardb-server:<version> ``` You can also start it with environment variables as follows: ```shell $ docker run --env SCALARDBCONTACTPOINTS=cassandra --env SCALARDBCONTACTPORT=9042 --env SCALARDBUSERNAME=cassandra --env SCALARDBPASSWORD=cassandra --env SCALARDBSTORAGE=cassandra -d -p 60051:60051 -p 8080:8080 ghcr.io/scalar-labs/scalardb-server:<version> ``` You can also start it with JMX as follows: ```shell $ docker run -v <your local property file path>:/scalardb/server/database.properties -e JAVA_OPTS="-Dlog4j.configurationFile=file:log4j2.properties -Djava.rmi.server.hostname=<your container hostname or IP address> -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote=true -Dcom.sun.management.jmxremote.local.only=false -Dcom.sun.management.jmxremote.port=9990 -Dcom.sun.management.jmxremote.rmi.port=9990 -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false" -d -p 60051:60051 -p 8080:8080 -p 9990:9990 ghcr.io/scalar-labs/scalardb-server:<version> ``` For zip archives, you can start ScalarDB Server with the following commands: ```shell $ unzip scalardb-server-<version>.zip $ cd scalardb-server-<version> $ export JAVA_OPTS="<your JVM options>" $ bin/scalardb-server --config <your property file path> ``` You can use the Java client of ScalarDB Server in almost the same way as other storages/databases. The difference is that you need to set `scalar.db.transaction_manager` to `grpc` in your client side property file. ```properties scalar.db.transaction_manager=grpc scalar.db.contact_points=<ScalarDB Server host> scalar.db.contact_port=60051 scalar.db.grpc.deadlinedurationmillis=60000 scalar.db.grpc.maxinboundmessage_size= scalar.db.grpc.maxinboundmetadata_size= ``` Please see the following sample to learn ScalarDB Server further: Please also see the following documents to learn how to deploy ScalarDB Server: