---
type: Deployment Guide
title: ScalarDB Server
description: 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.
resource: https://scalardb-community.scalar-labs.com/docs/latest/scalardb-server/
tags:
- scalardb-community
- v3.13
- phase:operate
status: stable
product: scalardb-community
product_title: ScalarDB Community
version: '3.13'
doc_id: scalardb-server
lifecycle_phase: operate
generated:
  by: process:okf-build/1.0.0
  at: '2026-08-10T20:40:05Z'
sources:
- id: docs-scalardb-community
  resource: https://github.com/scalar-labs/docs-scalardb-community/blob/71d199cb0df1c638bd7e305b64fa09fc7236e5c4/docs/scalardb-server.mdx
  title: ScalarDB Community documentation source (MDX)
  author: process:scalar-labs/docs-scalardb-community
  last_modified: '2025-04-07T11:32:02Z'
---

# ScalarDB Server

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.

## Install prerequisites

ScalarDB Server is written in Java. So one of the following Java Development Kits (JDKs) is required to run it:

- [Oracle JDK](https://www.oracle.com/java/technologies/downloads/) 8
- OpenJDK 8 from [Eclipse Temurin](https://adoptium.net/temurin/releases/), [Amazon Corretto](https://aws.amazon.com/corretto/), or [Microsoft](https://learn.microsoft.com/en-us/java/openjdk/download)

:::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](./requirements.md).

:::

## Install ScalarDB Server

We have Docker images in [our repository](https://github.com/orgs/scalar-labs/packages/container/package/scalardb-server) and zip archives of ScalarDB Server available in [releases](https://github.com/scalar-labs/scalardb/releases).

If you are interested in building from source, run the following command:

```console
./gradlew installDist
```

Of course, you can archive the jar and libraries by `./gradlew distZip` and so on.

## Configure ScalarDB Server

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
#
# ScalarDB Server configurations
#

# Port number of ScalarDB Server. The default is `60051`.
scalar.db.server.port=60051

# Prometheus exporter port. Prometheus exporter will not be started if a negative number is given. The default is `8080`.
scalar.db.server.prometheus_exporter_port=8080

# The maximum message size allowed to be received. If not specified, use the gRPC default value.
scalar.db.server.grpc.max_inbound_message_size=

# The maximum size of metadata allowed to be received. If not specified, use the gRPC default value.
scalar.db.server.grpc.max_inbound_metadata_size=

# The decommissioning duration in seconds. The default is `30`.
scalar.db.server.decommissioning_duration_secs=30

#
# Transaction manager configurations
#

# Transaction manager implementation. The default is `consensus-commit`.
scalar.db.transaction_manager=consensus-commit

# Storage implementation used for Consensus Commit. The default is `cassandra`.
scalar.db.storage=cassandra

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

# Port number for all the contact points.
#scalar.db.contact_port=

# Credential information to access the database.
scalar.db.username=cassandra
scalar.db.password=cassandra

# Isolation level used for Consensus Commit. Either `SNAPSHOT` or `SERIALIZABLE` can be specified. The default is `SNAPSHOT`.
scalar.db.consensus_commit.isolation_level=SNAPSHOT

# Serializable strategy used for Consensus Commit.
# Either `EXTRA_READ` or `EXTRA_WRITE` can be specified. The default is `EXTRA_READ`.
# If `SNAPSHOT` is specified in the property `scalar.db.consensus_commit.isolation_level`, this is ignored.
scalar.db.consensus_commit.serializable_strategy=
```

For details about transaction manager configurations, see [ScalarDB Configurations](./configurations.md).

## Start ScalarDB Server

### Docker images

For Docker images, you need to pull the ScalarDB Server image first:
```console
docker pull ghcr.io/scalar-labs/scalardb-server:<version>
```

And then, you can start ScalarDB Server with the following command:
```console
docker run -v <your local property file path>:/scalardb/server/database.properties.tmpl -d -p 60051:60051 -p 8080:8080 ghcr.io/scalar-labs/scalardb-server:<version>
```

You can also start it with DEBUG logging as follows:
```console
docker run -v <your local property file path>:/scalardb/server/database.properties.tmpl -e SCALAR_DB_LOG_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:
```console
docker run -v <your local property file path>:/scalardb/server/database.properties.tmpl -v <your custom log4j2 configuration file path>:/scalardb/server/log4j2.properties.tmpl -d -p 60051:60051 -p 8080:8080 ghcr.io/scalar-labs/scalardb-server:<version>
```

You can also start it with environment variables as follows:
```console
docker run --env SCALAR_DB_CONTACT_POINTS=cassandra --env SCALAR_DB_CONTACT_PORT=9042 --env SCALAR_DB_USERNAME=cassandra --env SCALAR_DB_PASSWORD=cassandra --env SCALAR_DB_STORAGE=cassandra -d -p 60051:60051 -p 8080:8080 ghcr.io/scalar-labs/scalardb-server:<version>
```

You can also start it with JMX as follows:
```console
docker run -v <your local property file path>:/scalardb/server/database.properties.tmpl -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>
```

### Zip archives

For zip archives, you can start ScalarDB Server with the following commands:

```console
unzip scalardb-server-<version>.zip
cd scalardb-server-<version>
export JAVA_OPTS="<your JVM options>"
bin/scalardb-server --config <your property file path>
```

## Usage of the Java client of ScalarDB Server

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
# Transaction manager implementation.
scalar.db.transaction_manager=grpc

# Comma-separated contact points.
scalar.db.contact_points=<ScalarDB Server host>

# Port number for all the contact points.
scalar.db.contact_port=60051

# The deadline duration for gRPC connections. The default is `60000` milliseconds (60 seconds).
scalar.db.grpc.deadline_duration_millis=60000

# The maximum message size allowed for a single gRPC frame. If not specified, use the gRPC default value.
scalar.db.grpc.max_inbound_message_size=

# The maximum size of metadata allowed to be received. If not specified, use the gRPC default value.
scalar.db.grpc.max_inbound_metadata_size=
```

## Further reading

Please see the following sample to learn ScalarDB Server further:

- [ScalarDB Server Sample](https://scalardb-community.scalar-labs.com/docs/latest/scalardb-samples/scalardb-server-sample/README/)

Please also see the following documents to learn how to deploy ScalarDB Server:

- [Deploy ScalarDB Server on AWS](https://scalardb-community.scalar-labs.com/docs/latest/scalar-kubernetes/ManualDeploymentGuideScalarDBServerOnEKS/)
- [Deploy ScalarDB Server on Azure](https://scalardb-community.scalar-labs.com/docs/latest/scalar-kubernetes/ManualDeploymentGuideScalarDBServerOnAKS/)
