github.com/ydb-platform/ydb-go-sdk/v3@v3.57.0/SQL_MIGRATION_v2_v3.md (about)

     1  # Migration from `ydb-go-sdk/v2` to `ydb-go-sdk/v3` with `database/sql` API driver usages
     2  
     3  > Article contains some cases for migrate from `github.com/yandex-cloud/ydb-go-sdk/v2/ydbsql` to `github.com/ydb-platform/ydb-go-sdk/v3`
     4  
     5  > Note: the article is being updated.
     6  
     7  ## `sql.Connector` initialization
     8  
     9  Package `database/sql` provides two ways for making driver:
    10  - from connection string (see [sql.Open(driverName, connectionString)](https://pkg.go.dev/database/sql#Open))
    11  - from custom connector (see [sql.OpenDB(connector)](https://pkg.go.dev/database/sql#OpenDB))
    12  
    13  Second way (making driver from connector) are different in `v2` and `v3`:
    14  - in `v2`:
    15    `ydbsql.Connector` returns single result (`sql.driver.Connector`) and init driver lazy on first request. This design causes rare errors. 
    16    ```go
    17    db := sql.OpenDB(ydbsql.Connector(
    18      ydbsql.WithDialer(dialer),
    19      ydbsql.WithEndpoint(params.endpoint),
    20      ydbsql.WithClient(&table.Client{
    21        Driver: driver,
    22      }),
    23    ))
    24    defer db.Close()
    25    ```
    26  - in `v3`:
    27    `ydb.Connector` creates `sql.driver.Connector` from native `YDB` driver, returns two results (`sql.driver..Connector` and error) and exclude some lazy driver initialization.
    28    ```go
    29    nativeDriver, err := ydb.Open(context.TODO(), "grpc://localhost:2136/local")
    30    if err != nil {
    31      // fallback on error
    32    }
    33    defer nativeDriver.Close(context.TODO())
    34    connector, err := ydb.Connector(nativeDriver)
    35    if err != nil {
    36      // fallback on error
    37    }
    38    db := sql.OpenDB(connector)
    39    defer db.Close()
    40    ```
    41  
    42  ## Read-only isolation levels
    43  
    44  In `ydb-go-sdk/v2/ydbsql` was allowed `sql.LevelReadCommitted` and `sql.LevelReadUncommitted` isolation levels for read-only interactive transactions. It implements with fake transaction with true `OnlineReadOnly` transaction control on each query inside transaction.
    45  
    46  Transaction controls `OnlineReadOnly` and `StaleReadOnly` will deprecate in the future.
    47  
    48  That's why `ydb-go-sdk/v3` allowed only `sql.LevelSnapshot` for read-only interactive transactions. Currently, snapshot isolation implements over `fake` transaction with true `OnlineReadOnly` transaction control on each request inside transaction.
    49  YDB implements snapshot isolation, but this feature is not deployed on YDB clusters now. After full deploying on each YDB cluster fake transaction will be replaced to true read-only interactive transaction with snapshot isolation level.