Merge pull request #197 from ydb-platform/readme

simplify README.md + add table.DefaultTxControl()

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

@@ -0,0 +1,7 @@
+// Package ydb-go-sdk - native Go's driver for YDB.
+/*
+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.
+*/
+package ydb

README.md

@@ -10,60 +10,78 @@ import (
 	"github.com/ydb-platform/ydb-go-sdk/v3/ratelimiter"
 )
 
+// IterateByIssues helps to iterate over internal issues of operation error
 func IterateByIssues(err error, it func(message string, code Ydb.StatusIds_StatusCode, severity uint32)) {
 	xerrors.IterateByIssues(err, it)
 }
 
+// IsTimeoutError checks whether given err is a some timeout error (context, transport or operation)
 func IsTimeoutError(err error) bool {
 	return xerrors.IsTimeoutError(err)
 }
 
+// IsTransportError checks whether given err is a transport (grpc) error
 func IsTransportError(err error, codes ...grpcCodes.Code) bool {
 	return xerrors.IsTransportError(err, codes...)
 }
 
+// Error is an interface of error which reports about error code and error name
 type Error xerrors.Error
 
+// TransportError checks when given error is a transport error and returns description of transport error
 func TransportError(err error) Error {
 	return xerrors.TransportError(err)
 }
 
+// IsYdbError reports when given error is and ydb error (transport, operation or internal driver error)
 func IsYdbError(err error) bool {
 	return xerrors.IsYdb(err)
 }
 
+// IsOperationError reports whether any error is an operation error with one of passed codes
+// If codes not defined IsOperationError returns true on error is an operation error
 func IsOperationError(err error, codes ...Ydb.StatusIds_StatusCode) bool {
 	return xerrors.IsOperationError(err, codes...)
 }
 
+// OperationError returns operation error description
+// If given err is not an operation error - returns nil
 func OperationError(err error) Error {
 	return xerrors.OperationError(err)
 }
 
+// IsOperationErrorOverloaded checks whether given err is an operation error with code Overloaded
 func IsOperationErrorOverloaded(err error) bool {
 	return IsOperationError(err, Ydb.StatusIds_OVERLOADED)
 }
 
+// IsOperationErrorUnavailable checks whether given err is an operation error with code Unavailable
 func IsOperationErrorUnavailable(err error) bool {
 	return IsOperationError(err, Ydb.StatusIds_UNAVAILABLE)
 }
 
+// IsOperationErrorAlreadyExistsError checks whether given err is an operation error with code AlreadyExistsError
 func IsOperationErrorAlreadyExistsError(err error) bool {
 	return IsOperationError(err, Ydb.StatusIds_ALREADY_EXISTS)
 }
 
+// IsOperationErrorNotFoundError checks whether given err is an operation error with code NotFoundError
 func IsOperationErrorNotFoundError(err error) bool {
 	return IsOperationError(err, Ydb.StatusIds_NOT_FOUND)
 }
 
+// IsOperationErrorSchemeError checks whether given err is an operation error with code SchemeError
 func IsOperationErrorSchemeError(err error) bool {
 	return IsOperationError(err, Ydb.StatusIds_SCHEME_ERROR)
 }
 
+// IsRatelimiterAcquireError checks whether given err is an ratelimiter acquire error
 func IsRatelimiterAcquireError(err error) bool {
 	return ratelimiterErrors.IsAcquireError(err)
 }
 
+// ToRatelimiterAcquireError casts given err to ratelimiter.AcquireError
+// If given err is not ratelimiter acquire error - returns nil
 func ToRatelimiterAcquireError(err error) ratelimiter.AcquireError {
 	return ratelimiterErrors.ToAcquireError(err)
 }

connection.go

@@ -0,0 +1,70 @@
+package ydb_test
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"time"
+
+	"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/types"
+)
+
+func Example_tableBulkUpsert() {
+	ctx := context.Background()
+	db, err := ydb.New(ctx,
+		ydb.WithConnectionString("grpcs://localhost:2135/?database=/local"),
+		ydb.WithAnonymousCredentials(),
+	)
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer func() {
+		_ = db.Close(ctx)
+	}()
+	type logMessage struct {
+		App       string
+		Host      string
+		Timestamp time.Time
+		HTTPCode  uint32
+		Message   string
+	}
+	// prepare native go data
+	const batchSize = 10000
+	logs := make([]logMessage, 0, batchSize)
+	for i := 0; i < batchSize; i++ {
+		message := logMessage{
+			App:       fmt.Sprintf("App_%d", i/256),
+			Host:      fmt.Sprintf("192.168.0.%d", i%256),
+			Timestamp: time.Now().Add(time.Millisecond * time.Duration(i%1000)),
+			HTTPCode:  200,
+		}
+		if i%2 == 0 {
+			message.Message = "GET / HTTP/1.1"
+		} else {
+			message.Message = "GET /images/logo.png HTTP/1.1"
+		}
+		logs = append(logs, message)
+	}
+	// execute bulk upsert with native ydb data
+	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
+			rows := make([]types.Value, 0, len(logs))
+			for _, msg := range logs {
+				rows = append(rows, types.StructValue(
+					types.StructFieldValue("App", types.UTF8Value(msg.App)),
+					types.StructFieldValue("Host", types.UTF8Value(msg.Host)),
+					types.StructFieldValue("Timestamp", types.TimestampValueFromTime(msg.Timestamp)),
+					types.StructFieldValue("HTTPCode", types.Uint32Value(msg.HTTPCode)),
+					types.StructFieldValue("Message", types.UTF8Value(msg.Message)),
+				))
+			}
+			return s.BulkUpsert(ctx, "/local/bulk_upsert_example", types.ListValue(rows...))
+		},
+	)
+	if err != nil {
+		log.Printf("unexpected error: %v", err)
+	}
+}

doc.go

@@ -0,0 +1,42 @@
+package ydb_test
+
+import (
+	"context"
+	"log"
+	"path"
+
+	"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/options"
+	"github.com/ydb-platform/ydb-go-sdk/v3/table/types"
+)
+
+func Example_tableCreateTable() {
+	ctx := context.Background()
+	db, err := ydb.New(ctx,
+		ydb.WithConnectionString("grpcs://localhost:2135/?database=/local"),
+		ydb.WithAnonymousCredentials(),
+	)
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer func() {
+		_ = db.Close(ctx)
+	}()
+	err = db.Table().Do(
+		ctx,
+		func(ctx context.Context, s table.Session) (err error) {
+			return s.CreateTable(ctx, path.Join(db.Name(), "series"),
+				options.WithColumn("series_id", types.Optional(types.TypeUint64)),
+				options.WithColumn("title", types.Optional(types.TypeUTF8)),
+				options.WithColumn("series_info", types.Optional(types.TypeUTF8)),
+				options.WithColumn("release_date", types.Optional(types.TypeDate)),
+				options.WithColumn("comment", types.Optional(types.TypeUTF8)),
+				options.WithPrimaryKeyColumn("series_id"),
+			)
+		},
+	)
+	if err != nil {
+		log.Printf("unexpected error: %v", err)
+	}
+}