From 848270f57bb459ee8598047db18087525ab23cce Mon Sep 17 00:00:00 2001 From: josh-wong Date: Tue, 24 Oct 2023 20:19:34 +0900 Subject: [PATCH] Add updated doc --- docs/3.10/configurations.md | 64 ++++++++++++++++++-- docs/3.10/two-phase-commit-transactions.md | 63 ++++++------------- docs/3.5/configurations.md | 16 ----- docs/3.5/two-phase-commit-transactions.md | 26 -------- docs/3.6/configurations.md | 16 ----- docs/3.6/two-phase-commit-transactions.md | 26 -------- docs/3.7/configurations.md | 16 ----- docs/3.7/two-phase-commit-transactions.md | 29 +-------- docs/3.8/configurations.md | 16 ----- docs/3.8/two-phase-commit-transactions.md | 33 +--------- docs/3.9/configurations.md | 64 ++++++++++++++++++-- docs/3.9/two-phase-commit-transactions.md | 63 ++++++------------- docs/latest/configurations.md | 64 ++++++++++++++++++-- docs/latest/two-phase-commit-transactions.md | 63 ++++++------------- 14 files changed, 238 insertions(+), 321 deletions(-) diff --git a/docs/3.10/configurations.md b/docs/3.10/configurations.md index b4f62e8..baa655d 100644 --- a/docs/3.10/configurations.md +++ b/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:.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 %} + +
{{ notice--info | markdownify }}
+ @@ -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= scalar.db.username= scalar.db.password= ``` + +### Configuration example #2 - App, ScalarDB Cluster, and database + +```mermaid +flowchart LR + app["App -
ScalarDB library with gRPC"] + cluster["ScalarDB Cluster -
(ScalarDB library with
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 %} + +
{{ notice--info | markdownify }}
+ +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: +``` + +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). diff --git a/docs/3.10/two-phase-commit-transactions.md b/docs/3.10/two-phase-commit-transactions.md index a5f935e..b9f7948 100644 --- a/docs/3.10/two-phase-commit-transactions.md +++ b/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,28 +35,28 @@ 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(""); +TwoPhaseCommitTransaction tx = transactionManager.begin(""); ``` 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(""); +TwoPhaseCommitTransaction tx = transactionManager.start(""); ``` ### Join a transaction (for participants) @@ -90,7 +64,7 @@ TwoPhaseCommitTransaction tx = manager.start(""); 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("") +TwoPhaseCommitTransaction tx = transactionManager.join("") ``` {% 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 %}
{{ notice--info | markdownify }}
@@ -307,12 +281,12 @@ The following shows how `resume()` works: ```java // Join (or begin) the transaction. -TwoPhaseCommitTransaction tx = manager.join(""); +TwoPhaseCommitTransaction tx = transactionManager.join(""); ... // Resume the transaction by using the transaction ID. -TwoPhaseCommitTransaction tx1 = manager.resume("") +TwoPhaseCommitTransaction tx1 = transactionManager.resume("") ``` {% 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 diff --git a/docs/3.5/configurations.md b/docs/3.5/configurations.md index 564fb7e..9882a18 100644 --- a/docs/3.5/configurations.md +++ b/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 port. scalar.db.contact_port= - -# Storage implementation. -scalar.db.storage=cassandra - -# Comma-separated contact points. -scalar.db.contact_points= - -# Credential information to access the database. -scalar.db.username= -scalar.db.password= ``` diff --git a/docs/3.5/two-phase-commit-transactions.md b/docs/3.5/two-phase-commit-transactions.md index dea9824..dede1d1 100644 --- a/docs/3.5/two-phase-commit-transactions.md +++ b/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. diff --git a/docs/3.6/configurations.md b/docs/3.6/configurations.md index c2e02e1..0c8008f 100644 --- a/docs/3.6/configurations.md +++ b/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 port. scalar.db.contact_port= - -# Storage implementation. -scalar.db.storage=cassandra - -# Comma-separated contact points. -scalar.db.contact_points= - -# Credential information to access the database. -scalar.db.username= -scalar.db.password= ``` diff --git a/docs/3.6/two-phase-commit-transactions.md b/docs/3.6/two-phase-commit-transactions.md index a9b2657..acea42c 100644 --- a/docs/3.6/two-phase-commit-transactions.md +++ b/docs/3.6/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. diff --git a/docs/3.7/configurations.md b/docs/3.7/configurations.md index c2e02e1..0c8008f 100644 --- a/docs/3.7/configurations.md +++ b/docs/3.7/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 port. scalar.db.contact_port= - -# Storage implementation. -scalar.db.storage=cassandra - -# Comma-separated contact points. -scalar.db.contact_points= - -# Credential information to access the database. -scalar.db.username= -scalar.db.password= ``` diff --git a/docs/3.7/two-phase-commit-transactions.md b/docs/3.7/two-phase-commit-transactions.md index 4881248..abaa992 100644 --- a/docs/3.7/two-phase-commit-transactions.md +++ b/docs/3.7/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. @@ -421,8 +395,7 @@ 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. ## Hands-on tutorial diff --git a/docs/3.8/configurations.md b/docs/3.8/configurations.md index d26dad0..ab82a37 100644 --- a/docs/3.8/configurations.md +++ b/docs/3.8/configurations.md @@ -180,12 +180,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) | | `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) | -### 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. @@ -258,14 +252,4 @@ scalar.db.contact_points= # ScalarDB Server port. scalar.db.contact_port= - -# Storage implementation. -scalar.db.storage=cassandra - -# Comma-separated contact points. -scalar.db.contact_points= - -# Credential information to access the database. -scalar.db.username= -scalar.db.password= ``` diff --git a/docs/3.8/two-phase-commit-transactions.md b/docs/3.8/two-phase-commit-transactions.md index 91c26c4..5146939 100644 --- a/docs/3.8/two-phase-commit-transactions.md +++ b/docs/3.8/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. @@ -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 %}
{{ notice--info | markdownify }}
@@ -715,7 +689,7 @@ In addition, each service typically has multiple servers (or hosts) for scalabil 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. -### gPRC +### gRPC When you use a client-side load balancer, you can use the same gRPC connection to send requests in a transaction, which guarantees that the requests go to the same servers. @@ -732,8 +706,7 @@ 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. ## Hands-on tutorial diff --git a/docs/3.9/configurations.md b/docs/3.9/configurations.md index b4f62e8..0b4074a 100644 --- a/docs/3.9/configurations.md +++ b/docs/3.9/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.9/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:.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 %} + +
{{ notice--info | markdownify }}
+ @@ -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.9/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.9/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= scalar.db.username= scalar.db.password= ``` + +### Configuration example #2 - App, ScalarDB Cluster, and database + +```mermaid +flowchart LR + app["App -
ScalarDB library with gRPC"] + cluster["ScalarDB Cluster -
(ScalarDB library with
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 %} + +
{{ notice--info | markdownify }}
+ +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: +``` + +For details about client configurations, see the ScalarDB Cluster [client configurations (redirects to the Enterprise docs site)](https://scalardb.scalar-labs.com/docs/3.9/scalardb-cluster/developer-guide-for-scalardb-cluster-with-java-api/#client-configurations). diff --git a/docs/3.9/two-phase-commit-transactions.md b/docs/3.9/two-phase-commit-transactions.md index a5f935e..1750ea0 100644 --- a/docs/3.9/two-phase-commit-transactions.md +++ b/docs/3.9/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,28 +35,28 @@ 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(""); +TwoPhaseCommitTransaction tx = transactionManager.begin(""); ``` 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(""); +TwoPhaseCommitTransaction tx = transactionManager.start(""); ``` ### Join a transaction (for participants) @@ -90,7 +64,7 @@ TwoPhaseCommitTransaction tx = manager.start(""); 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("") +TwoPhaseCommitTransaction tx = transactionManager.join("") ``` {% 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 %}
{{ notice--info | markdownify }}
@@ -307,12 +281,12 @@ The following shows how `resume()` works: ```java // Join (or begin) the transaction. -TwoPhaseCommitTransaction tx = manager.join(""); +TwoPhaseCommitTransaction tx = transactionManager.join(""); ... // Resume the transaction by using the transaction ID. -TwoPhaseCommitTransaction tx1 = manager.resume("") +TwoPhaseCommitTransaction tx1 = transactionManager.resume("") ``` {% 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 diff --git a/docs/latest/configurations.md b/docs/latest/configurations.md index b4f62e8..baa655d 100644 --- a/docs/latest/configurations.md +++ b/docs/latest/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:.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 %} + +
{{ notice--info | markdownify }}
+ @@ -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= scalar.db.username= scalar.db.password= ``` + +### Configuration example #2 - App, ScalarDB Cluster, and database + +```mermaid +flowchart LR + app["App -
ScalarDB library with gRPC"] + cluster["ScalarDB Cluster -
(ScalarDB library with
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 %} + +
{{ notice--info | markdownify }}
+ +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: +``` + +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). diff --git a/docs/latest/two-phase-commit-transactions.md b/docs/latest/two-phase-commit-transactions.md index a5f935e..b9f7948 100644 --- a/docs/latest/two-phase-commit-transactions.md +++ b/docs/latest/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,28 +35,28 @@ 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(""); +TwoPhaseCommitTransaction tx = transactionManager.begin(""); ``` 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(""); +TwoPhaseCommitTransaction tx = transactionManager.start(""); ``` ### Join a transaction (for participants) @@ -90,7 +64,7 @@ TwoPhaseCommitTransaction tx = manager.start(""); 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("") +TwoPhaseCommitTransaction tx = transactionManager.join("") ``` {% 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 %}
{{ notice--info | markdownify }}
@@ -307,12 +281,12 @@ The following shows how `resume()` works: ```java // Join (or begin) the transaction. -TwoPhaseCommitTransaction tx = manager.join(""); +TwoPhaseCommitTransaction tx = transactionManager.join(""); ... // Resume the transaction by using the transaction ID. -TwoPhaseCommitTransaction tx1 = manager.resume("") +TwoPhaseCommitTransaction tx1 = transactionManager.resume("") ``` {% 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