Project: ScalarDB (App Definition and Development / Database)
File: configurations.md

This page describes the available configurations for ScalarDB. ScalarDB provides its own transaction protocol called Consensus Commit. You can use the Consensus Commit protocol directly through the ScalarDB client library or through , which is a component that is available only in the ScalarDB Enterprise edition. Consensus Commit is the default transaction manager type in ScalarDB. To use the Consensus Commit transaction manager, add the following to the ScalarDB properties file: ```properties scalar.db.transaction_manager=consensus-commit ``` {% capture notice--info %} Note If you don't specify the `scalar.db.transaction_manager` property, `consensus-commit` will be the default value. {% endcapture %} <div class="notice--info">{{ notice--info | markdownify }}</div> The following basic configurations are available for the Consensus Commit transaction manager: | Name | Description | Default | |-|--|| | `scalar.db.transaction_manager` | `consensus-commit` should be specified. | - | | `scalar.db.consensuscommit.isolationlevel` | Isolation level used for Consensus Commit. Either `SNAPSHOT` or `SERIALIZABLE` can be specified. | `SNAPSHOT` | | `scalar.db.consensuscommit.serializablestrategy` | Serializable strategy used for Consensus Commit. Either `EXTRAREAD` or `EXTRAWRITE` can be specified. If `SNAPSHOT` is specified in the property `scalar.db.consensuscommit.isolationlevel`, this configuration will be ignored. | `EXTRA_READ` | | `scalar.db.consensus_commit.coordinator.namespace` | Namespace name of Coordinator tables. | `coordinator` | | `scalar.db.consensuscommit.includemetadata.enabled` | If set to `true`, `Get` and `Scan` operations results will contain transaction metadata. To see the transaction metadata columns details for a given table, you can use the `DistributedTransactionAdmin.getTableMetadata()` method, which will return the table metadata augmented with the transaction metadata columns. Using this configuration can be useful to investigate transaction-related issues. | `false` | The following performance-related configurations are available for the Consensus Commit transaction manager: | Name | Description | Default | |--|--|-| | `scalar.db.consensuscommit.parallelexecutor_count` | Number of executors (threads) for parallel execution. | `128` | | `scalar.db.consensuscommit.parallelpreparation.enabled` | Whether or not the preparation phase is executed in parallel. | `true` | | `scalar.db.consensuscommit.parallelvalidation.enabled` | Whether or not the validation phase (in `EXTRAREAD`) is executed in parallel. | The value of `scalar.db.consensuscommit.parallel_commit.enabled` | | `scalar.db.consensuscommit.parallelcommit.enabled` | Whether or not the commit phase is executed in parallel. | `true` | | `scalar.db.consensuscommit.parallelrollback.enabled` | Whether or not the rollback phase is executed in parallel. | The value of `scalar.db.consensuscommit.parallelcommit.enabled` | | `scalar.db.consensuscommit.asynccommit.enabled` | Whether or not the commit phase is executed asynchronously. | `false` | | `scalar.db.consensuscommit.asyncrollback.enabled` | Whether or not the rollback phase is executed asynchronously. | The value of `scalar.db.consensuscommit.asynccommit.enabled` | | `scalar.db.consensuscommit.parallelimplicitpreread.enabled` | Whether or not implicit pre-read is executed in parallel. | `true` | Consensus Commit has a storage abstraction layer and supports multiple underlying storages. You can specify the storage implementation by using the `scalar.db.storage` property. Select a database to see the configurations available for each

<div id="tabset-1"> <div class="tab"> <button class="tablinks" onclick="openTab(event, 'Cassandra', 'tabset-1')" id="defaultOpen-1">Cassandra</button> <button class="tablinks" onclick="openTab(event, 'CosmosDBforNoSQL', 'tabset-1')">CosmosDB for NoSQL</button> <button class="tablinks" onclick="openTab(event, 'DynamoDB', 'tabset-1')">DynamoDB</button> <button class="tablinks" onclick="openTab(event, 'JDBC_databases', 'tabset-1')">JDBC databases</button> </div> <div id="Cassandra" class="tabcontent" markdown="1"> The following configurations are available for Cassandra: | Name | Description | Default | |--|--|| | `scalar.db.storage` | `cassandra` must be specified. | - | | `scalar.db.contact_points` | Comma-separated contact points. | | | `scalar.db.contact_port` | Port number for all the contact points. | | | `scalar.db.username` | Username to access the database. | | | `scalar.db.password` | Password to access the database. | | </div> <div id="CosmosDBforNoSQL" class="tabcontent" markdown="1"> The following configurations are available for CosmosDB for NoSQL: | Name | Description | Default | |--|-|-| | `scalar.db.storage` | `cosmos` must be specified. | - | | `scalar.db.contact_points` | Azure Cosmos DB for NoSQL endpoint with which ScalarDB should communicate. | | | `scalar.db.password` | Either a master or read-only key used to perform authentication for accessing Azure Cosmos DB for NoSQL. | | | `scalar.db.cosmos.consistencylevel` | Consistency level used for Cosmos DB operations. `STRONG` or `BOUNDEDSTALENESS` can be specified. | `STRONG` | </div> <div id="DynamoDB" class="tabcontent" markdown="1"> The following configurations are available for DynamoDB: | Name | Description | Default | ||-|| | `scalar.db.storage` | `dynamo` must be specified. | - | | `scalar.db.contact_points` | AWS region with which ScalarDB should communicate (e.g., `us-east-1`). | | | `scalar.db.username` | AWS access key used to identify the user interacting with AWS. | | | `scalar.db.password` | AWS secret access key used to authenticate the user interacting with AWS. | | | `scalar.db.dynamo.endpoint_override` | Amazon DynamoDB endpoint with which ScalarDB should communicate. This is primarily used for testing with a local instance instead of an AWS service. | | | `scalar.db.dynamo.namespace.prefix` | Prefix for the user namespaces and metadata namespace names. Since AWS requires having unique tables names in a single AWS region, this is useful if you want to use multiple ScalarDB environments (development, production, etc.) in a single AWS region. | | </div> <div id="JDBC_databases" class="tabcontent" markdown="1"> The following configurations are available for JDBC databases: | Name | Description | Default | |--||| | `scalar.db.storage` | `jdbc` must be specified. | - | | `scalar.db.contact_points` | JDBC connection URL. | | | `scalar.db.username` | Username to access the database. | | | `scalar.db.password` | Password to access the database. | | | `scalar.db.jdbc.connectionpool.minidle` | Minimum number of idle connections in the connection pool. | `20` | | `scalar.db.jdbc.connectionpool.maxidle` | Maximum number of connections that can remain idle in the connection pool. | `50` | | `scalar.db.jdbc.connectionpool.maxtotal` | Maximum total number of idle and borrowed connections that can be active at the same time for the connection pool. Use a negative value for no limit. | `100` | | `scalar.db.jdbc.preparedstatementspool.enabled` | Setting this property to `true` enables prepared-statement pooling. | `false` | |

| Maximum number of open statements that can be allocated from the statement pool at the same time. Use a negative value for no limit. | `-1` | | `scalar.db.jdbc.isolationlevel` | Isolation level for JDBC. `READUNCOMMITTED`, `READCOMMITTED`, `REPEATABLEREAD`, or `SERIALIZABLE` can be specified. | Underlying-database specific | | `scalar.db.jdbc.tablemetadata.connectionpool.min_idle` | Minimum number of idle connections in the connection pool for the table metadata. | `5` | | `scalar.db.jdbc.tablemetadata.connectionpool.max_idle` | Maximum number of connections that can remain idle in the connection pool for the table metadata. | `10` | | `scalar.db.jdbc.tablemetadata.connectionpool.max_total` | Maximum total number of idle and borrowed connections that can be active at the same time for the connection pool for the table metadata. Use a negative value for no limit. | `25` | | `scalar.db.jdbc.admin.connectionpool.minidle` | Minimum number of idle connections in the connection pool for admin. | `5` | | `scalar.db.jdbc.admin.connectionpool.maxidle` | Maximum number of connections that can remain idle in the connection pool for admin. | `10` | | `scalar.db.jdbc.admin.connectionpool.maxtotal` | Maximum total number of idle and borrowed connections that can be active at the same time for the connection pool for admin. Use a negative value for no limit. | `25` | {% capture notice--info %} Note If you're using SQLite3 as a JDBC database, you must set `scalar.db.contact_points` as follows: ```properties scalar.db.contactpoints=jdbc:sqlite:<YOURDB>.sqlite3?busy_timeout=10000 ``` Unlike other JDBC databases, . To avoid frequent errors caused internally by , we recommend setting a parameter. {% endcapture %} <div class="notice--info">{{ notice--info | markdownify }}</div> </div> </div> ScalarDB supports using multiple storage implementations simultaneously. You can use multiple storages by specifying `multi-storage` as the value for the `scalar.db.storage` property. For details about using multiple storages, see . is a component that provides a gRPC interface to ScalarDB. For details about client configurations, see the ScalarDB Cluster . By enabling the cross-partition scan option below, the `Scan` operation can retrieve all records across partitions. In addition, you can specify arbitrary conditions and orderings in the cross-partition `Scan` operation by enabling `crosspartitionscan.filtering` and `crosspartitionscan.ordering`, respectively. Currently, the cross-partition scan with filtering and ordering is available only for JDBC databases. To enable filtering and ordering, `scalar.db.crosspartitionscan.enabled` must be set to `true`. For details on how to use cross-partition scan, see . {% capture notice--warning %} Attention For non-JDBC databases, we do not recommend enabling cross-partition scan with the `SERIALIAZABLE` isolation level because transactions could be executed at a lower isolation level (that is, `SNAPSHOT`). When using non-JDBC databases, use cross-partition scan at your own risk only if consistency does not matter for your transactions. {% endcapture %} <div class="notice--warning">{{ notice--warning | markdownify }}</div> | Name | Description | Default | |-|--|| | `scalar.db.crosspartitionscan.enabled` | Enable cross-partition scan. | `false` | | `scalar.db.crosspartitionscan.filtering.enabled` | Enable filtering in cross-partition

| `false` | | `scalar.db.crosspartitionscan.ordering.enabled` | Enable ordering in cross-partition scan. | `false` | The following are additional configurations available for ScalarDB: | Name | Description | Default | |||-| | `scalar.db.metadata.cacheexpirationtime_secs` | ScalarDB has a metadata cache to reduce the number of requests to the database. This setting specifies the expiration time of the cache in seconds. | `-1` (no expiration) | | `scalar.db.activetransactionmanagement.expirationtimemillis` | ScalarDB maintains ongoing transactions, which can be resumed by using a transaction ID. This setting specifies the expiration time of this transaction management feature in milliseconds. | `-1` (no expiration) | | `scalar.db.defaultnamespacename` | The given namespace name will be used by operations that do not already specify a namespace. | | | `scalar.db.systemnamespacename` | The given namespace name will be used by ScalarDB internally. | `scalardb` | You can use placeholders in the values, and they are replaced with environment variables (`${env:<ENVIRONMENTVARIABLENAME>}`) or system properties (`${sys:<SYSTEMPROPERTYNAME>}`). You can also specify default values in placeholders like `${sys:<SYSTEMPROPERTYNAME>:-<DEFAULT_VALUE>}`. The following is an example of a configuration that uses placeholders: ```properties scalar.db.username=${env:<SCALARDBUSERNAME>:-admin} scalar.db.password=${env:<SCALARDBPASSWORD>} ``` In this example configuration, ScalarDB reads the username and password from environment variables. If the environment variable `SCALARDBUSERNAME` does not exist, ScalarDB uses the default value `admin`. This section provides some configuration examples. ```mermaid flowchart LR app["<b>App</b><br />(ScalarDB library with<br />Consensus Commit)"] db[(Underlying storage or database)] app --> db ``` In this example configuration, the app (ScalarDB library with Consensus Commit) connects to an underlying storage or database (in this case, Cassandra) directly. {% capture notice--warning %} Attention This configuration exists only for development purposes and isnt suitable for a production environment. This is because the app needs to implement the interface to take transactionally consistent backups for ScalarDB, which requires additional configurations. {% endcapture %} <div class="notice--warning">{{ notice--warning | markdownify }}</div> The following is an example of the configuration for connecting the app to the underlying database through ScalarDB: ```properties scalar.db.transaction_manager=consensus-commit scalar.db.storage=cassandra scalar.db.contactpoints=<CASSANDRAHOST> scalar.db.username=<USERNAME> scalar.db.password=<PASSWORD> ``` ```mermaid flowchart LR app["App -<br />ScalarDB library with gRPC"] cluster["ScalarDB Cluster -<br />(ScalarDB library with<br />Consensus Commit)"] db[(Underlying storage or database)] app --> cluster --> db ``` In this example configuration, the app (ScalarDB library with gRPC) connects to an underlying storage or database (in this case, Cassandra) through ScalarDB Cluster, which is a component that is available only in the ScalarDB Enterprise edition. {% capture notice--info %} Note This configuration is acceptable for production use because ScalarDB Cluster implements the interface, which enables you to take transactionally consistent backups for ScalarDB by pausing ScalarDB Cluster. {% endcapture %} <div class="notice--info">{{ notice--info | markdownify }}</div> The following is an example of the configuration for connecting the app to the underlying database through ScalarDB Cluster: ```properties scalar.db.transaction_manager=cluster scalar.db.contactpoints=indirect:<SCALARDBCLUSTERCONTACTPOINT> ``` For details about client configurations, see the ScalarDB Cluster .