SQL_MIGRATION_v2_v3.md

Author: asmyasnikov

SQL_MIGRATION_v2_v3.md

@@ -4,6 +4,39 @@
 
 > Note: the article is being updated.
 
+## `sql.Connector` initialization
+
+Package `database/sql` provides two ways for making driver:
+- from connection string (see [sql.Open(driverName, connectionString)](https://pkg.go.dev/database/sql#Open))
+- from custom connector (see [sql.OpnDB(connector)](https://pkg.go.dev/database/sql#OpenDB))
+
+Second way (making driver from connector) are different in `v2` and `v3`:
+- in `v2`:
+  `ydbsql.Connector` returns single result (`sql.driver.Connector`) and init driver lazy on first request. This design causes rare errors. 
+  ```go
+  db := sql.OpenDB(ydbsql.Connector(
+    ydbsql.WithDialer(dialer),
+    ydbsql.WithEndpoint(params.endpoint),
+    ydbsql.WithClient(&table.Client{
+      Driver: driver,
+    }),
+  ))
+  defer db.Close()
+  ```
+- in `v3`:
+  `ydb.Connector` creates `sql.driver.Connector` from native `YDB` driver, returns two results (`sql.driver..Connector` and error) and exclude some lazy driver initialization.
+  ```go
+  nativeDriver, err := ydb.Open(context.TODO(), "grpcs://localhost:2135/local")
+  if err != nil {
+    // fallback on error
+  }
+  connector, err := ydb.Connector(nativeDriver)
+  if err != nil {
+    // fallback on error
+  }
+  db := sql.OpenDB(connector)
+  ```
+
 ## Read-only isolation levels
 
 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.