Merge pull request #124 from scalar-labs/add-new-docs

Add new docs for the ScalarDB Cluster .NET Client SDK

_data/navigation.yml

@@ -81,10 +81,12 @@ versions:
         url: /docs/latest/getting-started-with-scalardb/
       - title: "Getting Started with ScalarDB by Using Kotlin"
         url: /docs/latest/getting-started-with-scalardb-by-using-kotlin/
-      - title: "Getting Started with ScalarDB Cluster"
-        url: /docs/latest/scalardb-cluster/getting-started-with-scalardb-cluster-overview/
       - title: "Getting Started with ScalarDB Analytics with PostgreSQL"
         url: /docs/latest/scalardb-analytics-postgresql/getting-started/
+      - title: "Getting Started with ScalarDB Cluster"
+        url: /docs/latest/scalardb-cluster/getting-started-with-scalardb-cluster-overview/
+      - title: "Getting Started with the ScalarDB Cluster .NET Client SDK"
+        url: /docs/latest/scalardb-cluster-dotnet-client-sdk/
   # Samples docs
   - title: "Samples" 
     children:
@@ -229,10 +231,10 @@ versions:
         url: /docs/3.10/getting-started-with-scalardb/
       - title: "Getting Started with ScalarDB by Using Kotlin"
         url: /docs/3.10/getting-started-with-scalardb-by-using-kotlin/
-      - title: "Getting Started with ScalarDB Cluster"
-        url: /docs/3.10/scalardb-cluster/getting-started-with-scalardb-cluster-overview/
       - title: "Getting Started with ScalarDB Analytics with PostgreSQL"
         url: /docs/3.10/scalardb-analytics-postgresql/getting-started/
+      - title: "Getting Started with ScalarDB Cluster"
+        url: /docs/3.10/scalardb-cluster/getting-started-with-scalardb-cluster-overview/
   # Samples docs
   - title: "Samples" 
     children:
@@ -371,10 +373,10 @@ versions:
         url: /docs/3.9/getting-started-with-scalardb/
       - title: "Getting Started with ScalarDB by Using Kotlin"
         url: /docs/3.9/getting-started-with-scalardb-by-using-kotlin/
-      - title: "Getting Started with ScalarDB Cluster"
-        url: /docs/3.9/scalardb-cluster/getting-started-with-scalardb-cluster-overview/
       - title: "Getting Started with ScalarDB Analytics with PostgreSQL"
         url: /docs/3.9/scalardb-analytics-postgresql/getting-started/
+      - title: "Getting Started with ScalarDB Cluster"
+        url: /docs/3.9/scalardb-cluster/getting-started-with-scalardb-cluster-overview/
   # Samples docs
   - title: "Samples" 
     children:

docs/3.10/scalardb-cluster/getting-started-with-scalardb-cluster-overview.md

@@ -1,6 +1,6 @@
 # Getting Started with ScalarDB Cluster
 
-The following is tutorials for getting started with using ScalarDB Cluster:
+The following are tutorials for getting started with using ScalarDB Cluster:
 
 - [Getting Started with ScalarDB Cluster](getting-started-with-scalardb-cluster.md)
 - [Getting Started with ScalarDB Cluster GraphQL](getting-started-with-scalardb-cluster-graphql.md)

docs/3.11/scalardb-cluster-dotnet-client-sdk/getting-started-with-admin-api.md

@@ -0,0 +1,104 @@
+# Getting Started with the Administrative API in the ScalarDB Cluster .NET Client SDK
+
+The ScalarDB Cluster .NET Client SDK supports the Administrative API of ScalarDB Cluster. By using this API, you can manage ScalarDB Cluster from .NET applications.
+
+{% capture notice--info %}
+**Note**
+
+Although we recommend using asynchronous methods as in the following examples, you can use synchronous methods instead.
+{% endcapture %}
+
+<div class="notice--info">{{ notice--info | markdownify }}</div>
+
+## Get a transaction manager
+
+First, you need to get an object for interacting with the Administrative API. To get the object, you can use `TransactionFactory` as follows, replacing `<CLUSTER_URL>` with the URL of your cluster:
+
+```c#
+var scalarDbOptions = new ScalarDbOptions
+                      {
+                         Address = "http://<CLUSTER_URL>:60053"
+                         HopLimit = 10
+                      };
+var factory = TransactionFactory.Create(scalarDbOptions);
+
+using var admin = factory.GetTransactionAdmin();
+```
+
+## Manage ScalarDB Cluster
+
+The following operations can be performed by using the ScalarDB Cluster .NET Client SDK.
+
+### Create a new namespace
+
+```c#
+await admin.CreateNamespaceAsync("ns", ifNotExists: true);
+```
+
+### Drop a namespace
+
+```c#
+await admin.DropNamespaceAsync("ns", ifExists: true);
+```
+
+### Check if a namespace exists
+
+```c#
+var namespaceExists = await admin.IsNamespacePresentAsync("ns");
+```
+
+### Create a new table
+
+```c#
+using Scalar.Db.Cluster.Rpc.V1;
+// ...
+using ScalarDB.Net.Client.Builders;
+
+// ...
+
+var tableMetadata =
+    new TableMetadataBuilder()
+        .AddPartitionKey("pk", DataType.Int)
+        .AddClusteringKey("ck", DataType.Double)
+        .AddSecondaryIndex("index", DataType.Float)
+        .AddColumn("ordinary", DataType.Text)
+        .Build();
+
+await admin.CreateTableAsync("ns", "table_name", tableMetadata, ifNotExists: true);
+```
+
+### Drop a table
+
+```c#
+await admin.DropTableAsync("ns", "table_name", ifExists: true);
+```
+
+### Checking if a table exists
+
+```c#
+var tableExists = await admin.IsTablePresentAsync("ns", "table_name");
+```
+
+### Get the names of existing tables
+
+```c#
+var tablesList = await admin.GetTableNamesAsync("ns");
+```
+
+### Create the Coordinator table
+
+```c#
+await admin.CreateCoordinatorTablesAsync();
+```
+
+### Drop the Coordinator table
+
+```c#
+await admin.DropCoordinatorTablesAsync();
+```
+
+### Check if the Coordinator table exist
+
+```c#
+var exists = await admin.AreCoordinatorTablesPresentAsync();
+```

docs/3.11/scalardb-cluster-dotnet-client-sdk/getting-started-with-aspnet-and-di.md

@@ -0,0 +1,49 @@
+# Getting Started with ASP.NET Core and Dependency Injection in the ScalarDB Cluster .NET Client SDK
+
+The ScalarDB Cluster .NET Client SDK supports Dependency Injection in frameworks like ASP.NET Core.
+
+You can register the ScalarDB Cluster transaction managers as services in `IServiceCollection` as follows, replacing `<CLUSTER_URL>` with the URL of your cluster:
+
+```c#
+using ScalarDB.Net.Client.Extensions;
+
+//...
+
+var builder = WebApplication.CreateBuilder(args);
+
+//...
+
+builder.Services.AddScalarDbCluster(options =>
+{
+    options.Address = "http:\\<CLUSTER_URL>:60053";
+    options.HopLimit = 10;
+    options.EnableCrud = true; // true by default
+    options.EnableSql = true; // false by default
+    options.EnableAdmin = true; // false by default
+});
+```
+
+After registering the transaction managers, they can be injected into the controller's constructor as follows:
+
+```c#
+[ApiController]
+public class OrderController: ControllerBase
+{
+    private readonly IDistributedTransactionManager _manager;
+
+    public OrderController(IDistributedTransactionManager manager)
+    {
+        _manager = manager;
+    }
+}
+```
+
+Although these examples are for WebApi projects, the examples will work in a similar way in GrpcService projects.
+
+### `AddScalarDbCluster`-specific options
+
+This section describes some specific options for `AddScalarDbCluster`:
+
+- **EnableCrud:** Enables the transaction managers for executing CRUD operations. `IDistributedTransactionManager` and `ITwoPhaseCommitTransactionManager` will become available for injection.
+- **EnableSql:** Enables the transaction managers for executing SQL statements. `ISqlTransactionManager` and `ISqlTwoPhaseCommitTransactionManager` will become available for injection.    
+- **EnableAdmin:** Enables the administrative interface. `IDistributedTransactionAdmin` will become available for injection.

docs/3.11/scalardb-cluster-dotnet-client-sdk/getting-started-with-auth.md

@@ -0,0 +1,27 @@
+# Getting Started with ScalarDB Auth by Using ScalarDB Cluster .NET Client SDK
+
+The ScalarDB Cluster .NET Client SDK supports [ScalarDB Auth](https://github.com/scalar-labs/scalardb-cluster/blob/main/docs/scalardb-auth-with-sql.md), which allows you to authenticate and authorize your requests to ScalarDB Cluster.
+
+## Set credentials in `ScalarDbOptions`
+
+First, you need to get a transaction manager or transaction admin object with credentials by using `TransactionFactory` as follows, replacing the contents in the angle brackets as described. Also, be sure to replace `<GET_TRANSACTION_MANAGER>` with `GetTransactionManager()`, `GetTwoPhaseCommitTransactionManager()`, `GetSqlTransactionManager()`, or `GetSqlTwoPhaseCommitTransactionManager()`.  
+
+```c#
+var scalarDbOptions = new ScalarDbOptions
+                      {
+                         Address = "http://<CLUSTER_URL>:60053"
+                         HopLimit = 10,
+                         AuthEnabled = true,
+                         Username = "<USERNAME>",
+                         Password = "<PASSWORD>"
+                      };
+var factory = TransactionFactory.Create(scalarDbOptions);
+
+// To get a transaction manager
+using var manager = factory.<GET_TRANSACTION_MANAGER>();
+
+// To get a transaction admin
+using var admin = factory.GetTransactionAdmin();
+```
+
+A transaction manager or transaction admin object created from `TransactionFactory` with the provided credentials will automatically log in to ScalarDB Cluster and can communicate with it.

docs/3.11/scalardb-cluster-dotnet-client-sdk/getting-started-with-distributed-sql-transactions.md

@@ -0,0 +1,112 @@
+# Getting Started with Distributed SQL Transactions in the ScalarDB Cluster .NET Client SDK
+
+The ScalarDB Cluster .NET Client SDK supports the distributed SQL transaction functionality of ScalarDB Cluster. The SDK includes transaction and manager abstractions for easier communication within a cluster.
+
+{% capture notice--info %}
+**Note**
+
+Although we recommend using asynchronous methods, as in the following examples, you can use synchronous methods instead.
+{% endcapture %}
+
+<div class="notice--info">{{ notice--info | markdownify }}</div>
+
+For details about distributed non-SQL transactions, see [Getting Started with Distributed Transactions in the ScalarDB Cluster .NET Client SDK](getting-started-with-distributed-transactions.md).
+
+## Get a transaction manager
+
+First, you need to get a transaction manager object for distributed SQL transactions. To get the transaction manager object, you can use `TransactionFactory` as follows, replacing `<CLUSTER_URL>` with the URL of your cluster:
+
+```c#
+var scalarDbOptions = new ScalarDbOptions
+                      {
+                         Address = "http://<CLUSTER_URL>:60053"
+                         HopLimit = 10
+                      };
+var factory = TransactionFactory.Create(scalarDbOptions);
+
+using var manager = factory.GetSqlTransactionManager();
+```
+
+## Execute SQL queries
+
+To execute a SQL statement, you need a `SqlStatement` object, which can be created by using a builder as follows:
+
+```c#
+using ScalarDB.Net.Client.Builders;
+
+// ...
+
+var sqlStatement =
+    new SqlStatementBuilder()
+        .SetSql("SELECT * FROM order_service.statements WHERE item_id = :item_id")
+        .AddParam("item_id", 2)
+        .Build();
+```
+
+A single SQL statement can be executed directly by using the transaction manager as follows:
+
+```c#
+var resultSet = await manager.ExecuteAsync(sqlStatement);
+```
+
+The result from the `ExecuteAsync` method will contain records received from the cluster. The SDK has `GetValue`, `TryGetValue`, and `IsNull` extension methods to simplify using the records:
+
+```c#
+using ScalarDB.Net.Client.Extensions;
+
+// ...
+
+foreach (var record in resultSet.Records)
+{
+    // Getting an integer value from the "item_id" column.
+    // If it fails, an exception will be thrown.
+    var itemId = record.GetValue<int>("item_id");
+
+    // Trying to get a string value from the "order_id" column.
+    // If it fails, no exception will be thrown.
+    if (record.TryGetValue<string>("order_id", out var orderId))
+        Console.WriteLine($"order_id: {orderId}");
+
+    // Checking if the "count" column is null.
+    if (record.IsNull("count"))
+        Console.WriteLine("'count' is null");
+}
+```
+
+## Execute SQL queries in a transaction
+
+To execute multiple SQL statements as part of a single transaction, you need a transaction object.
+
+You can create a transaction object by using the transaction manager as follows:
+
+```c#
+var transaction = await manager.BeginAsync();
+```
+
+You can also resume a transaction that has already been started as follows:
+
+```c#
+var transaction = manager.Resume(transactionIdString);
+```
+
+{% capture notice--info %}
+**Note**
+
+The `Resume` method doesn't have an asynchronous version because it only creates a transaction object. Because of this, resuming a transaction by using the wrong ID is possible.
+{% endcapture %}
+
+<div class="notice--info">{{ notice--info | markdownify }}</div>
+
+The transaction has the same `ExecuteAsync` method as the transaction manager. That method can be used to execute SQL statements.
+
+When a transaction is ready to be committed, you can call the `CommitAsync` method of the transaction as follows:
+
+```c#
+await transaction.CommitAsync();
+```
+
+To roll back the transaction, you can use the `RollbackAsync` method:
+
+```c#
+await transaction.RollbackAsync();
+```