Skip to main content
Version: 3.9 (unsupported)
    Features and pricing

    ScalarDB SQL Server

    ScalarDB SQL Server is a gRPC server that implements ScalarDB SQL interface. With ScalarDB SQL Server, you can use ScalarDB SQL 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 SQL Server.

    Install prerequisites​

    ScalarDB SQL Server is written in Java. So the following software is required to run it.

    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.

    Install ScalarDB SQL Server​

    We have Docker images in our repository and zip archives of ScalarDB SQL Server available in releases.

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

    ./gradlew installDist

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

    Configure ScalarDB SQL Server​

    You need a properties file that includes the configurations for ScalarDB SQL Server. The properties file must contain two sections: ScalarDB SQL Server configurations and transaction manager configurations.

    #
    # ScalarDB SQL Server configurations
    #

    # Enable the statement cache. The default is `false`.
    scalar.db.sql.statement_cache.enabled=false

    # Maximum number of cached statements. The default is `100`.
    scalar.db.sql.statement_cache.size=100

    # Port number for grpc server. The default is `60052`.
    scalar.db.sql.server.port=60052

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

    # Decommissioning duration in seconds. The default is `30`. 
    scalar.db.sql.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 more details about the configurations for the transaction manager, see Transaction manager configurations.

    In addition, for more details about the configurations for ScalarDB SQL Server, see ScalarDB SQL Configurations.

    Start ScalarDB SQL Server​

    Docker images​

    For Docker images, you need to pull the ScalarDB SQL Server image first:

    docker pull ghcr.io/scalar-labs/scalardb-sql-server:<version>

    And then, you can start ScalarDB SQL Server with the following command:

    docker run -v <your local property file path>:/scalardb-sql/server/scalardb-sql-server.properties -d -p 60052:60052 -p 8080:8080 ghcr.io/scalar-labs/scalardb-sql-server:<version>

    You can also start it with DEBUG logging as follows:

    docker run -v <your local property file path>:/scalardb-sql/server/scalardb-sql-server.properties -e SCALAR_DB_LOG_LEVEL=DEBUG -d -p 60052:60052 -p 8080:8080 ghcr.io/scalar-labs/scalardb-sql-server:<version>

    You can also start it with your custom log configuration as follows:

    docker run -v <your local property file path>:/scalardb-sql/server/scalardb-sql-server.properties -v <your custom log4j2 configuration file path>:/scalardb-sql/server/log4j2.properties -d -p 60052:60052 -p 8080:8080 ghcr.io/scalar-labs/scalardb-sql-server:<version>

    You can also start it with environment variables as follows:

    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 60052:60052 -p 8080:8080 ghcr.io/scalar-labs/scalardb-sql-server:<version>

    You can also start it with JMX as follows:

    docker run -v <your local property file path>:/scalardb-sql/server/scalardb-sql-server.properties -e JAVA_OPTS="-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 60052:60052 -p 8080:8080 -p 9990:9990 ghcr.io/scalar-labs/scalardb-sql-server:<version>

    Zip archives​

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

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

    Usage of the Java client of ScalarDB SQL Server​

    You can connect to ScalarDB SQL Server by specifying Server mode in the configuration file on the client side. The configurations for Server mode are as follows:

    # Connection mode. "DIRECT" or "SERVER" can be set.
    # When you connect to ScalarDB SQL Server, specify the "SERVER" mode.
    scalar.db.sql.connection_mode=SERVER

    # Host name of ScalarDB SQL Server.
    scalar.db.sql.server_mode.host=<hostname of ScalarDB SQL Server>

    # Port number of ScalarDB SQL Server. 60052 by default.
    scalar.db.sql.server_mode.port=60052

    Please see ScalarDB SQL Configurations for more details of the configurations of Server mode.

    References​