* Added examples with own go.mod

CHANGELOG.md

@@ -7,6 +7,7 @@
 * Added `trace.Driver.OnConnDial` event callback
 * Fixed bug with no checking operation error on `discovery.Client` calls
 * Allowed zero create session timeout in `ydb.WithSessionPoolCreateSessionTimeout(timeout)` (less than or equal to zero - no used timeout on create session request)
+* Added examples with own `go.mod`
 
 ## v3.42.10
 * Added exit from retryer if got grpc-error `Unauthenticated` on `discovery/ListEndpoints` call  

codecov.yml

@@ -6,3 +6,4 @@
 ignore:
   - trace
   - testutil
+  - examples

examples/Makefile

@@ -0,0 +1,46 @@
+all: basic bulk_upsert containers ddl decimal serverless/healthcheck pagination partitioning_policies read_table ttl ttl_readtable serverless/url_shortener
+
+lint:
+	golangci-lint run ./basic ./bulk_upsert ./containers ./ddl ./decimal ./healthcheck ./pagination ./partitioning_policies ./read_table ./ttl ./ttl_readtable ./url_shortener
+
+basic:
+	go run ./basic/native -ydb=${YDB_CONNECTION_STRING} -prefix=basic
+
+database_sql:
+	go run ./basic/database_sql -ydb=${YDB_CONNECTION_STRING} -prefix=database/sql
+
+bulk_upsert:
+	go run ./bulk_upsert -ydb=${YDB_CONNECTION_STRING} -prefix=bulk_upsert -table=bulk_upsert
+
+containers:
+	go run ./containers -ydb=${YDB_CONNECTION_STRING} -prefix=containers
+
+ddl:
+	go run ./ddl -ydb=${YDB_CONNECTION_STRING} -prefix=ddl
+
+decimal:
+	go run ./decimal -ydb=${YDB_CONNECTION_STRING} -prefix=decimal
+
+pagination:
+	go run ./pagination -ydb=${YDB_CONNECTION_STRING} -prefix=pagination
+
+partitioning_policies:
+	go run ./partitioning_policies -ydb=${YDB_CONNECTION_STRING} -prefix=partitioning_policies -table=partitioning_policies
+
+read_table:
+	go run ./read_table -ydb=${YDB_CONNECTION_STRING} -prefix=read_table
+
+ttl:
+	go run ./ttl -ydb=${YDB_CONNECTION_STRING} -prefix=ttl
+
+ttl_readtable:
+	go run ./ttl_readtable -ydb=${YDB_CONNECTION_STRING} -prefix=ttl_readtable
+
+healthcheck:
+	go run ./serverless/healthcheck -ydb=${YDB_CONNECTION_STRING} -prefix=healthcheck -url=ya.ru -url=google.com
+
+url_shortener:
+	go run ./serverless/url_shortener -ydb=${YDB_CONNECTION_STRING} -prefix=url_shortener
+
+describe:
+	go run ./describe -ydb=${YDB_CONNECTION_STRING} -prefix=/ -t="Optional<Interval>" -t="Interval"

examples/README.md

@@ -0,0 +1,34 @@
+# ydb-go-examples
+
+> examples for work with YDB 
+
+## Navigation of examples
+
+| Example                            | Description                                                     | Run command                                                                                                          |
+|------------------------------------|-----------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
+| `auth/access_token_credentials`    | authenticate with access token credentials                      | see [README.md](https://github.com/ydb-platform/ydb-go-examples/tree/master/auth/access_token_credentials#readme)    |
+| `auth/anonymous_credentials`       | authenticate with anonymous credentials                         | see [README.md](https://github.com/ydb-platform/ydb-go-examples/tree/master/auth/anonymous_credentials#readme)       |
+| `auth/metadata_credentials`        | authenticate with metadata credentials                          | see [README.md](https://github.com/ydb-platform/ydb-go-examples/tree/master/auth/metadata_credentials#readme)        |
+| `auth/service_account_credentials` | authenticate with service account credentials                   | see [README.md](https://github.com/ydb-platform/ydb-go-examples/tree/master/auth/service_account_credentials#readme) |
+| `auth/environ`                     | authenticate using environment variables                        | see [README.md](https://github.com/ydb-platform/ydb-go-examples/tree/master/auth/environ#readme)                     |
+| `basic/native`                     | store and read the series with native driver                    | `make basic`                                                                                                         |
+| `basic/database_sql`               | store and read the series with database/sql driver              | `make database_sql`                                                                                                  |
+| `serverless/healthcheck`           | healthcheck site by URL (yandex function and local http-server) | `make healthcheck`                                                                                                   |
+| `serverless/url_shortener`         | URL shortener example (yandex function and local http-server)   | `make url_shortener`                                                                                                 |
+| `bulk_upsert`                      | bulk upserting data                                             | `make bulk_upsert`                                                                                                   |
+| `containers`                       | containers example                                              | `make containers`                                                                                                    |
+| `ddl`                              | DDL requests example                                            | `make ddl`                                                                                                           |
+| `decimal`                          | decimal store and read                                          | `make decimal`                                                                                                       |
+| `pagination`                       | pagination example                                              | `make pagination`                                                                                                    |
+| `partitioning_policies`            | partitioning_policies example                                   | `make partitioning_policies`                                                                                         |
+| `read_table`                       | read table example                                              | `make read_table`                                                                                                    |
+| `topic/cdc-cache-bus-freeseats`    | example of use cdc for cache updates in web application         | `go run topic/cdc-example-cache-freeseats/*.go`                                                                      |
+| `topic/cdc-fill-and-read`          | change table records and read cdc stream                        | `go run topic/cdc/*.go`                                                                                              |
+| `ttl`                              | TTL using example                                               | `make ttl`                                                                                                           |
+| `ttl_readtable`                    | TTL using example                                               | `make ttl_readtable`                                                                                                 |
+
+Run command needs prepared environ like this:
+```bash
+export YDB_SERVICE_ACCOUNT_KEY_FILE_CREDENTIALS=~/.ydb/SA.json
+export YDB_CONNECTION_STRING="grpcs://ydb.serverless.yandexcloud.net:2135/?database=/ru-central1/b1g8skpblkos03malf3s/etn02qhd0tfkrq4riqgd"
+```

examples/auth/README.md

@@ -0,0 +1,11 @@
+# auth examples
+
+Auth examples helps to understand YDB authentication:
+* `access_token_credentials` - example of use access token credentials
+* `anonymous_credentials` - example of use anonymous credentials
+* `metadata_credentials` - example of use metadata credentials
+* `service_account_credentials` - example of use service account key file credentials
+* `static_credentials` - example of use static credentials
+* `environ` - example of use environment variables to configure YDB authenticate
+
+By default, connect to YDB used environment variables unless otherwise specified

examples/auth/access_token_credentials/README.md

@@ -0,0 +1,9 @@
+# Authenticate with access token credentials
+
+`access_token_credentials` example provide code snippet for authenticate to YDB with access token credentials
+
+## Runing code snippet
+```bash
+access_token_credentials -ydb="grpcs://endpoint/?database=database" -token="mytoken"
+```
+

examples/auth/access_token_credentials/main.go

@@ -0,0 +1,69 @@
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"os"
+
+	ydb "github.com/ydb-platform/ydb-go-sdk/v3"
+)
+
+var (
+	dsn   string
+	token string
+)
+
+func init() {
+	required := []string{"ydb", "token"}
+	flagSet := flag.NewFlagSet(os.Args[0], flag.ExitOnError)
+	flagSet.Usage = func() {
+		out := flagSet.Output()
+		_, _ = fmt.Fprintf(out, "Usage:\n%s [options]\n", os.Args[0])
+		_, _ = fmt.Fprintf(out, "\nOptions:\n")
+		flagSet.PrintDefaults()
+	}
+	flagSet.StringVar(&dsn,
+		"ydb", "",
+		"YDB connection string",
+	)
+	flagSet.StringVar(&token,
+		"token", "",
+		"access token",
+	)
+	if err := flagSet.Parse(os.Args[1:]); err != nil {
+		flagSet.Usage()
+		os.Exit(1)
+	}
+	flagSet.Visit(func(f *flag.Flag) {
+		for i, arg := range required {
+			if arg == f.Name {
+				required = append(required[:i], required[i+1:]...)
+			}
+		}
+	})
+	if len(required) > 0 {
+		fmt.Printf("\nSome required options not defined: %v\n\n", required)
+		flagSet.Usage()
+		os.Exit(1)
+	}
+}
+
+func main() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	db, err := ydb.Open(ctx, dsn,
+		ydb.WithAccessTokenCredentials(token),
+	)
+	if err != nil {
+		panic(err)
+	}
+	defer func() { _ = db.Close(ctx) }()
+
+	whoAmI, err := db.Discovery().WhoAmI(ctx)
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println(whoAmI.String())
+}

examples/auth/anonymous_credentials/README.md

@@ -0,0 +1,10 @@
+# Authenticate with anonymous credentials
+
+`anonymous_credentials` example provide code snippet for authenticate to YDB with anonymous credentials
+
+## Runing code snippet
+```bash
+anonymous_credentials -ydb="grpcs://endpoint/?database=database"
+```
+
+

examples/auth/anonymous_credentials/main.go

@@ -0,0 +1,64 @@
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"os"
+
+	ydb "github.com/ydb-platform/ydb-go-sdk/v3"
+)
+
+var (
+	dsn string
+)
+
+func init() {
+	required := []string{"ydb"}
+	flagSet := flag.NewFlagSet(os.Args[0], flag.ExitOnError)
+	flagSet.Usage = func() {
+		out := flagSet.Output()
+		_, _ = fmt.Fprintf(out, "Usage:\n%s [options]\n", os.Args[0])
+		_, _ = fmt.Fprintf(out, "\nOptions:\n")
+		flagSet.PrintDefaults()
+	}
+	flagSet.StringVar(&dsn,
+		"ydb", "",
+		"YDB connection string",
+	)
+	if err := flagSet.Parse(os.Args[1:]); err != nil {
+		flagSet.Usage()
+		os.Exit(1)
+	}
+	flagSet.Visit(func(f *flag.Flag) {
+		for i, arg := range required {
+			if arg == f.Name {
+				required = append(required[:i], required[i+1:]...)
+			}
+		}
+	})
+	if len(required) > 0 {
+		fmt.Printf("\nSome required options not defined: %v\n\n", required)
+		flagSet.Usage()
+		os.Exit(1)
+	}
+}
+
+func main() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	db, err := ydb.Open(ctx, dsn,
+		ydb.WithAnonymousCredentials(),
+	)
+	if err != nil {
+		panic(err)
+	}
+	defer func() { _ = db.Close(ctx) }()
+
+	whoAmI, err := db.Discovery().WhoAmI(ctx)
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println(whoAmI.String())
+}

examples/auth/environ/README.md

@@ -0,0 +1,29 @@
+# Authenticate with environ
+
+`environ` example provide code snippet for authenticate to YDB with environ variables
+
+Authenticate produced with one of next environment variables:
+
+* `YDB_SERVICE_ACCOUNT_KEY_FILE_CREDENTIALS=<path/to/sa_key_file>` — used service account key file by path
+* `YDB_ANONYMOUS_CREDENTIALS="1"` — used for authenticate with anonymous access. Anonymous access needs for connect to testing YDB installation
+* `YDB_METADATA_CREDENTIALS="1"` — used metadata service for authenticate to YDB from yandex cloud virtual machine or from yandex function
+* `YDB_ACCESS_TOKEN_CREDENTIALS=<access_token>` — used for authenticate to YDB with short-life access token. For example, access token may be IAM token
+
+## Runing code snippet
+```bash
+export YDB_CONNECTION_STRING="grpcs://endpoint/?database=database"
+export YDB_SERVICE_ACCOUNT_KEY_FILE_CREDENTIALS=/Users/user/.ydb/sa.jsoon 
+environ
+# or
+export YDB_CONNECTION_STRING="grpcs://endpoint/?database=database"
+export YDB_ANONYMOUS_CREDENTIALS="1" 
+environ
+# or
+export YDB_CONNECTION_STRING="grpcs://endpoint/?database=database"
+export YDB_METADATA_CREDENTIALS="1" 
+environ
+# or
+export YDB_CONNECTION_STRING="grpcs://endpoint/?database=database"
+export YDB_ACCESS_TOKEN_CREDENTIALS="YDB_ACCESS_TOKEN"
+environ
+```

examples/auth/environ/main.go

@@ -0,0 +1,30 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	environ "github.com/ydb-platform/ydb-go-sdk-auth-environ"
+	ydb "github.com/ydb-platform/ydb-go-sdk/v3"
+)
+
+func main() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	db, err := ydb.Open(ctx,
+		os.Getenv("YDB_CONNECTION_STRING"),
+		environ.WithEnvironCredentials(ctx),
+	)
+	if err != nil {
+		panic(err)
+	}
+	defer func() { _ = db.Close(ctx) }()
+
+	whoAmI, err := db.Discovery().WhoAmI(ctx)
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println(whoAmI.String())
+}

examples/auth/metadata_credentials/README.md

@@ -0,0 +1,8 @@
+# Authenticate with metadata credentials
+
+`metadata_credentials` example provide code snippet for authenticate to YDB with metadata credentials
+
+## Runing code snippet
+```bash
+metadata_credentials -ydb="grpcs://endpoint/?database=database"
+```

examples/auth/metadata_credentials/main.go

@@ -0,0 +1,66 @@
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"os"
+
+	ydb "github.com/ydb-platform/ydb-go-sdk/v3"
+	yc "github.com/ydb-platform/ydb-go-yc"
+)
+
+var (
+	dsn string
+)
+
+func init() {
+	required := []string{"ydb"}
+	flagSet := flag.NewFlagSet(os.Args[0], flag.ExitOnError)
+	flagSet.Usage = func() {
+		out := flagSet.Output()
+		_, _ = fmt.Fprintf(out, "Usage:\n%s [options]\n", os.Args[0])
+		_, _ = fmt.Fprintf(out, "\nOptions:\n")
+		flagSet.PrintDefaults()
+	}
+	flagSet.StringVar(&dsn,
+		"ydb", "",
+		"YDB connection string",
+	)
+	if err := flagSet.Parse(os.Args[1:]); err != nil {
+		flagSet.Usage()
+		os.Exit(1)
+	}
+	flagSet.Visit(func(f *flag.Flag) {
+		for i, arg := range required {
+			if arg == f.Name {
+				required = append(required[:i], required[i+1:]...)
+			}
+		}
+	})
+	if len(required) > 0 {
+		fmt.Printf("\nSome required options not defined: %v\n\n", required)
+		flagSet.Usage()
+		os.Exit(1)
+	}
+}
+
+func main() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	db, err := ydb.Open(ctx, dsn,
+		yc.WithMetadataCredentials(),
+		yc.WithInternalCA(), // append Yandex Cloud certificates
+	)
+	if err != nil {
+		panic(err)
+	}
+	defer func() { _ = db.Close(ctx) }()
+
+	whoAmI, err := db.Discovery().WhoAmI(ctx)
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println(whoAmI.String())
+}