CHANGELOG.md

Author: asmyasnikov

CHANGELOG.md

@@ -1,3 +1,5 @@
+* Added `table.DefaultTxControl()` transaction control creator with serializable read-write isolation mode and auto-commit
+* Fixed passing nil query parameters
 * Fixed locking of cluster during call `cluster.Get`
 
 ## v3.19.1

CREDENTIALS.md

@@ -1,20 +1,96 @@
-# ydb-go-sdk
+# `ydb-go-sdk` - native Go's driver for [YDB](https://github.com/ydb-platform/ydb).
 
 [![PkgGoDev](https://pkg.go.dev/badge/github.com/ydb-platform/ydb-go-sdk/v3)](https://pkg.go.dev/github.com/ydb-platform/ydb-go-sdk/v3)
-[![GoDoc](https://godoc.org/github.com/ydb-platform/ydb-go-sdk/v3?status.svg)](https://godoc.org/github.com/ydb-platform/ydb-go-sdk/v3)
 ![tests](https://github.com/ydb-platform/ydb-go-sdk/workflows/tests/badge.svg?branch=master)
 ![lint](https://github.com/ydb-platform/ydb-go-sdk/workflows/lint/badge.svg?branch=master)
 [![Go Report Card](https://goreportcard.com/badge/github.com/ydb-platform/ydb-go-sdk/v3)](https://goreportcard.com/report/github.com/ydb-platform/ydb-go-sdk/v3)
 [![codecov](https://codecov.io/gh/ydb-platform/ydb-go-sdk/branch/master/graph/badge.svg?precision=2)](https://app.codecov.io/gh/ydb-platform/ydb-go-sdk)
 
-[YDB](https://github.com/ydb-platform/ydb) native Go's driver.
+Supports `table`, `discovery`, `coordination`, `ratelimiter`, `scheme` and `scripting` clients for `YDB`. 
+`YDB` is an open-source Distributed SQL Database that combines high availability and scalability with strict consistency and ACID transactions.
 
-Supports `table`, `discovery`, `coordination`, `ratelimiter`, `scheme` and `scripting` clients for `YDB`.
+## Example Usage <a name="example"></a>
 
-Simple example see in [example](example_table_test.go). More examples of usage placed in [examples](https://github.com/ydb-platform/ydb-go-examples) repository.
+* connect to YDB
+    ```
+    db, err := ydb.New(ctx,
+        ydb.WithConnectionString("grpcs://localhost:2135/?database=/local"),
+        ydb.WithAnonymousCredentials(),
+    )
+    if err != nil {
+        log.Fatal(err)
+    }
+    ```
+* execute `SELECT` query
+    ```
+    const query = `SELECT 42 as id, "myStr" as myStr;`
+    
+    // Do retry operation on errors with best effort
+    queryErr := db.Table().Do(ctx, func(ctx context.Context, s table.Session) (err error) {
+        _, res, err := s.Execute(ctx, table.DefaultTxControl(), query, nil)
+        if err != nil {
+            return err
+        }
+        defer res.Close()
+        if err = res.NextResultSetErr(ctx); err != nil {
+            return err 
+        }
+        for res.NextRow() {
+            var id    int32   
+            var myStr string 
+            err = res.ScanNamed(named.Required("id", &id),named.OptionalWithDefault("myStr", &myStr))
+            if err != nil {
+                log.Fatal(err)
+            }
+			log.Printf("id=%v, myStr='%s'\n", id, myStr)
+        }
+        return res.Err() // for driver retry if not nil
+    })
+    if queryErr != nil {
+        log.Fatal(queryErr)
+    }
+    ```
+More examples of usage placed in [examples](https://github.com/ydb-platform/ydb-go-examples) repository.
+
+## Credentials <a name="credentials"></a>
+
+Driver contains two options for making simple `credentials.Credentials`:
+- `ydb.WithAnonymousCredentials()`
+- `ydb.WithAccessTokenCredentials("token")`
+
+Another variants of `credentials.Credentials` object provides with external packages:
+
+Package | Type | Description                                                                                                                                                                                 | Link of example usage
+--- | --- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ---
+[ydb-go-yc](https://github.com/ydb-platform/ydb-go-yc) | credentials | credentials provider for Yandex.Cloud | [yc.WithServiceAccountKeyFileCredentials](https://github.com/ydb-platform/ydb-go-yc/blob/master/internal/cmd/connect/main.go#L22)
+[yc.WithInternalCA](https://github.com/ydb-platform/ydb-go-yc/blob/master/internal/cmd/connect/main.go#L22) [yc.WithMetadataCredentials](https://github.com/ydb-platform/ydb-go-yc/blob/master/internal/cmd/connect/main.go#L24)
+[ydb-go-yc-metadata](https://github.com/ydb-platform/ydb-go-yc-metadata) | credentials | metadata credentials provider for Yandex.Cloud | [yc.WithInternalCA](https://github.com/ydb-platform/ydb-go-yc-metadata/blob/master/options.go#L23) [yc.WithCredentials](https://github.com/ydb-platform/ydb-go-yc-metadata/blob/master/options.go#L17)
+[ydb-go-sdk-auth-environ](https://github.com/ydb-platform/ydb-go-sdk-auth-environ) | credentials | create credentials from environ | [ydbEnviron.WithEnvironCredentials](https://github.com/ydb-platform/ydb-go-sdk-auth-environ/blob/master/env.go#L11)
+
+## Ecosystem of debug tools over `ydb-go-sdk` <a name="debug"></a>
+
+Package `ydb-go-sdk` provide debugging over trace events in package `trace`.
+Next packages provide debug tooling:
+
+Package | Type | Description                                                                                                                                                                                 | Link of example usage
+--- | --- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ---
+[ydb-go-sdk-zap](https://github.com/ydb-platform/ydb-go-sdk-zap) | logging | logging ydb-go-sdk events with zap package                                                                                                                                                  | [ydbZap.WithTraces](https://github.com/ydb-platform/ydb-go-sdk-zap/blob/master/internal/cmd/bench/main.go#L64)
+[ydb-go-sdk-zerolog](https://github.com/ydb-platform/ydb-go-sdk-zap) | logging | logging ydb-go-sdk events with zerolog package                                                                                                                                              | [ydbZerolog.WithTraces](https://github.com/ydb-platform/ydb-go-sdk-zerolog/blob/master/internal/cmd/bench/main.go#L47)
+[ydb-go-sdk-metrics](https://github.com/ydb-platform/ydb-go-sdk-metrics) | metrics | common metrics of ydb-go-sdk. Package declare interfaces such as `Registry`, `GaugeVec` and `Gauge` and use it for traces                           |
+[ydb-go-sdk-prometheus](https://github.com/ydb-platform/ydb-go-sdk-prometheus) | metrics | prometheus wrapper over [ydb-go-sdk-metrics](https://github.com/ydb-platform/ydb-go-sdk-metrics) | [ydbPrometheus.WithTraces](https://github.com/ydb-platform/ydb-go-sdk-prometheus/blob/master/internal/cmd/bench/main.go#L56)
+[ydb-go-sdk-opentracing](https://github.com/ydb-platform/ydb-go-sdk-opentracing) | tracing | opentracing plugin for trace internal ydb-go-sdk calls | [ydbOpentracing.WithTraces](https://github.com/ydb-platform/ydb-go-sdk-opentracing/blob/master/internal/cmd/bench/main.go#L86)
+
+## Environment variables <a name="environ"></a>
+
+`ydb-go-sdk` supports next environment variables  which redefines default behavior of driver
+
+Name | Type | Default | Description
+--- | --- | --- | ---
+`YDB_SSL_ROOT_CERTIFICATES_FILE` | `string` | | path to certificates file
+`YDB_LOG_SEVERITY_LEVEL` | `string` | `quiet` | severity logging level of internal driver logger. Supported: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `quiet`
+`YDB_LOG_NO_COLOR` | `bool` | `false` | set any non empty value to disable colouring logs with internal driver logger
+`GRPC_GO_LOG_VERBOSITY_LEVEL` | `integer` | | set to `99` to see grpc logs
+`GRPC_GO_LOG_SEVERITY_LEVEL` | `string` | | set to `info` to see grpc logs
 
-See also [CREDENTIALS.md](CREDENTIALS.md) about supported YDB credentials.
 
-See [DEBUG.md](DEBUG.md) about supported debug tooling over `ydb-go-sdk`.
 
-See [ENVIRON.md](ENVIRON.md) about supported environment variables of `ydb-go-sdk`.

DEBUG.md

@@ -223,7 +223,7 @@ func (c *connection) Scripting() scripting.Client {
 	return c.scripting
 }
 
-// New connects to name and return name runtime holder
+// New connects to database and return driver runtime holder
 func New(ctx context.Context, opts ...Option) (_ Connection, err error) {
 	c := &connection{
 		opts:     opts,

ENVIRON.md

@@ -7,11 +7,9 @@ import (
 	"github.com/ydb-platform/ydb-go-sdk/v3"
 	"github.com/ydb-platform/ydb-go-sdk/v3/table"
 	"github.com/ydb-platform/ydb-go-sdk/v3/table/result/named"
-	"github.com/ydb-platform/ydb-go-sdk/v3/table/types"
 )
 
-// nolint: govet
-func Example_TableUsage() {
+func Example_tableSelect() {
 	ctx := context.Background()
 	db, err := ydb.New(ctx,
 		ydb.WithConnectionString("grpcs://localhost:2135/?database=/local"),
@@ -24,23 +22,14 @@ func Example_TableUsage() {
 		_ = db.Close(ctx)
 	}()
 	var (
-		txControl = table.TxControl(
-			table.BeginTx(table.WithSerializableReadWrite()), table.CommitTx(),
-		) // for managing transaction control during Execute
-		query = `
-			DECLARE $myStr AS Utf8; 
-			SELECT 42 as id, $myStr as myStr;
-		`
-		queryParams = table.NewQueryParameters(
-			table.ValueParam("$myStr", types.UTF8Value("test")),
-		) // ydb typed params for query
-		id    int32   // required value
-		myStr *string // optional value
+		query = `SELECT 42 as id, "my string" as myStr`
+		id    int32  // required value
+		myStr string // optional value
 	)
 	err = db.Table().Do( // Do retry operation on errors with best effort
 		ctx, // context manage exiting from Do
 		func(ctx context.Context, s table.Session) (err error) { // retry operation
-			_, res, err := s.Execute(ctx, txControl, query, queryParams)
+			_, res, err := s.Execute(ctx, table.DefaultTxControl(), query, nil)
 			if err != nil {
 				return err // for driver retry
 			}
@@ -53,12 +42,12 @@ func Example_TableUsage() {
 			for res.NextRow() { // iterate over rows
 				err = res.ScanNamed(
 					named.Required("id", &id),
-					named.Optional("myStr", &myStr),
+					named.OptionalWithDefault("myStr", &myStr),
 				)
 				if err != nil {
 					return err
 				}
-				log.Printf("id=%v, myStr=%v\n", id, *myStr)
+				log.Printf("id=%v, myStr='%s'\n", id, myStr)
 			}
 			return res.Err() // for driver retry if not nil
 		},

README.md

@@ -625,6 +625,10 @@ func (s *session) Execute(
 	q := new(dataQuery)
 	q.initFromText(query)
 
+	if params == nil {
+		params = table.NewQueryParameters()
+	}
+
 	onDone := trace.TableOnSessionQueryExecute(s.config.Trace(), &ctx, s, q, params)
 	defer func() {
 		onDone(txr, true, r, err)

connection.go

@@ -279,6 +279,14 @@ func TxControl(opts ...TxControlOption) *TransactionControl {
 	return c
 }
 
+// DefaultTxControl returns default transaction control with serializable read-write isolation mode and auto-commit
+func DefaultTxControl() *TransactionControl {
+	return TxControl(
+		BeginTx(WithSerializableReadWrite()),
+		CommitTx(),
+	)
+}
+
 // QueryParameters
 
 type (