Merge branch 'main' into sidebar-nav/add-cluster-deployment-patterns-guide

Author: josh-wong

docs/scalardb-cluster/deployment-patterns-for-microservices.mdx

@@ -0,0 +1,72 @@
+---
+tags:
+  - Enterprise Standard
+  - Enterprise Premium
+displayed_sidebar: docsEnglish
+---
+
+# ScalarDB Cluster Deployment Patterns for Microservices
+
+When building microservice applications that use ScalarDB Cluster, there are two patterns you can choose for how to deploy ScalarDB Cluster: shared-cluster pattern and separated-cluster pattern.
+This document first explains those patterns, how they differ, and the basic guidelines on which one to choose in which cases.
+
+Also, this document assumes that your microservice applications are created based on the database-per-service pattern, where each microservice manages its database, and a microservice needs to access another microservice's database via APIs between the microservices.
+
+## ScalarDB Cluster deployment patterns
+
+In the shared-cluster pattern, microservices share one ScalarDB Cluster instance, which is a cluster of ScalarDB Cluster nodes, in a system, so they access the same ScalarDB Cluster instance to interact with their databases. On the other hand, in the separated-cluster pattern, microservices use several ScalarDB Cluster instances. Typically, one microservice accesses one ScalarDB Cluster instance to interact with its database.
+
+The following diagram shows the patterns. (MS stands for microservice.)
+
+![ScalarDB Cluster deployment patterns for microservices.](images/scalardb-deployment-patterns.png)
+
+:::note
+
+You also need to manage the Coordinator table in either pattern in addition to the databases required for microservices.
+
+:::
+
+## Pros and cons
+
+One obvious difference is the amount of resources for ScalarDB Cluster instances. With the separated-cluster pattern, you need more resources to manage your applications. This also incurs more maintenance burden and costs.
+
+In addition, the ScalarDB Cluster APIs that you would need to use are different. Specifically, for the shared-cluster pattern, you need to use the [one-phase commit interface](../api-guide.mdx#transactional-api), where only one microservice needs to call `commit` to commit a transaction after microservices read and write records. For the separated-cluster pattern, you need to use the [two-phase commit interface](../two-phase-commit-transactions.mdx), where all the microservices first need to call `prepare` and then call `commit` if all the prepare calls are successful. Therefore, microservices with the separated-cluster pattern will likely be more complex than microservices with the shared-cluster pattern because they need to handle transactions and their errors in a more fine-grained manner.
+
+Moreover, the level of resource isolation is different. Microservices should be well-isolated for better maintainability and development efficiency, but the shared-cluster pattern brings weaker resource isolation. Weak resource isolation might also bring weak security. However, security risks can be mitigated by using the security features of ScalarDB Cluster, like authentication and authorization.
+
+Similarly, there is a difference in how systems are administrated. Specifically, in the shared-cluster pattern, a team must be tasked with managing a ScalarDB Cluster instance on behalf of the other teams. Typically, the central data team can manage it, but issues may arise if no such team exists. With the separated-cluster pattern, administration is more balanced but has a similar issue for the Coordinator table. The issue can be addressed by having a microservice for coordination and making a team manage the microservice.
+
+The following is a summary of the pros and cons of the patterns.
+
+### Shared-cluster pattern
+
+- **Pros:**
+  - Simple transaction and error handling because of the one-phase commit interface. (Backup operations for databases can also be simple.)
+  - Less resource usage because it uses one ScalarDB Cluster instance. 
+- **Cons:**
+  - Weak resource isolation between microservices.
+  - Unbalanced administration. (One team needs to manage a ScalarDB Cluster instance on behalf of the others.)
+
+### Separated-cluster pattern
+
+- **Pros:**
+  - Better resource isolation.
+  - More balanced administration. (A team manages one microservice and one ScalarDB Cluster instance. Also, a team must be tasked with managing the Coordinator table.)
+- **Cons:**
+  - Complex transaction and error handling due to the two-phase commit interface. (Backup operations for databases can also be complex.)
+  - More resource usage because of several ScalarDB Cluster instances.
+
+## Which pattern to choose
+
+Using the shared-cluster pattern is recommended whenever possible. Although the shared-cluster pattern has some disadvantages, as described above, its simplicity and ease of management outweigh those disadvantages. Moreover, since ScalarDB Cluster stores all critical states in their underlying databases and does not hold any critical states in its memory, it can be seen as just a path to the databases. Therefore, we believe a system with the shared-cluster pattern still complies with the database-per-service pattern and does not violate the microservice philosophy much.
+
+If the cons of the shared-cluster pattern are not acceptable, you can still use the separated-cluster pattern. However, you should use that pattern only if you properly understand the mechanism and usage of the two-phase commit interface. Otherwise, you might face some issues, like database anomalies.
+
+## Limitations
+
+ScalarDB provides several APIs, such as CRUD, SQL, and Spring Data JDBC. Although the CRUD and SQL interfaces support both the shared-cluster and separated-cluster patterns, the Spring Data JDBC interface does not support the shared-cluster pattern. This is because its one-phase commit interface currently assumes an application is monolithic, where it is not divided into microservices that interact with each other. The Spring Data JDBC interface supports the two-phase commit interface and the separated-cluster pattern, just as the other APIs do.
+
+## See also
+
+- [Transactions with a Two-Phase Commit Interface](../two-phase-commit-transactions.mdx)
+

docs/scalardb-cluster/images/scalardb-deployment-patterns.png

@@ -6,9 +6,9 @@ tags:
 displayed_sidebar: docsEnglish
 ---
 
-# ScalarDB Error Codes
+# ScalarDB Core Error Codes
 
-This page provides a list of error codes in ScalarDB.
+This page provides a list of error codes in ScalarDB Core.
 
 ## Error code classes and descriptions
 
@@ -1157,6 +1157,54 @@ The variable key column size must be greater than or equal to 64
 The value of the column %s in the primary key contains an illegal character. Primary-key columns must not contain any of the following characters in Cosmos DB: ':', '/', '\', '#', '?'. Value: %s
 ```
 
+### `CORE-10146`
+
+**Message**
+
+```markdown
+Inserting already-written data is not allowed
+```
+
+### `CORE-10147`
+
+**Message**
+
+```markdown
+Deleting already-inserted data is not allowed
+```
+
+### `CORE-10148`
+
+**Message**
+
+```markdown
+Invalid key: Column %s does not exist in the table %s in namespace %s.
+```
+
+### `CORE-10149`
+
+**Message**
+
+```markdown
+Invalid base64 encoding for blob value for column %s in table %s in namespace %s
+```
+
+### `CORE-10150`
+
+**Message**
+
+```markdown
+Invalid number specified for column %s in table %s in namespace %s
+```
+
+### `CORE-10151`
+
+**Message**
+
+```markdown
+Method null argument not allowed
+```
+
 ## `CORE-2xxxx` status codes
 
 ### `CORE-20000`

docs/scalardb-core-status-codes.mdx

@@ -0,0 +1,76 @@
+---
+tags:
+  - Enterprise Standard
+  - Enterprise Premium
+displayed_sidebar: docsJapanese
+---
+
+# マイクロサービスにおける ScalarDB Cluster のデプロイパターン
+
+import TranslationBanner from '/src/components/_translation-ja-jp.mdx';
+
+<TranslationBanner />
+
+ScalarDB Cluster を使用するマイクロサービスアプリケーションを構築する場合、ScalarDB Cluster のデプロイ方法として、共有クラスターパターンと分離クラスターパターンの2つのパターンを選択できます。
+このドキュメントでは、まずこれらのパターンについて説明し、それらの違いと、どの場合にどちらを選択するかの基本的なガイドラインを示します。
+
+また、このドキュメントでは、マイクロサービスアプリケーションが database-per-service パターンに基づいて作成されているものと想定しています。このパターンでは、各マイクロサービスがデータベースを管理し、マイクロサービスはマイクロサービス間の API を介して別のマイクロサービスのデータベースにアクセスする必要があります。
+
+## ScalarDB Cluster のデプロイパターン
+
+共有クラスターパターンでは、マイクロサービスはシステム内で1つの ScalarDB Cluster インスタンス (ScalarDB Cluster ノードのクラスタ) を共有するため、同じ ScalarDB Cluster インスタンスにアクセスしてデータベースとやり取りします。一方、分離クラスターパターンでは、マイクロサービスは複数の ScalarDB Cluster インスタンスを使用します。通常、1つのマイクロサービスが1つの ScalarDB Cluster インスタンスにアクセスして、データベースとやり取りします。
+
+次の図は2つのパターンを示しています。(MS はマイクロサービスの略です。)
+
+![マイクロサービスにおける ScalarDB Cluster のデプロイパターン。](images/scalardb-deployment-patterns.png)
+
+:::note
+
+どちらのパターンでも、マイクロサービスに必要なデータベースに加えて、Coordinator テーブルも管理する必要があります。
+
+:::
+
+## 長所と短所
+
+明らかな違いの1つは、ScalarDB Cluster インスタンスのリソースの量です。分離クラスターパターンでは、アプリケーションを管理するためのリソースが増えます。これにより、メンテナンスの負担とコストも増加します。
+
+さらに、使用する ScalarDB Cluster API も異なります。具体的には、共有クラスターパターンの場合、[1フェーズコミットインターフェース](../api-guide.mdx#transactional-api)を使用する必要があります。このインターフェースでは、マイクロサービスがレコードを読み書きした後、1つのマイクロサービスのみが `commit` を呼び出してトランザクションをコミットします。分離クラスターパターンの場合、[2フェーズコミットインターフェース](../two-phase-commit-transactions.mdx)を使用する必要があります。このインターフェースでは、すべてのマイクロサービスが最初に `prepare` を呼び出し、すべての`prepare` 呼び出しが成功した場合に `commit` を呼び出します。したがって、分離クラスターパターンのマイクロサービスは、トランザクションとそのエラーをよりきめ細かい方法で処理する必要があるため、共有クラスターパターンのマイクロサービスよりも複雑になる可能性があります。
+
+さらに、リソースの分離レベルも異なります。マイクロサービスは、保守性と開発効率を高めるために十分に分離されている必要がありますが、共有クラスターパターンではリソースの分離が弱くなります。リソースの分離が弱いと、セキュリティも弱くなる可能性があります。ただし、認証や承認などの ScalarDB Cluster のセキュリティ機能を使用することで、セキュリティリスクを軽減できます。
+
+同様に、システムの管理方法にも違いがあります。具体的には、共有クラスターパターンでは、他のチームに代わって ScalarDB Cluster インスタンスを管理するタスクをチームに割り当てる必要があります。通常は中央データチームが管理しますが、そのようなチームが存在しない場合は問題が発生する可能性があります。分離クラスターパターンでは、管理のバランスがより取れていますが、Coordinator テーブルに関して同様の問題が発生します。この問題は、調整用のマイクロサービスを用意し、1つのチームにそのマイクロサービスを管理させることで対処できます。
+
+次に、パターンの長所と短所をまとめます。
+
+### 共有クラスターパターン
+
+- **長所:**
+  - 1フェーズコミットインターフェースのため、トランザクションとエラーの処理が簡単です。(データベースのバックアップ操作も簡単です。)
+  - 1つの ScalarDB Cluster インスタンスを使用するため、リソース使用量が少なくなります。
+- **短所:**
+  - マイクロサービス間のリソース分離が弱い。
+  - 管理のバランスが取れていない。(1つのチームが他のチームに代わって ScalarDB Cluster インスタンスを管理する必要があります。)
+
+### 分離クラスターパターン
+
+- **利点:**
+  - リソースの分離が向上します。
+  - 管理のバランスがより取れます。(1つのチームが1つのマイクロサービスと1つの ScalarDB Cluster インスタンスを管理します。また、1つのチームに Coordinator ターテーブルの管理を任せる必要があります。)
+- **欠点:**
+  - 2フェーズコミットインターフェースによるトランザクションとエラー処理が複雑です。(データベースのバックアップ操作も複雑になることがあります。)
+  - 複数の ScalarDB Cluster インスタンスがあるため、リソース使用量が増加します。
+
+
+## どのパターンを選択するか
+
+可能な限り、共有クラスターパターンを使用することをお勧めします。共有クラスターパターンには前述のようにいくつかの欠点がありますが、そのシンプルさと管理のしやすさはそれらの欠点を上回ります。さらに、ScalarDB Cluster はすべての重要な状態を基盤となるデータベースに保存し、メモリには重要な状態を保持しないため、データベースへの単なるパスとして見ることができます。したがって、共有クラスターパターンのシステムは依然としてサービスごとのデータベースパターンに準拠しており、マイクロサービスの理念にあまり違反していないと考えています。
+
+共有クラスターパターンの欠点が受け入れられない場合は、分離クラスターパターンを使用できます。ただし、2フェーズコミットインターフェースのメカニズムと使用方法を適切に理解している場合にのみ、このパターンを使用してください。そうでない場合、データベースの異常などの問題が発生する可能性があります。
+
+## 制限事項
+
+ScalarDB は、CRUD、SQL、Spring Data JDBC などのいくつかの API を提供します。 CRUD および SQL インターフェースは共有クラスターパターンと分離クラスターパターンの両方をサポートしていますが、Spring Data JDBC インターフェースは共有クラスターパターンをサポートしていません。これは、Spring Data JDBC の1フェーズコミットインターフェースが現在、アプリケーションがモノリシックであり、相互にやり取りするマイクロサービスに分割されていないことを前提としているためです。Spring Data JDBC インターフェースは、他の API と同様に、2フェーズコミットインターフェースと分離クラスターパターンをサポートしています。
+
+## 参照
+
+- [2フェーズコミットインターフェースを使用したトランザクション](../two-phase-commit-transactions.mdx)

i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-cluster/deployment-patterns-for-microservices.mdx

@@ -6,13 +6,13 @@ tags:
 displayed_sidebar: docsJapanese
 ---
 
-# ScalarDB エラーコード
+# ScalarDB Core エラーコード
 
 import TranslationBanner from '/src/components/_translation-ja-jp.mdx';
 
 <TranslationBanner />
 
-このページでは、ScalarDB のエラーコードの一覧を示します。
+このページでは、ScalarDB Core のエラーコードの一覧を示します。
 
 ## エラーコードのクラスと説明
 
@@ -206,7 +206,7 @@ The clustering key is not properly specified. Operation: %s
 **メッセージ**
 
 ```markdown
-The encryption feature is not enabled. To encrypt data at rest, you must enable this feature. Note that this feature is supported only in the ScalarDB Enterprise edition
+The authentication and authorization feature is not enabled. To use this feature, you must enable it. Note that this feature is supported only in the ScalarDB Enterprise edition
 ```
 
 ### `CORE-10023`
@@ -1142,7 +1142,7 @@ This operation is supported only when no conditions are specified. If you want t
 **メッセージ**
 
 ```markdown
-ScalarDB Transparent Data Encryption is not enabled. To use ScalarDB Transparent Data Encryption, you must enable it. Note that this feature is supported only in the ScalarDB Enterprise edition
+The encryption feature is not enabled. To encrypt data at rest, you must enable this feature. Note that this feature is supported only in the ScalarDB Enterprise edition
 ```
 
 ### `CORE-10144`
@@ -1161,6 +1161,54 @@ The variable key column size must be greater than or equal to 64
 The value of the column %s in the primary key contains an illegal character. Primary-key columns must not contain any of the following characters in Cosmos DB: ':', '/', '\', '#', '?'. Value: %s
 ```
 
+### `CORE-10146`
+
+**メッセージ**
+
+```markdown
+Inserting already-written data is not allowed
+```
+
+### `CORE-10147`
+
+**メッセージ**
+
+```markdown
+Deleting already-inserted data is not allowed
+```
+
+### `CORE-10148`
+
+**メッセージ**
+
+```markdown
+Invalid key: Column %s does not exist in the table %s in namespace %s.
+```
+
+### `CORE-10149`
+
+**メッセージ**
+
+```markdown
+Invalid base64 encoding for blob value for column %s in table %s in namespace %s
+```
+
+### `CORE-10150`
+
+**メッセージ**
+
+```markdown
+Invalid number specified for column %s in table %s in namespace %s
+```
+
+### `CORE-10151`
+
+**メッセージ**
+
+```markdown
+Method null argument not allowed
+```
+
 ## `CORE-2xxxx` ステータスコード
 
 ### `CORE-20000`
@@ -1610,7 +1658,7 @@ Fetching the next result failed
 **メッセージ**
 
 ```markdown
-Rolling back the transaction failed
+Rolling back the transaction failed. Details: %s
 ```
 
 ### `CORE-30030`