* Changed output of sugar.GenerateDeclareSection (added error as second result)

* Specified `sugar.GenerateDeclareSection` for `go1.18` (supports input types `*table.QueryParameters` `[]table.ParameterOption` or `[]sql.NamedArg`)
* Added `database/sql` example and docs (WIP)

Author: asmyasnikov

CHANGELOG.md

@@ -1,3 +1,7 @@
+* Changed output of `sugar.GenerateDeclareSection` (added error as second result)
+* Specified `sugar.GenerateDeclareSection` for `go1.18` (supports input types `*table.QueryParameters` `[]table.ParameterOption` or `[]sql.NamedArg`)
+* Added `database/sql` example and docs (WIP)
+
 ## v3.36.1
 * Fixed `xsql.Rows` error checking
 

README.md

@@ -59,7 +59,7 @@ if queryErr != nil {
     log.Fatal(queryErr)
 }
 ```
-* usage with `database/sql`
+* usage with `database/sql` (see additional docs in [SQL.md](SQL.md) )
 ```golang
 import (
     "context"

SQL.md

@@ -0,0 +1,57 @@
+# `database/sql` driver for `YDB`
+
+## Initialization of `database/sql` driver
+
+### Configure driver with `ydb.Connector` (recommended way)
+    ```
+    import (
+        "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
+        )
+        if err != nil {
+            // fallback on error
+        }
+        connector, err := ydb.Connector(nativeDriver,
+            // See ydb.ConnectorOption's for configure connector
+        )
+        if err != nil {
+            // fallback on error
+        }
+        db := sql.OpenDB(connector)
+    }
+    ```
+### Configure driver only with data source name (connection string)
+    ```
+    import (
+        _ "github.com/ydb-platform/ydb-go-sdk/v3"
+    )
+    
+    func main() {
+        db, err := sql.Open("ydb", "grpcs://localhost:2135/local")
+    }
+    ```
+    Data source name parameters:
+    * `token` – access token to be used during requests (required)
+    * static credentials with authority part of URI, like `grpcs://root:password@localhost:2135/local`
+    * `query_mode=scripting` - you can redefine default `data` query mode
+
+## Execute queries
+
+### On database object
+
+### With transaction
+
+## Query modes
+
+## Specify `YDB` transaction control 
+
+## Retryer's for `YDB` `database/sql` driver
+
+### Over `sql.Conn` object
+
+### Over `sql.Tx`

doc.go

@@ -55,6 +55,31 @@ func Example_table() {
 	}
 }
 
+func Example_databaseSQL() {
+	db, err := sql.Open("ydb", "grpcs://localhost:2135/local")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer db.Close() // cleanup resources
+
+	var (
+		query = `SELECT 42 as id, "my string" as myStr`
+		id    int32  // required value
+		myStr string // optional value
+	)
+	err = retry.DoTx(context.TODO(), db, func(ctx context.Context, tx *sql.Tx) error {
+		row := tx.QueryRowContext(ctx, query)
+		if err = row.Scan(&id, &myStr); err != nil {
+			return err
+		}
+		log.Printf("id=%v, myStr='%s'\n", id, myStr)
+		return nil
+	}, retry.WithDoTxRetryOptions(retry.WithIdempotent(true)))
+	if err != nil {
+		log.Fatal(err)
+	}
+}
+
 func Example_databaseSql() {
 	db, err := sql.Open("ydb", "grpcs://localhost:2135/local")
 	if err != nil {

example_test.go

@@ -5,14 +5,17 @@ import (
 	"fmt"
 	"sort"
 
+	"github.com/ydb-platform/ydb-go-sdk/v3/internal/xerrors"
 	"github.com/ydb-platform/ydb-go-sdk/v3/table"
 	"github.com/ydb-platform/ydb-go-sdk/v3/table/types"
 )
 
+var ErrNameRequired = xerrors.Wrap(fmt.Errorf("ydb: only named parameters are supported"))
+
 // GenerateDeclareSection generates DECLARE section text in YQL query by params
 //
 // Warning: This is an experimental feature and could change at any time
-func GenerateDeclareSection(params *table.QueryParameters) string {
+func GenerateDeclareSection(params *table.QueryParameters) (string, error) {
 	var (
 		buf      bytes.Buffer
 		names    []string
@@ -28,7 +31,10 @@ func GenerateDeclareSection(params *table.QueryParameters) string {
 	})
 	sort.Strings(names)
 	for _, name := range names {
+		if name == "" {
+			return "", xerrors.WithStackTrace(ErrNameRequired)
+		}
 		buf.WriteString(declares[name])
 	}
-	return buf.String()
+	return buf.String(), nil
 }

internal/table/params.go

@@ -6,7 +6,6 @@ import (
 	"database/sql/driver"
 	"fmt"
 	"sync/atomic"
-	"time"
 
 	"github.com/ydb-platform/ydb-go-sdk/v3/internal/retry"
 	"github.com/ydb-platform/ydb-go-sdk/v3/internal/xerrors"
@@ -15,7 +14,6 @@ import (
 	"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/result"
-	"github.com/ydb-platform/ydb-go-sdk/v3/table/types"
 	"github.com/ydb-platform/ydb-go-sdk/v3/trace"
 )
 
@@ -112,56 +110,7 @@ func (c *conn) setClosed() {
 }
 
 func (conn) CheckNamedValue(v *driver.NamedValue) (err error) {
-	if v.Name == "" {
-		return fmt.Errorf("ydb: only named parameters are supported")
-	}
-
-	if valuer, ok := v.Value.(driver.Valuer); ok {
-		v.Value, err = valuer.Value()
-		if err != nil {
-			return fmt.Errorf("ydb: driver.Valuer error: %w", err)
-		}
-	}
-
-	switch x := v.Value.(type) {
-	case types.Value:
-		// OK.
-	case bool:
-		v.Value = types.BoolValue(x)
-	case int8:
-		v.Value = types.Int8Value(x)
-	case uint8:
-		v.Value = types.Uint8Value(x)
-	case int16:
-		v.Value = types.Int16Value(x)
-	case uint16:
-		v.Value = types.Uint16Value(x)
-	case int32:
-		v.Value = types.Int32Value(x)
-	case uint32:
-		v.Value = types.Uint32Value(x)
-	case int64:
-		v.Value = types.Int64Value(x)
-	case uint64:
-		v.Value = types.Uint64Value(x)
-	case float32:
-		v.Value = types.FloatValue(x)
-	case float64:
-		v.Value = types.DoubleValue(x)
-	case []byte:
-		v.Value = types.StringValue(x)
-	case string:
-		v.Value = types.UTF8Value(x)
-	case [16]byte:
-		v.Value = types.UUIDValue(x)
-	case time.Time:
-		v.Value = types.DateValueFromTime(x)
-
-	default:
-		return xerrors.WithStackTrace(fmt.Errorf("ydb: unsupported type: %T", x))
-	}
-
-	return nil
+	return checkNamedValue(v)
 }
 
 func (c *conn) PrepareContext(ctx context.Context, query string) (_ driver.Stmt, err error) {

internal/xsql/conn.go

@@ -0,0 +1,122 @@
+package xsql
+
+import (
+	"database/sql"
+	"database/sql/driver"
+	"fmt"
+	internal "github.com/ydb-platform/ydb-go-sdk/v3/internal/table"
+	"github.com/ydb-platform/ydb-go-sdk/v3/internal/xerrors"
+	"time"
+
+	"github.com/ydb-platform/ydb-go-sdk/v3/table"
+	"github.com/ydb-platform/ydb-go-sdk/v3/table/types"
+)
+
+func toQueryParams(values []driver.NamedValue) *table.QueryParameters {
+	if len(values) == 0 {
+		return nil
+	}
+	opts := make([]table.ParameterOption, len(values))
+	for i, arg := range values {
+		switch v := arg.Value.(type) {
+		case types.Value:
+			opts[i] = table.ValueParam(arg.Name, arg.Value.(types.Value))
+		case table.ParameterOption:
+			opts[i] = v
+		case *table.QueryParameters:
+			if len(values) != 1 {
+				panic("only one arg with type *table.QueryParameters are supported")
+			}
+			return v
+		default:
+			panic(fmt.Sprintf("unsupported type: %T", v))
+		}
+	}
+	return table.NewQueryParameters(opts...)
+}
+
+func primitiveToValue(v interface{}) (value types.Value, err error) {
+	if valuer, ok := v.(driver.Valuer); ok {
+		v, err = valuer.Value()
+		if err != nil {
+			return nil, fmt.Errorf("ydb: driver.Valuer error: %w", err)
+		}
+	}
+
+	switch x := v.(type) {
+	case types.Value:
+		return x, nil
+	case bool:
+		return types.BoolValue(x), nil
+	case int8:
+		return types.Int8Value(x), nil
+	case uint8:
+		return types.Uint8Value(x), nil
+	case int16:
+		return types.Int16Value(x), nil
+	case uint16:
+		return types.Uint16Value(x), nil
+	case int32:
+		return types.Int32Value(x), nil
+	case uint32:
+		return types.Uint32Value(x), nil
+	case int64:
+		return types.Int64Value(x), nil
+	case uint64:
+		return types.Uint64Value(x), nil
+	case float32:
+		return types.FloatValue(x), nil
+	case float64:
+		return types.DoubleValue(x), nil
+	case []byte:
+		return types.StringValue(x), nil
+	case string:
+		return types.UTF8Value(x), nil
+	case [16]byte:
+		return types.UUIDValue(x), nil
+	case time.Time:
+		return types.DateValueFromTime(x), nil
+	default:
+		return nil, xerrors.WithStackTrace(fmt.Errorf("ydb: unsupported type: %T", x))
+	}
+}
+
+func checkNamedValue(v *driver.NamedValue) (err error) {
+	if v.Name == "" {
+		switch v.Value.(type) {
+		case table.ParameterOption:
+			return nil
+		case *table.QueryParameters:
+			return nil
+		default:
+			return xerrors.WithStackTrace(internal.ErrNameRequired)
+		}
+	}
+
+	value, err := primitiveToValue(v.Value)
+	if err != nil {
+		return xerrors.WithStackTrace(err)
+	}
+
+	v.Value = value
+
+	return nil
+}
+
+// GenerateDeclareSection generates DECLARE section text in YQL query by params
+//
+// Warning: This is an experimental feature and could change at any time
+func GenerateDeclareSection(args []sql.NamedArg) (string, error) {
+	values := make([]table.ParameterOption, len(args))
+	for i, arg := range args {
+		if arg.Name == "" {
+			return "", xerrors.WithStackTrace(internal.ErrNameRequired)
+		}
+		value, err := primitiveToValue(arg.Value)
+		if err != nil {
+			return "", xerrors.WithStackTrace(err)
+		}
+		values[i] = table.ValueParam(arg.Name, value)
+	}
+	return internal.GenerateDeclareSection(table.NewQueryParameters(values...))
+}

internal/xsql/convert.go

@@ -1,3 +1,6 @@
+//go:build !go1.18
+// +build !go1.18
+
 package sugar
 
 import (
@@ -8,6 +11,6 @@ import (
 // GenerateDeclareSection generates DECLARE section text in YQL query by params
 //
 // Warning: This is an experimental feature and could change at any time
-func GenerateDeclareSection(params *table.QueryParameters) string {
+func GenerateDeclareSection(params *table.QueryParameters) (string, error) {
 	return internal.GenerateDeclareSection(params)
 }