Merge pull request #64 from scalar-labs/add-updated-config-docs

Add updated ScalarDB configuration-related docs

docs/3.10/configurations.md

@@ -4,7 +4,7 @@ This page describes the available configurations for ScalarDB.
 
 ## ScalarDB client configurations
 
-ScalarDB provides its own transaction protocol called Consensus Commit. You can use the Consensus Commit protocol directly through the ScalarDB client library.
+ScalarDB provides its own transaction protocol called Consensus Commit. You can use the Consensus Commit protocol directly through the ScalarDB client library or through [ScalarDB Cluster (redirects to the Enterprise docs site)](https://scalardb.scalar-labs.com/docs/3.10/scalardb-cluster/), which is a component that is available only in the ScalarDB Enterprise edition.
 
 ### Use Consensus Commit directly
 
@@ -127,6 +127,21 @@ The following configurations are available for JDBC databases:
 | `scalar.db.jdbc.admin.connection_pool.max_idle`           | Maximum number of connections that can remain idle in the connection pool for admin.                                                                                         | `10`                         |
 | `scalar.db.jdbc.admin.connection_pool.max_total`          | 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 use SQLite3 as a JDBC database, you must set `scalar.db.contact_points` as follows.
+
+```properties
+scalar.db.contact_points=jdbc:sqlite:<YOUR_DB>.sqlite3?busy_timeout=10000
+```
+
+Unlike other JDBC databases, [SQLite3 does not fully support concurrent access](https://www.sqlite.org/lang_transaction.html).
+To avoid frequent errors caused internally by [`SQLITE_BUSY`](https://www.sqlite.org/rescode.html#busy), we recommend setting a [`busy_timeout`](https://www.sqlite.org/c3ref/busy_timeout.html) parameter.
+{% endcapture %}
+
+<div class="notice--info">{{ notice--info | markdownify }}</div>
+
 </div>
 </div>
 
@@ -136,6 +151,12 @@ ScalarDB supports using multiple storage implementations simultaneously. You can
 
 For details about using multiple storages, see [Multi-Storage Transactions](multi-storage-transactions.md).
 
+### Use Consensus Commit through ScalarDB Cluster
+
+[ScalarDB Cluster (redirects to the Enterprise docs site)](https://scalardb.scalar-labs.com/docs/3.10/scalardb-cluster/) is a component that provides a gRPC interface to ScalarDB.
+
+For details about client configurations, see the ScalarDB Cluster [client configurations (redirects to the Enterprise docs site)](https://scalardb.scalar-labs.com/docs/3.10/scalardb-cluster/developer-guide-for-scalardb-cluster-with-java-api/#client-configurations).
+
 ## Other ScalarDB configurations
 
 The following are additional configurations available for ScalarDB:
@@ -146,13 +167,11 @@ The following are additional configurations available for ScalarDB:
 | `scalar.db.active_transaction_management.expiration_time_millis` | 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.default_namespace_name`                               | The given namespace name will be used by operations that do not already specify a namespace. |                      |
 
-### Two-phase commit support
-
-ScalarDB supports transactions with a two-phase commit interface. With transactions with a two-phase commit interface, you can execute a transaction that spans multiple processes or applications, like in a microservice architecture.
+## Configuration examples
 
-For details about using two-phase commit, see [Transactions with a Two-Phase Commit Interface](two-phase-commit-transactions.md).
+This section provides some configuration examples.
 
-## Configuration example
+### Configuration example #1 - App and database
 
 ```mermaid
 flowchart LR
@@ -187,3 +206,36 @@ scalar.db.contact_points=<CASSANDRA_HOST>
 scalar.db.username=<USERNAME>
 scalar.db.password=<PASSWORD>
 ```
+
+### Configuration example #2 - App, ScalarDB Cluster, and database
+
+```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 [Scalar Admin](https://github.com/scalar-labs/scalar-admin) 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
+# Transaction manager implementation.
+scalar.db.transaction_manager=cluster
+
+# Contact point of the cluster.
+scalar.db.contact_points=indirect:<SCALARDB_CLUSTER_CONTACT_POINT>
+```
+
+For details about client configurations, see the ScalarDB Cluster [client configurations (redirects to the Enterprise docs site)](https://scalardb.scalar-labs.com/docs/3.10/scalardb-cluster/developer-guide-for-scalardb-cluster-with-java-api/#client-configurations).

docs/3.10/two-phase-commit-transactions.md

@@ -14,32 +14,6 @@ In transactions with a two-phase commit interface, there are two roles—Coordin
 
 The Coordinator process and the participant processes all have different transaction manager instances. The Coordinator process first begins or starts a transaction, and the participant processes join the transaction. After executing CRUD operations, the Coordinator process and the participant processes commit the transaction by using the two-phase interface.
 
-## How to configure ScalarDB to support transactions with a two-phase commit interface
-
-To enable transactions with a two-phase commit interface, you need to specify `consensus-commit` as the value for `scalar.db.transaction_manager` in the ScalarDB properties file.
-
-The following is an example of a configuration for transactions with a two-phase commit interface when using Cassandra:
-
-```properties
-# Consensus Commit is required to support transactions with a two-phase commit interface.
-scalar.db.transaction_manager=consensus-commit
-
-# Storage implementation.
-scalar.db.storage=cassandra
-
-# Comma-separated contact points.
-scalar.db.contact_points=cassandra
-
-# Port number for all the contact points.
-scalar.db.contact_port=9042
-
-# Credential information to access the database.
-scalar.db.username=cassandra
-scalar.db.password=cassandra
-```
-
-For additional configurations, see [ScalarDB Configurations](configurations.md).
-
 ## How to execute transactions with a two-phase commit interface
 
 To execute a two-phase commit transaction, you must get the transaction manager instance. Then, the Coordinator process can begin or start the transaction, and the participant can process the transaction.
@@ -61,36 +35,36 @@ For the process or application that begins the transaction to act as Coordinator
 
 ```java
 // Begin a transaction.
-TwoPhaseCommitTransaction tx = manager.begin();
+TwoPhaseCommitTransaction tx = transactionManager.begin();
 ```
 
 Or, for the process or application that begins the transaction to act as Coordinator, you should use the following `start` method:
 
 ```java
 // Start a transaction.
-TwoPhaseCommitTransaction tx = manager.start();
+TwoPhaseCommitTransaction tx = transactionManager.start();
 ```
 
 Alternatively, you can use the `begin` method for a transaction by specifying a transaction ID as follows:
 
 ```java
 // Begin a transaction by specifying a transaction ID.
-TwoPhaseCommitTransaction tx = manager.begin("<TRANSACTION_ID>");
+TwoPhaseCommitTransaction tx = transactionManager.begin("<TRANSACTION_ID>");
 ```
 
 Or, you can use the `start` method for a transaction by specifying a transaction ID as follows:
 
 ```java
 // Start a transaction by specifying a transaction ID.
-TwoPhaseCommitTransaction tx = manager.start("<TRANSACTION_ID>");
+TwoPhaseCommitTransaction tx = transactionManager.start("<TRANSACTION_ID>");
 ```
 
 ### Join a transaction (for participants)
 
 For participants, you can join a transaction by specifying the transaction ID associated with the transaction that Coordinator has started or begun as follows:
 
 ```java
-TwoPhaseCommitTransaction tx = manager.join("<TRANSACTION_ID>")
+TwoPhaseCommitTransaction tx = transactionManager.join("<TRANSACTION_ID>")
 ```
 
 {% capture notice--info %}
@@ -213,7 +187,7 @@ Similar to `prepare()`, if any of the Coordinator or participant processes fail
 {% capture notice--info %}
 **Note**
 
-When using the [Consensus Commit](configurations/#consensus-commit) transaction manager with `EXTRA_READ` set as the value for `scalar.db.consensus_commit.serializable_strategy` and `SERIALIZABLE` set as the value for `scalar.db.consensus_commit.isolation_level`, you need to call `validate()`. However, if you are not using Consensus Commit, specifying `validate()` will not have any effect.
+When using the [Consensus Commit](configurations.md#use-consensus-commit-directly) transaction manager with `EXTRA_READ` set as the value for `scalar.db.consensus_commit.serializable_strategy` and `SERIALIZABLE` set as the value for `scalar.db.consensus_commit.isolation_level`, you need to call `validate()`. However, if you are not using Consensus Commit, specifying `validate()` will not have any effect.
 {% endcapture %}
 
 <div class="notice--info">{{ notice--info | markdownify }}</div>
@@ -307,12 +281,12 @@ The following shows how `resume()` works:
 
 ```java
 // Join (or begin) the transaction.
-TwoPhaseCommitTransaction tx = manager.join("<TRANSACTION_ID>");
+TwoPhaseCommitTransaction tx = transactionManager.join("<TRANSACTION_ID>");
 
 ...
 
 // Resume the transaction by using the transaction ID.
-TwoPhaseCommitTransaction tx1 = manager.resume("<TRANSACTION_ID>")
+TwoPhaseCommitTransaction tx1 = transactionManager.resume("<TRANSACTION_ID>")
 ```
 
 {% capture notice--info %}
@@ -359,7 +333,7 @@ public class ServiceAImpl implements ServiceA {
 
   @Override
   public void facadeEndpoint() throws Exception {
-    TwoPhaseCommitTransaction tx = manager.begin();
+    TwoPhaseCommitTransaction tx = transactionManager.begin();
 
     try {
       ...
@@ -404,19 +378,19 @@ public class ServiceBImpl implements ServiceB {
   @Override
   public void endpoint1(String txId) throws Exception {
     // Join the transaction.
-    TwoPhaseCommitTransaction tx = manager.join(txId);
+    TwoPhaseCommitTransaction tx = transactionManager.join(txId);
   }
 
   @Override
   public void endpoint2(String txId) throws Exception {
     // Resume the transaction that you joined in `endpoint1()`.
-    TwoPhaseCommitTransaction tx = manager.resume(txId);
+    TwoPhaseCommitTransaction tx = transactionManager.resume(txId);
   }
 
   @Override
   public void prepare(String txId) throws Exception {
     // Resume the transaction.
-    TwoPhaseCommitTransaction tx = manager.resume(txId);
+    TwoPhaseCommitTransaction tx = transactionManager.resume(txId);
 
     ...
 
@@ -427,7 +401,7 @@ public class ServiceBImpl implements ServiceB {
   @Override
   public void commit(String txId) throws Exception {
     // Resume the transaction.
-    TwoPhaseCommitTransaction tx = manager.resume(txId);
+    TwoPhaseCommitTransaction tx = transactionManager.resume(txId);
 
     ...
 
@@ -438,7 +412,7 @@ public class ServiceBImpl implements ServiceB {
   @Override
   public void rollback(String txId) throws Exception {
     // Resume the transaction.
-    TwoPhaseCommitTransaction tx = manager.resume(txId);
+    TwoPhaseCommitTransaction tx = transactionManager.resume(txId);
 
     ...
 
@@ -713,7 +687,7 @@ In addition, each service typically has multiple servers (or hosts) for scalabil
 
 ![Load balancing for transactions with a two-phase commit interface](images/two_phase_commit_load_balancing.png)
 
-There are several approaches to achieve load balancing for transactions with a two-phase commit interface depending on the protocol between the services. Some approaches for this include using gRPC and HTTP/1.1.
+There are several approaches to achieve load balancing for transactions with a two-phase commit interface depending on the protocol between the services. Some approaches for this include using gRPC, HTTP/1.1, and [ScalarDB Cluster (redirects to the Enterprise docs site)](https://scalardb.scalar-labs.com/docs/latest/scalardb-cluster/), which is a component that is available only in the ScalarDB Enterprise edition.
 
 ### gRPC
 
@@ -732,8 +706,11 @@ For more details about load balancing in gRPC, see [gRPC Load Balancing](https:/
 Typically, you use a server-side (proxy) load balancer with HTTP/1.1:
 
 - When using an L3/L4 load balancer, you can use the same HTTP connection to send requests in a transaction, which guarantees the requests go to the same server.
-- When using an L7 load balancer, since requests in the same HTTP connection don't necessarily go to the same server, you need to use cookies or similar method to route requests to the correct server.
-You can use session affinity (sticky session) in that case.
+- When using an L7 load balancer, since requests in the same HTTP connection don't necessarily go to the same server, you need to use cookies or similar method to route requests to the correct server. You can use session affinity (sticky session) in that case.
+
+### ScalarDB Cluster
+
+ScalarDB Cluster addresses request routing by providing a routing mechanism that is capable of directing requests to the appropriate cluster node within the cluster. For details about ScalarDB Cluster, see [ScalarDB Cluster (redirects to the Enterprise docs site)](https://scalardb.scalar-labs.com/docs/latest/scalardb-cluster/).
 
 ## Hands-on tutorial
 

docs/3.5/configurations.md

@@ -174,12 +174,6 @@ The following are additional configurations available for ScalarDB:
 |------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------|
 | `scalar.db.metadata.cache_expiration_time_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) |
 
-### Two-phase commit support
-
-ScalarDB supports transactions with a two-phase commit interface. With transactions with a two-phase commit interface, you can execute a transaction that spans multiple processes or applications, like in a microservice architecture.
-
-For details about using two-phase commit, see [Transactions with a Two-Phase Commit Interface](two-phase-commit-transactions.md).
-
 ## Configuration examples
 
 This section provides some configuration examples.
@@ -252,14 +246,4 @@ scalar.db.contact_points=<SCALARDB_SERVER_HOST>
 
 # ScalarDB Server port.
 scalar.db.contact_port=<SCALARDB_SERVER_PORT>
-
-# Storage implementation.
-scalar.db.storage=cassandra
-
-# Comma-separated contact points.
-scalar.db.contact_points=<CASSANDRA_HOST>
-
-# Credential information to access the database.
-scalar.db.username=<USERNAME>
-scalar.db.password=<PASSWORD>
 ```

docs/3.5/two-phase-commit-transactions.md

@@ -14,32 +14,6 @@ In transactions with a two-phase commit interface, there are two roles—Coordin
 
 The Coordinator process and the participant processes all have different transaction manager instances. The Coordinator process first starts a transaction, and the participant processes join the transaction. After executing CRUD operations, the Coordinator process and the participant processes commit the transaction by using the two-phase interface.
 
-## How to configure ScalarDB to support transactions with a two-phase commit interface
-
-To enable transactions with a two-phase commit interface, you need to specify `consensus-commit` as the value for `scalar.db.transaction_manager` in the ScalarDB properties file.
-
-The following is an example of a configuration for transactions with a two-phase commit interface when using Cassandra:
-
-```properties
-# Consensus Commit is required to support transactions with a two-phase commit interface.
-scalar.db.transaction_manager=consensus-commit
-
-# Storage implementation.
-scalar.db.storage=cassandra
-
-# Comma-separated contact points.
-scalar.db.contact_points=cassandra
-
-# Port number for all the contact points.
-scalar.db.contact_port=9042
-
-# Credential information to access the database.
-scalar.db.username=cassandra
-scalar.db.password=cassandra
-```
-
-For additional configurations, see [ScalarDB Configurations](configurations.md).
-
 ## How to execute transactions with a two-phase commit interface
 
 To execute a two-phase commit transaction, you must get the transaction manager instance. Then, the Coordinator process can start the transaction, and the participant can process the transaction.

docs/3.6/configurations.md

@@ -178,12 +178,6 @@ The following are additional configurations available for ScalarDB:
 |------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------|
 | `scalar.db.metadata.cache_expiration_time_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) |
 
-### Two-phase commit support
-
-ScalarDB supports transactions with a two-phase commit interface. With transactions with a two-phase commit interface, you can execute a transaction that spans multiple processes or applications, like in a microservice architecture.
-
-For details about using two-phase commit, see [Transactions with a Two-Phase Commit Interface](two-phase-commit-transactions.md).
-
 ## Configuration examples
 
 This section provides some configuration examples.
@@ -256,14 +250,4 @@ scalar.db.contact_points=<SCALARDB_SERVER_HOST>
 
 # ScalarDB Server port.
 scalar.db.contact_port=<SCALARDB_SERVER_PORT>
-
-# Storage implementation.
-scalar.db.storage=cassandra
-
-# Comma-separated contact points.
-scalar.db.contact_points=<CASSANDRA_HOST>
-
-# Credential information to access the database.
-scalar.db.username=<USERNAME>
-scalar.db.password=<PASSWORD>
 ```