docs

Author: asmyasnikov

MIGRATION_v2_v3.md

@@ -8,10 +8,11 @@
 3. [Connect to `YDB` using connection string](#connect-dsn)
 4. [Make table client and session pool](#table-client)
 5. [Execute query with table client and session pool](#execute-queries)
-6. [Scan query result into local variables](#scan-result)
-7. [Logging SDK's events](#logs)
-8. [Add metrics about SDK's events](#metrics)
-9. [Add `Jaeger` traces about SDK's events](#jaeger)
+6. [About truncated result](#truncated)
+7. [Scan query result into local variables](#scan-result)
+8. [Logging SDK's events](#logs)
+9. [Add metrics about SDK's events](#metrics)
+10. [Add `Jaeger` traces about SDK's events](#jaeger)
 
 ## Imports <a name="imports"></a>
 - in `v2`: 
@@ -141,7 +142,74 @@
   if err != nil {
     // error fallback
   }
-  ```  
+  ```
+
+## About truncated result <a name="truncated"></a>
+
+Call of `session.Execute` may returns a result with a flag `Truncated` because `YDB` have a default limit of rows is a 1000.
+In this case query must be changed for supporting pagination. Trucated flag in result must be checks explicitly.
+- in `v2`:
+  ```go
+  var res *table.Result
+  err := table.Retry(ctx, sp,
+    table.OperationFunc(
+        func(ctx context.Context, s *table.Session) (err error) {
+            _, res, err = s.Execute(ctx, readTx, "SELECT 1+1")
+            if err != nil {
+              // error fallback
+            }
+            for res.NextStreamSet(ctx) {
+                for res.NextRow() {
+                   // process column values
+                }
+            }
+            if err := res.Err(); err != nil {
+                // error fallback
+            }
+            if res.Trucated() {
+                // alarm to query developers
+            }
+            return nil
+        },
+    ),
+  }
+  if err != nil {
+    // error fallback
+  }
+  ```
+- in `v3`:
+  By default, truncated result wraps as non-retryable error
+  ```go
+  import (
+    "github.com/ydb-platform/ydb-go-sdk/v3/table/result"  
+  )
+  ...
+  var res result.Result
+  err := db.Table().Do(ctx,
+    func(ctx context.Context, s table.Session) (err error) {
+        _, res, err = s.Execute(ctx, readTx, "SELECT 1+1")
+        if err != nil {
+            // error fallback
+        }
+        for res.NextStreamSet(ctx) {
+            for res.NextRow() {
+               // process column values
+            }
+        }
+        // no need to check truncated result explicitly 
+        // if res.Truncated() {
+        //   // alarm to query developers
+        // }
+        return res.Err()
+    },
+    table.WithIdempotent(), // only idempotent queries
+  )
+  if err != nil {
+    // error fallback
+  }
+  ```
+  But if default behaviour are not allowed, wrapping truncated result as error may be disabled with option `ydb.WithIgnoreTruncated` 
+
 
 ## Scan query result into local variables <a name="scan-result"></a>
 - in `v2`: 
@@ -276,9 +344,10 @@
        ydbMetrics "github.com/ydb-platform/ydb-go-sdk-prometheus"
     )
     ...
+	registry := prometheus.NewRegistry()
     db, err := ydb.Open(ctx, connectionString,
       ...
-      ydbMetrics.WithTraces(log, trace.DriverConnEvents | trace.DriverClusterEvents),
+      ydbMetrics.WithTraces(registry, ydbMetrics.WithDetails(trace.DetailsAll)),
     )
     ```
   * metrics to other monitoring systems may be add with common package `"github.com/ydb-platform/ydb-go-sdk-metrics"`
@@ -301,7 +370,7 @@
   ...
   db, err := ydb.Open(ctx, connectionString,
     ...
-    ydbTracing.WithTraces(log, trace.DriverConnEvents | trace.DriverClusterEvents | trace.DriverRepeaterEvents | trace.DiscoveryEvents),
+    ydbTracing.WithTraces(trace.DriverConnEvents | trace.DriverClusterEvents | trace.DriverRepeaterEvents | trace.DiscoveryEvents),
   )
   ```  
 

SQL.md

@@ -17,25 +17,30 @@ Package `ydb-go-sdk` provides usage `database/sql` API also.
    * [Over `sql.Tx`](#retry-tx)
 6. [Query args types](#arg-types)
 7. [Get native driver from `*sql.DB`](#unwrap)
+8. [Logging SDK's events](#logs)
+9. [Add metrics about SDK's events](#metrics)
+10. [Add `Jaeger` traces about driver events](#jaeger)
 
 ## Initialization of `database/sql` driver <a name="init"></a>
 
 ### Configure driver with `ydb.Connector` (recommended way) <a name="init-connector"></a>
 ```go
 import (
+	"database/sql"
+	
     "github.com/ydb-platform/ydb-go-sdk/v3"
 )
 
 func main() {
     // init native ydb-go-sdk driver
     nativeDriver, err := ydb.Open(context.TODO(), "grpcs://localhost:2135/local",
-        // See many ydb.Option's for configure driver
+        // See many ydb.Option's for configure driver https://pkg.go.dev/github.com/ydb-platform/ydb-go-sdk/v3#Option
     )
     if err != nil {
         // fallback on error
     }
     connector, err := ydb.Connector(nativeDriver,
-        // See ydb.ConnectorOption's for configure connector
+        // See ydb.ConnectorOption's for configure connector https://pkg.go.dev/github.com/ydb-platform/ydb-go-sdk/v3#ConnectorOption
     )
     if err != nil {
         // fallback on error
@@ -46,6 +51,8 @@ func main() {
 ### Configure driver only with data source name (connection string) <a name="init-dsn"></a>
 ```go
 import (
+	"database/sql"
+	
     _ "github.com/ydb-platform/ydb-go-sdk/v3"
 )
 
@@ -259,7 +266,7 @@ err := retry.DoTx(context.TODO(), db, func(ctx context.Context, tx *sql.Tx) erro
    ```
 ## Get native driver from `*sql.DB` <a name="unwrap"></a>
 
-```
+```go
 db, err := sql.Open("ydb", "grpcs://localhost:2135/local")
 if err != nil {
     t.Fatal(err)
@@ -273,3 +280,78 @@ nativeDriver.Table().Do(ctx, func(ctx context.Context, s table.Session) error {
     return nil
 })
 ```
+
+## Logging driver events <a name="logging"></a>
+
+Adding a logging driver events allowed only if connection to `YDB` opens over [connector](##init-connector).
+Adding of logging provides with [debug adapters](README.md#debug) and wrotes in [migration notes](MIGRATION_v2_v3.md#logs)
+Example of adding `zap` logging:
+```go
+import (
+    "github.com/ydb-platform/ydb-go-sdk/v3/trace"
+	ydbZap "github.com/ydb-platform/ydb-go-sdk-zap"
+)
+...
+nativeDriver, err := ydb.Open(ctx, connectionString,
+    ...
+    ydbZap.WithTraces(log, trace.DetailsAll),
+)
+if err != nil {
+    // fallback on error
+}
+connector, err := ydb.Connector(nativeDriver)
+if err != nil {
+    // fallback on error
+}
+db := sql.OpenDB(connector)
+```
+
+## Add metrics about SDK's events <a name="metrics"></a>
+
+Adding of driver events monitoring allowed only if connection to `YDB` opens over [connector](##init-connector).
+Monitoring of driver events provides with [debug adapters](README.md#debug) and wrotes in [migration notes](MIGRATION_v2_v3.md#metrics)
+Example of adding `Prometheus` monitoring:
+```go
+import (
+    "github.com/ydb-platform/ydb-go-sdk/v3/trace"
+    ydbMetrics "github.com/ydb-platform/ydb-go-sdk-prometheus"
+)
+...
+nativeDriver, err := ydb.Open(ctx, connectionString,
+    ...
+    ydbMetrics.WithTraces(registry, ydbMetrics.WithDetails(trace.DetailsAll)),
+)
+if err != nil {
+    // fallback on error
+}
+connector, err := ydb.Connector(nativeDriver)
+if err != nil {
+    // fallback on error
+}
+db := sql.OpenDB(connector)
+```
+
+## Add `Jaeger` traces about driver events <a name="jaeger"></a>
+
+Adding of `Jaeger` traces about driver events allowed only if connection to `YDB` opens over [connector](##init-connector).
+`Jaeger` tracing provides with [debug adapters](README.md#debug) and wrotes in [migration notes](MIGRATION_v2_v3.md#jaeger)
+Example of adding `Jaeger` tracing:
+```go
+import (
+    "github.com/ydb-platform/ydb-go-sdk/v3/trace"
+    ydbOpentracing "github.com/ydb-platform/ydb-go-sdk-opentracing"
+)
+...
+nativeDriver, err := ydb.Open(ctx, connectionString,
+    ...
+    ydbOpentracing.WithTraces(trace.DriverConnEvents | trace.DriverClusterEvents | trace.DriverRepeaterEvents | trace.DiscoveryEvents),
+)
+if err != nil {
+    // fallback on error
+}
+connector, err := ydb.Connector(nativeDriver)
+if err != nil {
+    // fallback on error
+}
+db := sql.OpenDB(connector)
+```