Skip to content

Commit 7a2ad8c

Browse files
zinalzinal
committed
updated the textual part of documentation for database/sql APIs
1 parent 5a7b6a1 commit 7a2ad8c

File tree

1 file changed

+68
-47
lines changed

1 file changed

+68
-47
lines changed

‎SQL.md‎

Lines changed: 68 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,24 @@
11
# `database/sql` driver for `YDB`
22

3-
Package `ydb-go-sdk` provides usage `database/sql` API also.
4-
`database/sql` driver implementation use `ydb-go-sdk` native driver API's.
3+
In addition to native YDB Go driver APIs, package `ydb-go-sdk` provides standard APIs for `database/sql`.
4+
It allows to use "regular" Go facilities to access YDB databases.
5+
Behind the scene, `database/sql` APIs are implemented using the native interfaces.
6+
57

68
## Table of contents
79
1. [Initialization of `database/sql` driver](#init)
810
* [Configure driver with `ydb.Connector` (recommended way)](#init-connector)
9-
* [Configure driver only with data source name (connection string)](#init-dsn)
10-
2. [Execute queries](#queries)
11-
* [On database object](#queries-db)
12-
* [With transaction](#queries-tx)
11+
* [Configure driver with data source name or connection string](#init-dsn)
12+
2. [Query execution](#queries)
13+
* [Queries on database object](#queries-db)
14+
* [Queries on transaction object](#queries-tx)
1315
3. [Query modes (DDL, DML, DQL, etc.)](#query-modes)
14-
4. [Retry helpers for `YDB` `database/sql` driver](#retry)
15-
* [Over `sql.Conn` object](#retry-conn)
16-
* [Over `sql.Tx`](#retry-tx)
17-
5. [Query args types](#arg-types)
18-
6. [Get native driver from `*sql.DB`](#unwrap)
16+
4. [Changing the transaction control mode](#tx-control)
17+
5. [Retry helpers for `YDB` `database/sql` driver](#retry)
18+
* [Retries over `sql.Conn` object](#retry-conn)
19+
* [Retries over `sql.Tx`](#retry-tx)
20+
6. [Specifying query parameters](#arg-types)
21+
7. [Accessing the native driver from `*sql.DB`](#unwrap)
1922

2023
## Initialization of `database/sql` driver <a name="init"></a>
2124

@@ -42,7 +45,8 @@ func main() {
4245
db := sql.OpenDB(connector)
4346
}
4447
```
45-
### Configure driver only with data source name (connection string) <a name="init-dsn"></a>
48+
49+
### Configure driver with data source name or connection string <a name="init-dsn"></a>
4650
```go
4751
import (
4852
_ "github.com/ydb-platform/ydb-go-sdk/v3"
@@ -57,12 +61,12 @@ Data source name parameters:
5761
* static credentials with authority part of URI, like `grpcs://root:password@localhost:2135/local`
5862
* `query_mode=scripting` - you can redefine default [DML](https://en.wikipedia.org/wiki/Data_manipulation_language) query mode
5963

60-
## Execute queries <a name="queries"></a>
64+
## Query execution <a name="queries"></a>
6165

62-
### On database object <a name="queries-db"></a>
66+
### Queries on database object <a name="queries-db"></a>
6367
```go
6468
rows, err := db.QueryContext(ctx,
65-
"SELECT series_id, title, release_date FROM /full/path/of/table/series;"
69+
"SELECT series_id, title, release_date FROM `/full/path/of/table/series`;"
6670
)
6771
if err != nil {
6872
log.Fatal(err)
@@ -85,19 +89,23 @@ if err = rows.Err(); err != nil { // always check final rows err
8589
}
8690
```
8791

88-
### With transaction <a name="queries-tx"></a>
89-
Supports only `default` transaction options which mapped to `YDB` `SerializableReadWrite` transaction settings.
92+
### Queries on transaction object <a name="queries-tx"></a>
93+
Query execution on transaction object supports only `default` transaction options
94+
which are mapped to `YDB` `SerializableReadWrite` transaction settings.
95+
96+
`YDB`'s `OnlineReadOnly` and `StaleReadOnly` transaction settings are not compatible
97+
with interactive transactions such as `database/sql`'s `*sql.Tx`.
98+
That's why `ydb-go-sdk` implements read-only `sql.LevelSnapshot` with fake transaction
99+
(temporary, until `YDB` starts to support true snapshot isolation mode).
90100

91-
`YDB`'s `OnlineReadOnly` and `StaleReadOnly` transaction settings are not compatible with interactive transactions such as `database/sql`'s `*sql.Tx`.
92-
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)
93101
```go
94102
tx, err := db.BeginTx(ctx, sql.TxOptions{})
95103
if err != nil {
96104
log.Fatal(err)
97105
}
98106
defer tx.Rollback()
99107
rows, err := tx.QueryContext(ctx,
100-
"SELECT series_id, title, release_date FROM /full/path/of/table/series;"
108+
"SELECT series_id, title, release_date FROM `/full/path/of/table/series`;"
101109
)
102110
if err != nil {
103111
log.Fatal(err)
@@ -122,48 +130,56 @@ if err = tx.Commit(); err != nil {
122130
log.Fatal(err)
123131
}
124132
```
133+
125134
## Query modes (DDL, DML, DQL, etc.) <a name="query-modes"></a>
126-
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.
135+
Currently the `YDB` server APIs require the use of a proper GRPC service method depending on the specific request type.
136+
In particular, [DDL](https://en.wikipedia.org/wiki/Data_definition_language) must be called through `table.session.ExecuteSchemeQuery`,
137+
[DML](https://en.wikipedia.org/wiki/Data_manipulation_language) needs `table.session.Execute`, and
138+
[DQL](https://en.wikipedia.org/wiki/Data_query_language) should be passed via `table.session.Execute` or `table.session.StreamExecuteScanQuery`.
139+
`YDB` also has a so-called "scripting" service, which supports different query types within a single method,
140+
but without support for transactions.
127141

128-
That's why needs to select query mode on client side currently.
142+
Unfortunately, this leads to the need to choose the proper query mode on the application side.
129143

130-
`YDB` team have a roadmap goal to implements a single method for executing different query types.
144+
`YDB` team has a roadmap goal to implement a single universal service method for executing
145+
different query types and without the limitations of the "scripting" service method.
131146

132-
`database/sql` driver implementation for `YDB` supports next query modes:
147+
`database/sql` driver implementation for `YDB` supports the following query modes:
133148
* `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.
134-
* `ydb.ExplainQueryMode` - for gettting plan and [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree) of some query
135-
* `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)
149+
* `ydb.ExplainQueryMode` - for gettting plan and [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree) of the query
150+
* `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)
136151
* `ydb.SchemeQueryMode` - for [DDL](https://en.wikipedia.org/wiki/Data_definition_language) queries
137-
* `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
152+
* `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
138153

139-
Example for changing default query mode:
154+
Example for changing the default query mode:
140155
```go
141156
res, err = db.ExecContext(ydb.WithQueryMode(ctx, ydb.SchemeQueryMode),
142157
"DROP TABLE `/full/path/to/table/series`",
143158
)
144159
```
145160

146-
## Specify `YDB` transaction control <a name="tx-control"></a>
161+
## Changing the transaction control mode <a name="tx-control"></a>
147162

148-
Default `YDB`'s transaction control is a `SerializableReadWrite`.
149-
Default transaction control outside interactive transactions may be changed with context:
163+
Default `YDB`'s transaction control mode is a `SerializableReadWrite`.
164+
Default transaction control mode can be changed outside of interactive transactions by updating the context object:
150165
```
151166
ctx := ydb.WithTxControl(ctx, table.OnlineReadOnlyTxControl())
152167
```
153168

154169
## Retry helpers for `YDB` `database/sql` driver <a name="retry"></a>
155170

156171
`YDB` is a distributed `RDBMS` with non-stop 24/7 releases flow.
157-
It means some nodes may be not available for queries.
158-
Also network errors may be occurred.
159-
That's why some queries may be complete with errors.
172+
It means some nodes may be unavailable for queries at some point in time.
173+
Network errors may also occur.
174+
That's why some queries may complete with errors.
160175
Most of those errors are transient.
161-
`ydb-go-sdk`'s "knows" what to do on specific error: retry or not, with or without backoff, with or whithout deleting session, etc.
162-
`ydb-go-sdk` provides retry helpers which can work either with plain database connection object, or with interactive transaction object.
176+
`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.
177+
`ydb-go-sdk` provides retry helpers which can work either with the database connection object, or with the transaction object.
163178

164-
### Over `sql.Conn` object <a name="retry-conn"></a>
179+
### Retries over `sql.Conn` object <a name="retry-conn"></a>
165180

166-
`retry.Do` helper allow custom lambda, which must return error for processing or nil if retry operation is ok.
181+
`retry.Do` helper accepts custom lambda, which must return error if it happens during the processing,
182+
or nil if the operation succeeds.
167183
```
168184
import (
169185
"github.com/ydb-platform/ydb-go-sdk/v3/retry"
@@ -181,11 +197,15 @@ err := retry.Do(context.TODO(), db, func(ctx context.Context, cc *sql.Conn) erro
181197
182198
```
183199

184-
### Over `sql.Tx` <a name="retry-tx"></a>
200+
### Retries over `sql.Tx` <a name="retry-tx"></a>
185201

186-
`retry.DoTx` helper allow custom lambda, which must return error for processing or nil if retry operation is ok.
202+
`retry.DoTx` helper accepts custom lambda, which must return error if it happens during processing,
203+
or nil if the operation succeeds.
204+
205+
`tx` object is a prepared transaction object.
206+
207+
The logic within the custom lambda does not need the explicit commit or rollback at the end - `retry.DoTx` does it automatically.
187208

188-
`tx` object is a prepared transaction object which not requires commit or rollback at the end - `retry.DoTx` do it automatically.
189209
```
190210
import (
191211
"github.com/ydb-platform/ydb-go-sdk/v3/retry"
@@ -207,10 +227,10 @@ err := retry.DoTx(context.TODO(), db, func(ctx context.Context, tx *sql.Tx) erro
207227
}))
208228
```
209229

210-
## Query args types <a name="arg-types"></a>
230+
## Specifying query parameters <a name="arg-types"></a>
211231

212-
`database/sql` driver for `YDB` supports next types of query args:
213-
* multiple `sql.NamedArg` (uniform `database/sql` arg)
232+
`database/sql` driver for `YDB` supports the following types of query parameters:
233+
* multiple `sql.NamedArg` arguments (standard `database/sql` query parameters)
214234
```
215235
rows, err := cc.QueryContext(ctx, `
216236
DECLARE $seasonTitle AS Utf8;
@@ -221,7 +241,7 @@ err := retry.DoTx(context.TODO(), db, func(ctx context.Context, tx *sql.Tx) erro
221241
sql.Named("views", uint64(1000)),
222242
)
223243
```
224-
* multiple native for `ydb-go-sdk` `table.ParameterOption` which constructs from `table.ValueParam("name", value)`
244+
* multiple native `ydb-go-sdk` `table.ParameterOption` arguments which are constructed with `table.ValueParam("name", value)`
225245
```
226246
rows, err := cc.QueryContext(ctx, `
227247
DECLARE $seasonTitle AS Utf8;
@@ -232,7 +252,7 @@ err := retry.DoTx(context.TODO(), db, func(ctx context.Context, tx *sql.Tx) erro
232252
table.ValueParam("views", types.Uint64Value((1000)),
233253
)
234254
```
235-
* single native for `ydb-go-sdk` `*table.QueryParameters` which constructs from `table.NewQueryParameters(parameterOptions...)`
255+
* single native `ydb-go-sdk` `*table.QueryParameters` argument which are constructed with `table.NewQueryParameters(parameterOptions...)`
236256
```
237257
rows, err := cc.QueryContext(ctx, `
238258
DECLARE $seasonTitle AS Utf8;
@@ -245,7 +265,8 @@ err := retry.DoTx(context.TODO(), db, func(ctx context.Context, tx *sql.Tx) erro
245265
),
246266
)
247267
```
248-
## Get native driver from `*sql.DB` <a name="unwrap"></a>
268+
269+
## Accessing the native driver from `*sql.DB` <a name="unwrap"></a>
249270

250271
```
251272
db, err := sql.Open("ydb", "grpcs://localhost:2135/local")

0 commit comments

Comments
 (0)