Skip to content

Commit 868ab42

Browse files
asmyasnikovasmyasnikov
authored
Merge pull request #194 from ydb-platform/readmi
Refactored README.md and godoc documentation
2 parents 6623d86 + ddf3cd8 commit 868ab42

File tree

7 files changed

+124
-39
lines changed

7 files changed

+124
-39
lines changed

‎CREDENTIALS.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
## Credentials <a name="Credentials"></a>
2+
3+
Driver contains two options for making simple `credentials.Credentials`:
4+
- `ydb.WithAnonymousCredentials()`
5+
- `ydb.WithAccessTokenCredentials("token")`
6+
7+
Another variants to get `credentials.Credentials` object provides with external packages:
8+
9+
Package | Type | Description | Link of example usage
10+
--- | --- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ---
11+
[ydb-go-yc](https://github.com/ydb-platform/ydb-go-yc) | credentials | credentials provider for Yandex.Cloud | [yc.WithServiceAccountKeyFileCredentials](https://github.com/ydb-platform/ydb-go-yc/blob/master/internal/cmd/connect/main.go#L22) [yc.WithInternalCA](https://github.com/ydb-platform/ydb-go-yc/blob/master/internal/cmd/connect/main.go#L22) [yc.WithMetadataCredentials](https://github.com/ydb-platform/ydb-go-yc/blob/master/internal/cmd/connect/main.go#L24)
12+
[ydb-go-yc-metadata](https://github.com/ydb-platform/ydb-go-yc-metadata) | credentials | metadata credentials provider for Yandex.Cloud | [yc.WithInternalCA](https://github.com/ydb-platform/ydb-go-yc-metadata/blob/master/options.go#L23) [yc.WithCredentials](https://github.com/ydb-platform/ydb-go-yc-metadata/blob/master/options.go#L17)
13+
[ydb-go-sdk-auth-environ](https://github.com/ydb-platform/ydb-go-sdk-auth-environ) | credentials | create credentials from environ | [ydbEnviron. WithEnvironCredentials](https://github.com/ydb-platform/ydb-go-sdk-auth-environ/blob/master/env.go#L11)

‎DEBUG.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
## Ecosystem of debug tools over `ydb-go-sdk` <a name="Debug"></a>
2+
3+
Package `ydb-go-sdk` provide debugging over trace events in package `trace`.
4+
Now supports driver events in `trace.Driver` struct and table-service events in `trace.Table` struct.
5+
Next packages provide debug tooling:
6+
7+
Package | Type | Description | Link of example usage
8+
--- | --- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ---
9+
[ydb-go-sdk-zap](https://github.com/ydb-platform/ydb-go-sdk-zap) | logging | logging ydb-go-sdk events with zap package | [ydbZap.WithTraces](https://github.com/ydb-platform/ydb-go-sdk-zap/blob/master/internal/cmd/bench/main.go#L64)
10+
[ydb-go-sdk-zerolog](https://github.com/ydb-platform/ydb-go-sdk-zap) | logging | logging ydb-go-sdk events with zerolog package | [ydbZerolog.WithTraces](https://github.com/ydb-platform/ydb-go-sdk-zerolog/blob/master/internal/cmd/bench/main.go#L47)
11+
[ydb-go-sdk-metrics](https://github.com/ydb-platform/ydb-go-sdk-metrics) | metrics | common metrics of ydb-go-sdk. Package declare interfaces such as `Registry`, `GaugeVec` and `Gauge` and use it for create `trace.Driver` and `trace.Table` traces |
12+
[ydb-go-sdk-prometheus](https://github.com/ydb-platform/ydb-go-sdk-prometheus) | metrics | prometheus wrapper over [ydb-go-sdk-metrics](https://github.com/ydb-platform/ydb-go-sdk-metrics) | [ydbPrometheus.WithTraces](https://github.com/ydb-platform/ydb-go-sdk-prometheus/blob/master/internal/cmd/bench/main.go#L56)
13+
[ydb-go-sdk-opentracing](https://github.com/ydb-platform/ydb-go-sdk-opentracing) | tracing | opentracing plugin for trace internal ydb-go-sdk calls | [ydbOpentracing.WithTraces](https://github.com/ydb-platform/ydb-go-sdk-opentracing/blob/master/internal/cmd/bench/main.go#L86)

‎ENVIRON.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
## Environment variables <a name="Environ"></a>
2+
3+
Name | Type | Default | Description
4+
--- | --- | --- | ---
5+
`YDB_SSL_ROOT_CERTIFICATES_FILE` | `string` | | path to certificates file
6+
`YDB_LOG_SEVERITY_LEVEL` | `string` | `quiet` | severity logging level. Supported: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `quiet`
7+
`YDB_LOG_NO_COLOR` | `bool` | `false` | set any non empty value to disable colouring logs
8+
`GRPC_GO_LOG_VERBOSITY_LEVEL` | `integer` | | set to `99` to see grpc logs
9+
`GRPC_GO_LOG_SEVERITY_LEVEL` | `string` | | set to `info` to see grpc logs
10+

‎NEXT_MAJOR_RELEASE.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
# Breaking changes for the next major release
2-
- [ ] Added required param DSN to ydb.New call (instead optional params ydb.WithConnectionString, ydb.WithEndpoint, ydb.WithDatabase, ydb.WithInsecure)
2+
- [ ] Make connection string as required param to ydb.New call (instead optional params ydb.WithConnectionString, ydb.WithEndpoint, ydb.WithDatabase, ydb.WithInsecure)
3+
- [ ] Change signature of `closer.Closer.Close(ctx) error` to `closer.Closer.Close()`

‎README.md‎

Lines changed: 4 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -66,44 +66,10 @@ if err != nil {
6666
log.Fatal(err)
6767
}
6868
```
69-
More examples are listed in [examples](https://github.com/ydb-platform/ydb-go-examples) repository.
69+
More examples of usage placed in [examples](https://github.com/ydb-platform/ydb-go-examples) repository.
7070

71-
## Credentials <a name="Credentials"></a>
71+
See also [CREDENTIALS.md](CREDENTIALS.md) about supported YDB credentials.
7272

73-
Driver contains two options for making simple `credentials.Credentials`:
74-
- `ydb.WithAnonymousCredentials()`
75-
- `ydb.WithAccessTokenCredentials("token")`
73+
See [DEBUG.md](DEBUG.md) about supported debug tooling over `ydb-go-sdk`.
7674

77-
Another variants to get `credentials.Credentials` object provides with external packages:
78-
79-
Package | Type | Description | Link of example usage
80-
--- | --- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ---
81-
[ydb-go-yc](https://github.com/ydb-platform/ydb-go-yc) | credentials | credentials provider for Yandex.Cloud | [yc.WithServiceAccountKeyFileCredentials](https://github.com/ydb-platform/ydb-go-yc/blob/master/internal/cmd/connect/main.go#L22) [yc.WithInternalCA](https://github.com/ydb-platform/ydb-go-yc/blob/master/internal/cmd/connect/main.go#L22) [yc.WithMetadataCredentials](https://github.com/ydb-platform/ydb-go-yc/blob/master/internal/cmd/connect/main.go#L24)
82-
[ydb-go-yc-metadata](https://github.com/ydb-platform/ydb-go-yc-metadata) | credentials | metadata credentials provider for Yandex.Cloud | [yc.WithInternalCA](https://github.com/ydb-platform/ydb-go-yc-metadata/blob/master/options.go#L23) [yc.WithCredentials](https://github.com/ydb-platform/ydb-go-yc-metadata/blob/master/options.go#L17)
83-
[ydb-go-sdk-auth-environ](https://github.com/ydb-platform/ydb-go-sdk-auth-environ) | credentials | create credentials from environ | [ydbEnviron. WithEnvironCredentials](https://github.com/ydb-platform/ydb-go-sdk-auth-environ/blob/master/env.go#L11)
84-
85-
Usage examples can be found [here](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth).
86-
87-
## Environment variables <a name="Environ"></a>
88-
89-
Name | Type | Default | Description
90-
--- | --- | --- | ---
91-
`YDB_SSL_ROOT_CERTIFICATES_FILE` | `string` | | path to certificates file
92-
`YDB_LOG_SEVERITY_LEVEL` | `string` | `quiet` | severity logging level. Supported: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `quiet`
93-
`YDB_LOG_NO_COLOR` | `bool` | `false` | set any non empty value to disable colouring logs
94-
`GRPC_GO_LOG_VERBOSITY_LEVEL` | `integer` | | set to `99` to see grpc logs
95-
`GRPC_GO_LOG_SEVERITY_LEVEL` | `string` | | set to `info` to see grpc logs
96-
97-
## Ecosystem of debug tools over `ydb-go-sdk` <a name="Debug"></a>
98-
99-
Package `ydb-go-sdk` provide debugging over trace events in package `trace`.
100-
Now supports driver events in `trace.Driver` struct and table-service events in `trace.Table` struct.
101-
Next packages provide debug tooling:
102-
103-
Package | Type | Description | Link of example usage
104-
--- | --- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ---
105-
[ydb-go-sdk-zap](https://github.com/ydb-platform/ydb-go-sdk-zap) | logging | logging ydb-go-sdk events with zap package | [ydbZap.WithTraces](https://github.com/ydb-platform/ydb-go-sdk-zap/blob/master/internal/cmd/bench/main.go#L64)
106-
[ydb-go-sdk-zerolog](https://github.com/ydb-platform/ydb-go-sdk-zap) | logging | logging ydb-go-sdk events with zerolog package | [ydbZerolog.WithTraces](https://github.com/ydb-platform/ydb-go-sdk-zerolog/blob/master/internal/cmd/bench/main.go#L47)
107-
[ydb-go-sdk-metrics](https://github.com/ydb-platform/ydb-go-sdk-metrics) | metrics | common metrics of ydb-go-sdk. Package declare interfaces such as `Registry`, `GaugeVec` and `Gauge` and use it for create `trace.Driver` and `trace.Table` traces |
108-
[ydb-go-sdk-prometheus](https://github.com/ydb-platform/ydb-go-sdk-prometheus) | metrics | prometheus wrapper over [ydb-go-sdk-metrics](https://github.com/ydb-platform/ydb-go-sdk-metrics) | [ydbPrometheus.WithTraces](https://github.com/ydb-platform/ydb-go-sdk-prometheus/blob/master/internal/cmd/bench/main.go#L56)
109-
[ydb-go-sdk-opentracing](https://github.com/ydb-platform/ydb-go-sdk-opentracing) | tracing | opentracing plugin for trace internal ydb-go-sdk calls | [ydbOpentracing.WithTraces](https://github.com/ydb-platform/ydb-go-sdk-opentracing/blob/master/internal/cmd/bench/main.go#L86)
75+
See [ENVIRON.md](ENVIRON.md) about supported environment variables of `ydb-go-sdk`.

‎example_table_test.go‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
package ydb_test
2+
3+
import (
4+
"context"
5+
"log"
6+
7+
"github.com/ydb-platform/ydb-go-sdk/v3"
8+
"github.com/ydb-platform/ydb-go-sdk/v3/table"
9+
"github.com/ydb-platform/ydb-go-sdk/v3/table/result/named"
10+
"github.com/ydb-platform/ydb-go-sdk/v3/table/types"
11+
)
12+
13+
// nolint: govet
14+
func Example_TableUsage() {
15+
ctx := context.Background()
16+
db, err := ydb.New(ctx,
17+
ydb.WithConnectionString("grpcs://localhost:2135/?database=/local"),
18+
ydb.WithAnonymousCredentials(),
19+
)
20+
if err != nil {
21+
log.Fatal(err)
22+
}
23+
defer func() {
24+
_ = db.Close(ctx)
25+
}()
26+
var (
27+
txControl = table.TxControl(
28+
table.BeginTx(table.WithSerializableReadWrite()), table.CommitTx(),
29+
) // for managing transaction control during Execute
30+
query = `
31+
DECLARE $myStr AS Utf8;
32+
SELECT 42 as id, $myStr as myStr;
33+
`
34+
queryParams = table.NewQueryParameters(
35+
table.ValueParam("$myStr", types.UTF8Value("test")),
36+
) // ydb typed params for query
37+
id int32 // required value
38+
myStr *string // optional value
39+
)
40+
err = db.Table().Do( // Do retry operation on errors with best effort
41+
ctx, // context manage exiting from Do
42+
func(ctx context.Context, s table.Session) (err error) { // retry operation
43+
_, res, err := s.Execute(ctx, txControl, query, queryParams)
44+
if err != nil {
45+
return err // for driver retry
46+
}
47+
defer func() {
48+
_ = res.Close() // must close always
49+
}()
50+
if err = res.NextResultSetErr(ctx); err != nil { // check single result set and switch to it
51+
return err // for driver retry
52+
}
53+
for res.NextRow() { // iterate over rows
54+
err = res.ScanNamed(
55+
named.Required("id", &id),
56+
named.Optional("myStr", &myStr),
57+
)
58+
if err != nil {
59+
return err
60+
}
61+
log.Printf("id=%v, myStr=%v\n", id, *myStr)
62+
}
63+
return res.Err() // for driver retry if not nil
64+
},
65+
)
66+
if err != nil {
67+
log.Printf("unexpected error: %v", err)
68+
}
69+
}

‎ydb.go‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
package ydb
2+
3+
// Package `ydb-go-sdk` is a native Go's driver for communicate with `YDB` database.
4+
//
5+
// Supports `table`, `discovery`, `coordination`, `ratelimiter`, `scheme` and `scripting` clients for `YDB`.
6+
//
7+
// See [CREDENTIALS.md](CREDENTIALS.md) about supported YDB credentials.
8+
//
9+
// See [DEBUG.md](DEBUG.md) about supported debug tooling over `ydb-go-sdk`.
10+
//
11+
// See [ENVIRON.md](ENVIRON.md) about supported environment variables of `ydb-go-sdk`.
12+
//
13+
// Examples of usage placed in [examples](https: //github.com/ydb-platform/ydb-go-examples) repository.

0 commit comments

Comments
 (0)