Skip to main content
Version: 3.7 (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.

    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 property file holding the configuration for ScalarDB SQL Server. It contains two sections, ScalarDB SQL Server configurations and underlying storage/database configurations.

    #
    # For ScalarDB SQL Server
    #

    # Default transaction mode. "TRANSACTION" or "TWO_PHASE_COMMIT_TRANSACTION" can be set. "TRANSACTION" mode is used by default.
    scalar.db.sql.default_transaction_mode=TRANSACTION

    # Enable the statement cache. Default is false.
    scalar.db.sql.statement_cache.enabled=false

    # The maximum number of cached statement. Default is 100.
    scalar.db.sql.statement_cache.size=100

    # Port number for grpc server. Default port number is 60052.
    scalar.db.sql.server.port=60052

    #
    # For underlying storage/database configurations
    #

    # Comma separated contact points. For DynamoDB, the region is specified by this parameter.
    scalar.db.contact_points=localhost

    # Port number for all the contact points. Default port number for each database is used if empty.
    #scalar.db.contact_port=

    # Credential information to access the database. For Cosmos DB, username isn't used. For DynamoDB, AWS_ACCESS_KEY_ID is specified by the username and AWS_ACCESS_SECRET_KEY is specified by the password.
    scalar.db.username=cassandra
    scalar.db.password=cassandra

    # Storage implementation. "cassandra" or "cosmos" or "dynamo" or "jdbc" or "grpc" can be set. Default storage is "cassandra".
    scalar.db.storage=cassandra

    # The type of the transaction manager. "consensus-commit" or "jdbc" or "grpc" can be set. The default is "consensus-commit".
    scalar.db.transaction_manager=consensus-commit

    # Isolation level used for ConsensusCommit. Either SNAPSHOT or SERIALIZABLE can be specified. SNAPSHOT is used by default.
    scalar.db.consensus_commit.isolation_level=SNAPSHOT

    # Serializable strategy used for ConsensusCommit transaction manager.
    # Either EXTRA_READ or EXTRA_WRITE can be specified. EXTRA_READ is used by default.
    # If SNAPSHOT is specified in the property "scalar.db.consensus_commit.isolation_level", this is ignored.
    scalar.db.consensus_commit.serializable_strategy=

    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.tmpl -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.tmpl -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.tmpl -v <your custom log4j2 configuration file path>:/scalardb-sql/server/log4j2.properties.tmpl -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.tmpl -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 use the Java client of ScalarDB SQL Server in almost the same way as the DIRECT connection mode (that uses ScalarDB API directly). When you connect to ScalarDB SQL Server, you need to specify the SERVER connection mode. The configurations for the SERVER connection mode are as follows:

    # Connection mode. "DIRECT" or "SERVER" can be set. "DIRECT" mode is used by default.
    # 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

    # Default transaction mode. "TRANSACTION" or "TWO_PHASE_COMMIT_TRANSACTION" can be set. "TRANSACTION" mode is used by default.
    scalar.db.sql.default_transaction_mode=TRANSACTION

    References​