Merge pull request #361 from zinal/SQL.md-b1

asmyasnikov · web-flow · commit 50b9184eb647 · 2022-08-29T17:03:19.000+03:00
Sql.md b1
diff --git a/SQL.md b/SQL.md
@@ -1,22 +1,25 @@
 # `database/sql` driver for `YDB`
 
-Package `ydb-go-sdk` provides usage `database/sql` API also. 
-`database/sql` driver implementation use `ydb-go-sdk` native driver API's.
+In addition to native YDB Go driver APIs, package `ydb-go-sdk` provides standard APIs for `database/sql`.
+It allows to use "regular" Go facilities to access YDB databases.
+Behind the scene, `database/sql` APIs are implemented using the native interfaces.
+
 
 ## Table of contents
 1. [Initialization of `database/sql` driver](#init)
    * [Configure driver with `ydb.Connector` (recommended way)](#init-connector)
-   * [Configure driver only with data source name (connection string)](#init-dsn)
-2. [About session pool](#session-pool)
-3. [Execute queries](#queries)
-   * [On database object](#queries-db)
-   * [With transaction](#queries-tx)
+   * [Configure driver with data source name or connection string](#init-dsn)
+2. [Session pooling](#session-pool)
+3. [Query execution](#queries)
+   * [Queries on database object](#queries-db)
+   * [Queries on transaction object](#queries-tx)
 4. [Query modes (DDL, DML, DQL, etc.)](#query-modes)
-5. [Retry helpers for `YDB` `database/sql` driver](#retry)
-   * [Over `sql.Conn` object](#retry-conn)
-   * [Over `sql.Tx`](#retry-tx)
-6. [Query args types](#arg-types)
-7. [Get native driver from `*sql.DB`](#unwrap)
+5. [Changing the transaction control mode](#tx-control)
+6. [Retry helpers for `YDB` `database/sql` driver](#retry)
+   * [Retries over `sql.Conn` object](#retry-conn)
+   * [Retries over `sql.Tx`](#retry-tx)
+7. [Specifying query parameters](#arg-types)
+8. [Accessing the native driver from `*sql.DB`](#unwrap)
 
 ## Initialization of `database/sql` driver <a name="init"></a>
 
@@ -43,7 +46,8 @@ func main() {
     db := sql.OpenDB(connector)
 }
 ```
-### Configure driver only with data source name (connection string) <a name="init-dsn"></a>
+
+### Configure driver with data source name or connection string <a name="init-dsn"></a>
 ```go
 import (
     _ "github.com/ydb-platform/ydb-go-sdk/v3"
@@ -58,23 +62,24 @@ Data source name parameters:
 * static credentials with authority part of URI, like `grpcs://root:password@localhost:2135/local`
 * `query_mode=scripting` - you can redefine default [DML](https://en.wikipedia.org/wiki/Data_manipulation_language) query mode
 
-## About session pool <a name="session-pool"></a>
+## Session pooling <a name="session-pool"></a>
 
-Native driver `ydb-go-sdk/v3` implements internal session pool, which uses with `db.Table().Do()` or `db.Table().DoTx()` methods.
-Internal session pool configures with options like `ydb.WithSessionPoolSizeLimit()` and other.
-Unlike session pool in native driver, `database/sql` contains another session pool, which configures with `*sql.DB.SetMaxOpenConns` and `*sql.DB.SetMaxIdleConns`.
-Lifetime of `YDB` session depends on driver configuration and predefined errors, such as `sql.driver.ErrBadConn`.
-`YDB` driver for `database/sql` transform internal `YDB` errors into `sql.driver.ErrBadConn` depending on result of internal error check (delete session on error or not and other).
-In most cases this behaviour of `database/sql` driver implementation for specific RDBMS completes queries without result errors.
-But some errors on unfortunate cases may be get on client-side.
-That's why querying must be wrapped with retry helpers, such as `retry.Do` or `retry.DoTx` (see more about retry helpers in [retry section](#retry)).
+Native driver `ydb-go-sdk/v3` implements the internal session pool, which uses with `db.Table().Do()` or `db.Table().DoTx()` methods.
+Internal session pool is configured with options like `ydb.WithSessionPoolSizeLimit()` and other.
+Unlike the session pool in the native driver, `database/sql` contains a different implementation of the session pool, which is configured with `*sql.DB.SetMaxOpenConns` and `*sql.DB.SetMaxIdleConns`.
+Lifetime of a `YDB` session depends on driver configuration and error occurance, such as `sql.driver.ErrBadConn`.
+`YDB` driver for `database/sql` includes the logic to transform the internal `YDB` error codes into `sql.driver.ErrBadConn` and other retryable and non-retryable error types.
 
-## Execute queries <a name="queries"></a>
+In most cases the implementation of `database/sql` driver for YDB allows to complete queries without user-visible errors.
+But some errors need to be handled on the client side, by re-running not a single operation, but a complete transaction.
+Therefore the transaction logic needs to be wrapped with retry helpers, such as `retry.Do` or `retry.DoTx` (see more about retry helpers in the [retry section](#retry)).
 
-### On database object <a name="queries-db"></a>
+## Query execution <a name="queries"></a>
+
+### Queries on database object <a name="queries-db"></a>
 ```go
 rows, err := db.QueryContext(ctx,
-    "SELECT series_id, title, release_date FROM /full/path/of/table/series;"
+    "SELECT series_id, title, release_date FROM `/full/path/of/table/series`;"
 )
 if err != nil {
     log.Fatal(err)
@@ -97,19 +102,23 @@ if err = rows.Err(); err != nil { // always check final rows err
 }
 ```
 
-### With transaction <a name="queries-tx"></a>
-Supports only `default` transaction options which mapped to `YDB` `SerializableReadWrite` transaction settings.
+### Queries on transaction object <a name="queries-tx"></a>
+Query execution on transaction object supports only `default` transaction options
+which are mapped to `YDB` `SerializableReadWrite` transaction settings.
+
+`YDB`'s `OnlineReadOnly` and `StaleReadOnly` transaction settings are not compatible
+with interactive transactions such as `database/sql`'s `*sql.Tx`.
+That's why `ydb-go-sdk` implements read-only `sql.LevelSnapshot` with fake transaction
+(temporary, until `YDB` starts to support true snapshot isolation mode).
 
-`YDB`'s `OnlineReadOnly` and `StaleReadOnly` transaction settings are not compatible with interactive transactions such as `database/sql`'s `*sql.Tx`.
-That's why `ydb-go-sdk` implements read-only `sql.LevelSnapshot` with fake transaction (temporary, while `YDB` main clusters are supports true snapshot isolation mode)
 ```go
 tx, err := db.BeginTx(ctx, sql.TxOptions{})
 if err != nil {
     log.Fatal(err)
 }
 defer tx.Rollback()
 rows, err := tx.QueryContext(ctx,
-    "SELECT series_id, title, release_date FROM /full/path/of/table/series;"
+    "SELECT series_id, title, release_date FROM `/full/path/of/table/series`;"
 )
 if err != nil {
     log.Fatal(err)
@@ -134,48 +143,56 @@ if err = tx.Commit(); err != nil {
     log.Fatal(err)
 }
 ```
+
 ## Query modes (DDL, DML, DQL, etc.) <a name="query-modes"></a>
-The `YDB` server API is currently requires to select a specific method by specific request type. For example, [DDL](https://en.wikipedia.org/wiki/Data_definition_language) must be called with `table.session.ExecuteSchemeQuery`, [DML](https://en.wikipedia.org/wiki/Data_manipulation_language) must be called with `table.session.Execute`, [DQL](https://en.wikipedia.org/wiki/Data_query_language) may be called with `table.session.Execute` or `table.session.StreamExecuteScanQuery` etc. `YDB` have a `scripting` service also, which provides different query types with single method, but not supports transactions.
+Currently the `YDB` server APIs require the use of a proper GRPC service method depending on the specific request type.
+In particular, [DDL](https://en.wikipedia.org/wiki/Data_definition_language) must be called through `table.session.ExecuteSchemeQuery`,
+[DML](https://en.wikipedia.org/wiki/Data_manipulation_language) needs `table.session.Execute`, and
+[DQL](https://en.wikipedia.org/wiki/Data_query_language) should be passed via `table.session.Execute` or `table.session.StreamExecuteScanQuery`.
+`YDB` also has a so-called "scripting" service, which supports different query types within a single method,
+but without support for transactions.
 
-That's why needs to select query mode on client side currently.
+Unfortunately, this leads to the need to choose the proper query mode on the application side.
 
-`YDB` team have a roadmap goal to implements a single method for executing different query types.
+`YDB` team has a roadmap goal to implement a single universal service method for executing
+different query types and without the limitations of the "scripting" service method.
 
-`database/sql` driver implementation for `YDB` supports next query modes:
+`database/sql` driver implementation for `YDB` supports the following query modes:
 * `ydb.DataQueryMode` - default query mode, for lookup [DQL](https://en.wikipedia.org/wiki/Data_query_language) queries and [DML](https://en.wikipedia.org/wiki/Data_manipulation_language) queries.
-* `ydb.ExplainQueryMode` - for gettting plan and [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree) of some query
-* `ydb.ScanQueryMode` - for strong [OLAP](https://en.wikipedia.org/wiki/Online_analytical_processing) scenarious, [DQL-only](https://en.wikipedia.org/wiki/Data_query_language) queries. Read more about scan queries in [ydb.tech](https://ydb.tech/en/docs/concepts/scan_query)
+* `ydb.ExplainQueryMode` - for gettting plan and [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree) of the query
+* `ydb.ScanQueryMode` - for heavy [OLAP](https://en.wikipedia.org/wiki/Online_analytical_processing) style scenarious, with [DQL-only](https://en.wikipedia.org/wiki/Data_query_language) queries. Read more about scan queries in [ydb.tech](https://ydb.tech/en/docs/concepts/scan_query)
 * `ydb.SchemeQueryMode` - for [DDL](https://en.wikipedia.org/wiki/Data_definition_language) queries
-* `ydb.ScriptingQueryMode` - for [DDL](https://en.wikipedia.org/wiki/Data_definition_language), [DML](https://en.wikipedia.org/wiki/Data_manipulation_language), [DQL](https://en.wikipedia.org/wiki/Data_query_language) queries (not a [TCL](https://en.wikipedia.org/wiki/SQL#Transaction_controls)). Be careful: queries executes longer than with other query modes and consumes bigger server-side resources
+* `ydb.ScriptingQueryMode` - for [DDL](https://en.wikipedia.org/wiki/Data_definition_language), [DML](https://en.wikipedia.org/wiki/Data_manipulation_language), [DQL](https://en.wikipedia.org/wiki/Data_query_language) queries (not a [TCL](https://en.wikipedia.org/wiki/SQL#Transaction_controls)). Be careful: queries execute longer than with other query modes, and consume more server-side resources
 
-Example for changing default query mode:
+Example for changing the default query mode:
 ```go
 res, err = db.ExecContext(ydb.WithQueryMode(ctx, ydb.SchemeQueryMode),
    "DROP TABLE `/full/path/to/table/series`",
 )
 ```
 
-## Specify `YDB` transaction control <a name="tx-control"></a>
+## Changing the transaction control mode <a name="tx-control"></a>
 
-Default `YDB`'s transaction control is a `SerializableReadWrite`. 
-Default transaction control outside interactive transactions may be changed with context:
+Default `YDB`'s transaction control mode is a `SerializableReadWrite`. 
+Default transaction control mode can be changed outside of interactive transactions by updating the context object:
 ```
 ctx := ydb.WithTxControl(ctx, table.OnlineReadOnlyTxControl())
 ```
 
 ## Retry helpers for `YDB` `database/sql` driver <a name="retry"></a>
 
 `YDB` is a distributed `RDBMS` with non-stop 24/7 releases flow.
-It means some nodes may be not available for queries.
-Also network errors may be occurred.
-That's why some queries may be complete with errors.
+It means some nodes may be unavailable for queries at some point in time.
+Network errors may also occur.
+That's why some queries may complete with errors.
 Most of those errors are transient.
-`ydb-go-sdk`'s "knows" what to do on specific error: retry or not, with or without backoff, with or whithout deleting session, etc.
-`ydb-go-sdk` provides retry helpers which can work either with plain database connection object, or with interactive transaction object.
+`ydb-go-sdk`'s "knows" what to do on specific error: retry or not, with or without backoff, with or without the need to re-establish the session, etc.
+`ydb-go-sdk` provides retry helpers which can work either with the database connection object, or with the transaction object.
 
-### Over `sql.Conn` object <a name="retry-conn"></a>
+### Retries over `sql.Conn` object <a name="retry-conn"></a>
 
-`retry.Do` helper allow custom lambda, which must return error for processing or nil if retry operation is ok.
+`retry.Do` helper accepts custom lambda, which must return error if it happens during the processing,
+or nil if the operation succeeds.
 ```
 import (
     "github.com/ydb-platform/ydb-go-sdk/v3/retry"
@@ -193,11 +210,15 @@ err := retry.Do(context.TODO(), db, func(ctx context.Context, cc *sql.Conn) erro
 
 ```
 
-### Over `sql.Tx` <a name="retry-tx"></a>
+### Retries over `sql.Tx` <a name="retry-tx"></a>
+
+`retry.DoTx` helper accepts custom lambda, which must return error if it happens during processing,
+or nil if the operation succeeds.
 
-`retry.DoTx` helper allow custom lambda, which must return error for processing or nil if retry operation is ok.
+`tx` object is a prepared transaction object.
+
+The logic within the custom lambda does not need the explicit commit or rollback at the end - `retry.DoTx` does it automatically.
 
-`tx` object is a prepared transaction object which not requires commit or rollback at the end - `retry.DoTx` do it automatically.    
 ```
 import (
     "github.com/ydb-platform/ydb-go-sdk/v3/retry"
@@ -219,10 +240,10 @@ err := retry.DoTx(context.TODO(), db, func(ctx context.Context, tx *sql.Tx) erro
 }))
 ```
 
-## Query args types <a name="arg-types"></a>
+## Specifying query parameters <a name="arg-types"></a>
 
-`database/sql` driver for `YDB` supports next types of query args:
-* multiple `sql.NamedArg` (uniform `database/sql` arg)
+`database/sql` driver for `YDB` supports the following types of query parameters:
+* multiple `sql.NamedArg` arguments (standard `database/sql` query parameters)
    ```
    rows, err := cc.QueryContext(ctx, `
           DECLARE $seasonTitle AS Utf8;
@@ -233,7 +254,7 @@ err := retry.DoTx(context.TODO(), db, func(ctx context.Context, tx *sql.Tx) erro
       sql.Named("views", uint64(1000)),
    )
    ```
-* multiple native for `ydb-go-sdk` `table.ParameterOption` which constructs from `table.ValueParam("name", value)`
+* multiple native `ydb-go-sdk` `table.ParameterOption` arguments which are constructed with `table.ValueParam("name", value)`
    ```
    rows, err := cc.QueryContext(ctx, `
           DECLARE $seasonTitle AS Utf8;
@@ -244,7 +265,7 @@ err := retry.DoTx(context.TODO(), db, func(ctx context.Context, tx *sql.Tx) erro
       table.ValueParam("views", types.Uint64Value((1000)),
    )
    ```
-* single native for `ydb-go-sdk` `*table.QueryParameters` which constructs from `table.NewQueryParameters(parameterOptions...)`
+* single native `ydb-go-sdk` `*table.QueryParameters` argument which are constructed with `table.NewQueryParameters(parameterOptions...)`
    ```
    rows, err := cc.QueryContext(ctx, `
           DECLARE $seasonTitle AS Utf8;
@@ -257,7 +278,8 @@ err := retry.DoTx(context.TODO(), db, func(ctx context.Context, tx *sql.Tx) erro
       ),
    )
    ```
-## Get native driver from `*sql.DB` <a name="unwrap"></a>
+
+## Accessing the native driver from `*sql.DB` <a name="unwrap"></a>
 
 ```
 db, err := sql.Open("ydb", "grpcs://localhost:2135/local")
