YDB Go SDK

https://github.com/ydb-platform/ydb-go-sdk
Admin
YDB Go SDK is a pure Go native and database/sql driver for YDB, an open-source Distributed SQL...
Tokens:302,484
Snippets:1,912
Trust Score:7.6
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install YDB Go SDK

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/README.md

Use the go get command to install the latest version of the YDB Go SDK.

```sh
go get -u github.com/ydb-platform/ydb-go-sdk/v3
```

--------------------------------

### Run the Apache Arrow example

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/apache_arrow/README.md

Execute the example from the examples directory. Set YDB_CONNECTION_STRING if it differs from grpc://localhost:2136/local. The command uses anonymous authentication.

```sh
go run ./apache_arrow
```

--------------------------------

### Run metadata_credentials example

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/auth/metadata_credentials/README.md

Command to run the metadata_credentials example, specifying the YDB endpoint and database via the -ydb flag.

```bash
metadata_credentials -ydb="grpcs://endpoint/?database=database"
```

--------------------------------

### Go example with bindings via connector options

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/SQL.md

Go code enabling query bindings using connector options: query.TablePathPrefix, query.Declare, and query.Positional.

```go
import (
  "context"
  "database/sql"

  "github.com/ydb-platform/ydb-go-sdk/v3" 
)

func main() {
  var (
    ctx = context.TODO()
    nativeDriver = ydb.MustOpen(ctx, "grpc://localhost:2136/local")
    db = sql.OpenDB(ydb.MustConnector(nativeDriver,
      query.TablePathPrefix("/local/path/to/my/folder"), // bind pragma TablePathPrefix
      query.Declare(),                                   // bind parameters declare
      query.Positional(),                                // bind positional args
    ))
  )
  defer nativeDriver.Close(ctx) // cleanup resources
  defer db.Close()

  // positional args
  row := db.QueryRowContext(ctx, `SELECT ?, ?`, 42, "my string")
}
```

--------------------------------

### Run anonymous_credentials example

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/auth/anonymous_credentials/README.md

Execute the anonymous_credentials example by providing the YDB connection string as a flag.

```bash
anonymous_credentials -ydb="grpcs://endpoint/?database=database"
```

--------------------------------

### Run access_token_credentials example

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/auth/access_token_credentials/README.md

Execute the access_token_credentials binary with the required ydb endpoint and token arguments.

```bash
access_token_credentials -ydb="grpcs://endpoint/?database=database" -token="mytoken"
```

--------------------------------

### Start local YDB Docker container for benchmarks

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/tests/integration/arrow/README.md

Starts a disposable local YDB database for benchmarks. The benchmark requires permission to create, load and drop /local/query_arrow_benchmark. Use a disposable local database.

```sh
docker run -d --name ydb-query-with-arrow --hostname localhost \
  --platform linux/amd64 -p 2136:2136 -p 8765:8765 \
  -e YDB_USE_IN_MEMORY_PDISKS=true ydbplatform/local-ydb:26.3.1.17
```

--------------------------------

### Go example with bindings via connection string

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/SQL.md

Go code enabling query bindings using connection string parameter go_auto_bind with table_path_prefix, declare, and positional options.

```go
import (
  "context"
  "database/sql"

  _ "github.com/ydb-platform/ydb-go-sdk/v3" // anonymous import for registering driver
)

func main() {
  var (
    ctx = context.TODO()
    db = sql.Open("ydb", 
      "grpc://localhost:2136/local?"+
        "go_auto_bind="+
          "table_path_prefix(/local/path/to/my/folder),"+
          "declare,"+
          "positional", 
    )
  )
  defer db.Close() // cleanup resources

  // positional args
  row := db.QueryRowContext(ctx, `SELECT ?, ?`, 42, "my string")
}
```

--------------------------------

### Expected output of the Apache Arrow example

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/apache_arrow/README.md

The command prints these lines, showing the results from QueryArrow and WithResultFormatArrow.

```text
QueryArrow: id=24 name="WOW"
QueryArrow: id=42 name="my string"
WithResultFormatArrow: id=24 name="WOW"
WithResultFormatArrow: id=42 name="my string"
```

--------------------------------

### Run service_account_credentials example

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/auth/service_account_credentials/README.md

Executes the service_account_credentials binary with the YDB endpoint and service account key file path. The -ydb flag specifies the connection string, and -sa-file points to the service account JSON file.

```bash
service_account_credentials -ydb="grpcs://endpoint/?database=database" -sa-file="/Users/user/.ydb/sa.json"
```

--------------------------------

### Run the server with YDB_CONNECTION_STRING and go run

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/redis_over_ydb/README.md

Starts the redis_over_ydb server on port 6379, using the provided YDB connection string. Stop with Ctrl+C or SIGTERM.

```bash
export YDB_CONNECTION_STRING='grpc://localhost:2136/local' go run ./redis_over_ydb -addr :6379
```

--------------------------------

### Configure client balancing with ydb.WithBalancer and balancers.PreferLocationsWithFallback

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/SQL.md

Shows how to open a YDB native driver with a custom balancer using ydb.WithBalancer and balancers.PreferLocationsWithFallback, then create a database/sql connection. The default balancer is random choice. The example sets connection pool limits and a connection max idle time as a workaround for background keep-alive of YDB sessions.

```go
import (
    "github.com/ydb-platform/ydb-go-sdk/v3/balancers"
)
func main() {
    nativeDriver, err := ydb.Open(context.TODO(), "grpc://localhost:2136/local",
        ydb.WithBalancer(
            balancers.PreferLocationsWithFallback(
                balancers.RandomChoice(), "a", "b",
            ),
        ),
    )
    if err != nil {
        // fallback on error
    }
    connector, err := ydb.Connector(nativeDriver)
    if err != nil {
        // fallback on error
    }
    db := sql.OpenDB(connector)
    db.SetMaxOpenConns(100)
    db.SetMaxIdleConns(100)
    db.SetConnMaxIdleTime(time.Second) // workaround for background keep-aliving of YDB sessions
}
```

--------------------------------

### Run the lock example with YDB Docker

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/coordination/README.md

Builds the lock application and runs it against a local YDB Docker instance using anonymous credentials. The command specifies the YDB endpoint, path, and semaphore name.

```bash
$ go build 
$ YDB_ANONYMOUS_CREDENTIALS=1 ./lock -ydb grpc://localhost:2136/local --path /local/test --semaphore lock
```

--------------------------------

### Run environ example with environment variables

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/auth/environ/README.md

Bash commands to set the YDB connection string and one of the authentication environment variables, then run the `environ` command. The snippet shows four alternative authentication methods: service account key file, anonymous, metadata, and access token. Each method is shown as a separate command sequence.

```bash
export YDB_CONNECTION_STRING="grpcs://endpoint/?database=database"
export YDB_SERVICE_ACCOUNT_KEY_FILE_CREDENTIALS=/Users/user/.ydb/sa.jsoon 
environ
```

```bash
export YDB_CONNECTION_STRING="grpcs://endpoint/?database=database"
export YDB_ANONYMOUS_CREDENTIALS="1" 
environ
```

```bash
export YDB_CONNECTION_STRING="grpcs://endpoint/?database=database"
export YDB_METADATA_CREDENTIALS="1" 
environ
```

```bash
export YDB_CONNECTION_STRING="grpcs://endpoint/?database=database"
export YDB_ACCESS_TOKEN_CREDENTIALS="YDB_ACCESS_TOKEN"
environ
```

--------------------------------

### Run OpenTelemetry stack with Docker Compose

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/opentelemetry/README.md

Commands to start the local OpenTelemetry stack using Docker Compose.

```bash
# Preferred (Docker Compose v1 / legacy binary)
docker-compose -f compose-e2e.yaml up -d --build

# Alternative (Docker Compose v2 plugin, if available)
# docker compose -f compose-e2e.yaml up -d --build
```

--------------------------------

### Send messages with topic writer

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/topic/README.md

Creates a topic writer with a message group ID and GZIP codec, then writes two messages. The example shows how to configure the writer and handle write errors.

```golang
producerAndGroupID := "group-id"
writer, err := db.Topic().StartWriter(producerAndGroupID, "topicName",
    topicoptions.WithMessageGroupID(producerAndGroupID),
    topicoptions.WithCodec(topictypes.CodecGzip),
)
if err != nil {
    log.Fatal(err)
}

data1 := []byte{1, 2, 3}
data2 := []byte{4, 5, 6}
mess1 := topicwriter.Message{Data: bytes.NewReader(data1)}
mess2 := topicwriter.Message{Data: bytes.NewReader(data2)}

err = writer.Write(ctx, mess1, mess2)
if err != nil {
	log.Fatal(err)
}
```

--------------------------------

### Benchmark with redis-benchmark

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/redis_over_ydb/README.md

Measures performance with 900 concurrent connections, 10000 requests, and 1000 keys for GET and SET commands.

```bash
redis-benchmark -p 6379 -q -c 900 -n 10000 -r 1000 -t get,set
```

--------------------------------

### YQL query with PRAGMA TablePathPrefix

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/SQL.md

Example YQL query using PRAGMA TablePathPrefix to simplify table names.

```sql
PRAGMA TablePathPrefix("/local/path/to/tables/");
DECLARE $title AS Text;
DECLARE $views AS Uint64;
SELECT season_id FROM seasons WHERE title LIKE $title AND views > $views;
```

--------------------------------

### Redis benchmark output (origin Redis v8.6.2)

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/redis_over_ydb/README.md

Shows the throughput and latency for SET and GET on a standalone Redis server.

```text
SET: 62111.80 requests per second, p50=11.951 msec      
GET: 57803.47 requests per second, p50=13.335 msec
```

--------------------------------

### Query transaction object with BeginTx and QueryContext

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/SQL.md

Starts a read-only snapshot transaction, executes a query, iterates over rows, and commits. Includes rollback on defer and error checks.

```go
tx, err := db.BeginTx(ctx, sql.TxOption{
  ReadOnly: true,
  Isolation: sql.LevelSnapshot,
})
if err != nil {
    log.Fatal(err)
}
defer tx.Rollback()
rows, err := tx.QueryContext(ctx,
    "SELECT series_id, title, release_date FROM `/full/path/of/table/series`;"
)
if err != nil {
    log.Fatal(err)
}
defer rows.Close() // always close rows 
var (
    id          *string
    title       *string
    releaseDate *time.Time
)
for rows.Next() { // iterate over rows
    // apply database values to go's type destinations
    if err = rows.Scan(&id, &title, &releaseDate); err != nil {
        log.Fatal(err)
    }
    log.Printf("> [%s] %s (%s)", *id, *title, releaseDate.Format("2006-01-02"))
}
if err = rows.Err(); err != nil { // always check final rows err
    log.Fatal(err)
}
if err = tx.Commit(); err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Run SLO workload with environment variables

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/tests/slo/README.md

Example of running the SLO workload binary with required and optional environment variables set. The workload creates a table, fills it with initial data, runs read/write workers, and then drops the table.

```bash
export YDB_ENDPOINT=grpc://ydb:2136
export YDB_DATABASE=/Root/testdb
export WORKLOAD_DURATION=600
export OTEL_EXPORTER_OTLP_ENDPOINT=http://ydb-prometheus:9090/api/v1/otlp
export PROMETHEUS_URL=http://ydb-prometheus:9090

./slo-native-table
```

--------------------------------

### Go example without bindings using YDB types

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/SQL.md

Go code showing explicit parameter declaration and YDB types without bindings. Requires importing ydb-go-sdk packages.

```go
import (
  "context"
  "database/sql"

  "github.com/ydb-platform/ydb-go-sdk/v3"
  "github.com/ydb-platform/ydb-go-sdk/v3/table"
  "github.com/ydb-platform/ydb-go-sdk/v3/types"
)

func main() {
  db := sql.Open("ydb", "grpc://localhost:2136/local")
  defer db.Close()

  // positional args
  row := db.QueryRowContext(context.TODO(), `
    PRAGMA TablePathPrefix("/local/path/to/my/folder");
    DECLARE $p0 AS Int32;
    DECLARE $p1 AS Utf8;
    SELECT $p0, $p1`, 
    sql.Named("p0", 42), 
    table.ValueParam("$p1", types.TextValue("my string")),
  )
  // process row ...
}
```

--------------------------------

### Run SLO tests with Docker Compose

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/tests/slo/SLO.md

Starts the full SLO test stack with telemetry, chaos injection, extra nodes, and the current workload. Requires Docker Compose v2.21+ and enough resources. The first run clones ydb-slo-action and builds images, which can take 10–15 minutes on a cold cache.

```bash
cd tests/slo

SRC_PATH=native/query WORKLOAD_DURATION=600 docker compose \
  --profile telemetry \
  --profile chaos \
  --profile extra-nodes \
  --profile workload-current \
  up --build
```

--------------------------------

### YQL query with DECLARE and full table path

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/SQL.md

Example YQL query that declares parameters and uses a full table path. This is the baseline without bindings.

```sql
DECLARE $title AS Text;
DECLARE $views AS Uint64;
SELECT season_id
FROM `/local/path/to/tables/seasons`
WHERE title LIKE $title AND views > $views;
```

--------------------------------

### Redis benchmark output (KV API)

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/redis_over_ydb/README.md

Shows the throughput and latency for SET and GET when using the KV API without session pool limitation.

```text
SET: 17825.31 requests per second, p50=44.575 msec                    
GET: 10235.42 requests per second, p50=82.431 msec 
```

--------------------------------

### Redis benchmark output (Query API)

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/redis_over_ydb/README.md

Shows the throughput and latency for SET and GET when using the Query API with default session pool limit of 50.

```text
SET: 5138.75 requests per second, p50=156.543 msec                    
GET: 1434.51 requests per second, p50=548.863 msec
```

--------------------------------

### Worker main loop and semaphore acquisition pseudocode

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/coordination/README.md

This Go pseudocode shows the main loop for managing worker tasks. It opens a Coordination session, acquires semaphores for each task, and starts a new task for each acquired lease until the worker capacity is reached. The code also includes the awaitSemaphore function that acquires an ephemeral semaphore and sends the lease to the main loop if capacity is available, otherwise releases it.

```go
for {
    session, err := db.Coordination().OpenSession(ctx, path)
    if err != nil {
        // The context is canceled.
        break
    }

    semaphoreCtx, semaphoreCancel := context.WithCancel(ctx)
    capacitySemaphore := semaphore.NewWeighted(capacity)
    leaseChan := make(chan *coordination.Lease)
    for _, name := range tasks {
        go awaitSemaphore(semaphoreCtx, semaphoreCancel, session, name, capacitySemaphore, leaseChan)
    }

    tasksStarted := 0
loop:
    for {
        lease := <-leaseChan
			
        // Run a new task every time we acquire a semaphore.
        go doWork(lease.Context())
        
        tasksStarted++
        if tasksStarted == capacity {
            break
        }
    }

    // The capacity is full, cancel all Acquire operations.
    semaphoreCancel()
	
    // Wait until the session is alive.
    <-session.Context().Done()
	
    // The tasks must be stopped since we do not own the semaphores anymore.
    cancelTasks()
}

func awaitSemaphore(
	ctx context.Context,
	cancel context.CancelFunc,
	session coordination.Session, 
	semaphoreName string,
	capacitySemaphore *semaphore.Weighted,
	leaseChan chan *coordination.Lease,
) {
    lease, err := session.AcquireSemaphore(
        ctx,
        semaphoreName,
        coordination.Exclusive,
        options.WithEphemeral(true),
    )
    if err != nil {
        // Let the main loop know that something is wrong.
        // ...
        return
    }

    // If there is a need in tasks for the current worker, provide it with a new lease.
    if capacitySemaphore.TryAcquire(1) {
        leaseChan <- lease
    } else {
        // This may happen since we are waiting for all existing semaphores trying to grab the first available to us.
        err := lease.Release()
        if err != nil {
            // Let the main loop know that something is wrong.
            // ...
        }
    }	
}
```

--------------------------------

### Process Arrow columns directly with Session.QueryArrow

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/apache_arrow/README.md

Uses `Session.QueryArrow` inside `db.Query().Do` to process Arrow columns without SDK rows or scans. The example iterates over result parts, creates an IPC reader per part, and consumes record batches before calling `Next` or `Release`.

```go
err := db.Query().Do(ctx, func(ctx context.Context, s query.Session) error {
    result, err := s.QueryArrow(ctx, sql)
    if err != nil {
        return err
    }
    defer result.Close(ctx)
    for part, err := range result.Parts(ctx) {
        if err != nil {
            return err
        }
        reader, err := ipc.NewReader(part)
        if err != nil {
            return err
        }
        for reader.Next() {
            batch := reader.RecordBatch()
            // Consume batch columns here, before Next or Release.
            fmt.Println(batch.NumRows())
        }
        err = reader.Err()
        reader.Release()
        if err != nil {
            return err
        }
    }
    return nil
})
```

--------------------------------

### Initialize database/sql driver with ydb.Connector

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/SQL.md

Recommended way to configure the driver. Opens a native YDB driver, creates a connector, and opens a *sql.DB. Sets connection pool limits and a workaround for background keep-alive of YDB sessions.

```go
import (
    "database/sql"
  
    "github.com/ydb-platform/ydb-go-sdk/v3"
)

func main() {
    // init native ydb-go-sdk driver
    nativeDriver, err := ydb.Open(context.TODO(), "grpc://localhost:2136/local",
        // See many ydb.Option's for configure driver https://pkg.go.dev/github.com/ydb-platform/ydb-go-sdk/v3#Option
    )
    if err != nil {
        // fallback on error
    }
    defer nativeDriver.Close(context.TODO())
    connector, err := ydb.Connector(nativeDriver,
        // See ydb.ConnectorOption's for configure connector https://pkg.go.dev/github.com/ydb-platform/ydb-go-sdk/v3#ConnectorOption
    )
    if err != nil {
        // fallback on error
    }
    db := sql.OpenDB(connector)
    defer db.Close()
    db.SetMaxOpenConns(100)
    db.SetMaxIdleConns(100)
    db.SetConnMaxIdleTime(time.Second) // workaround for background keep-aliving of YDB sessions
}
```

--------------------------------

### Initialize database/sql driver with data source name

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/SQL.md

Alternative way to configure the driver using sql.Open with the "ydb" driver name and a connection string. Requires importing the driver package with a blank identifier.

```go
import (
    "database/sql"
  
    _ "github.com/ydb-platform/ydb-go-sdk/v3"
)

func main() {
    db, err := sql.Open("ydb", "grpc://localhost:2136/local")
    defer db.Close()
}
```

--------------------------------

### Build and run URL shortener as HTTP server

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/serverless/url_shortener/README.md

Commands to clone the repository, build the binary, and run the server with YDB credentials and endpoint. The server listens on port 80.

```bash
git clone github.com/ydb-platform/ydb-go-sdk/v3 ydb-go-sdk
cd ydb-go-sdk/examples/serverless/url_shortener
go build -o url_shortener .
YDB_SERVICE_ACCOUNT_KEY_FILE_CREDENTIALS=/path/to/sa/key/file \
url_shortener \
   -ydb=grpcs://ydb.serverless.yandexcloud.net:2135/ru-central1/b1g8skpblkos03malf3s/etn01f8gv9an9sedo9fu \
   -port=80
```

--------------------------------

### Create go.mod and zip for serverless function

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/serverless/healthcheck/README.md

Initialize a Go module and create a zip archive containing service.go, go.mod, and go.sum for deployment as a Yandex function.

```bash
go mod init example && go mod tidy
zip archive.zip service.go go.mod go.sum
```

--------------------------------

### Run Arrow query benchmark with go test -bench BenchmarkFormats

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/QUERY.md

Run the Arrow query benchmark from the SDK checkout. Requires the integration test directory, a YDB instance, and the `tests/integration/arrow` module. Set `YDB_CONNECTION_STRING` if it differs from `grpc://localhost:2136/local`. The module uses Arrow Go v18.8.0 and needs Go 1.25 or newer.

```sh
cd tests/integration/arrow
export GOTOOLCHAIN=go1.27.0
for sample in 1 2 3 4 5; do
  for rows in 1 10 100 1000 10000; do
    iterations=1000
    if [ "$rows" -ge 1000 ]; then iterations=100; fi
    go test -tags integration -run '^$' -bench "^BenchmarkFormats$/${rows}$" -benchtime="${iterations}x" -count=1 -cpu=4 -v
  done
done

```

--------------------------------

### Deploy URL shortener as serverless function

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/serverless/url_shortener/README.md

Commands to initialize a Go module, zip the source files, and create a Yandex Cloud function version with the specified runtime and environment variables.

```bash
go mod init example && go mod tidy
zip archive.zip service.go go.mod go.sum
yc sls fn version create \
   --service-account-id=aje46n285h0re8nmm5u6 \
   --runtime=golang116 \
   --entrypoint=main.Serverless \
   --memory=128m \
   --execution-timeout=1s \
   --environment YDB="grpcs://ydb.serverless.yandexcloud.net:2135/ru-central1/b1g8skpblkos03malf3s/etnpa7o3qltdfgu9vsap" \
   --source-path=./archive.zip \
   --function-id=d4euc5gp5614b56crpnj
```

--------------------------------

### Run lint and tests from repo root

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/AGENTS.md

Run these commands from the repository root to verify the codebase. golangci-lint runs all linters, and go test -race runs tests with the race detector enabled.

```bash
golangci-lint run ./...
go test -race ./...
```

--------------------------------

### Run Go application locally for debugging

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/opentelemetry/README.md

Commands to scale down the containerized app and run the Go program directly from the host for faster iteration.

```bash
docker-compose -f compose-e2e.yaml up -d --scale app=0
go mod tidy
YDB_DSN=grpc://localhost:2136/local \
  OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317 \
  go run .
```

--------------------------------

### Change default query mode with ydb.WithQueryMode

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/SQL.md

Use ydb.WithQueryMode to set the query mode for a single ExecContext call. This example uses SchemeQueryMode for a DDL statement (DROP TABLE). The context is passed as the first argument to ExecContext.

```go
res, err = db.ExecContext(ydb.WithQueryMode(ctx, ydb.SchemeQueryMode),
   "DROP TABLE `/full/path/to/table/series`",
)
```

--------------------------------

### Using a single *table.QueryParameters argument

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/SQL.md

Shows how to pass all query parameters in a single *table.QueryParameters object, constructed with table.NewQueryParameters and table.ValueParam.

```go
rows, err := db.QueryContext(ctx, 
  `
    DECLARE $title AS Text;
    DECLARE $views AS Uint64;
    SELECT season_id FROM seasons WHERE title LIKE $title AND views > $views;
  `,
  table.NewQueryParameters(
      table.ValueParam("$seasonTitle", types.TextValue("%Season 1%")),
      table.ValueParam("$views", types.Uint64Value((1000)),
  ),
)
```

--------------------------------

### Unwrap native driver from *sql.Conn with retry.Do

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/SQL.md

Shows how to unwrap the native driver from a *sql.Conn inside a retry.Do callback. This allows using native driver features like Scripting().Execute while still working with the *sql.Conn for standard queries.

```go
err := retry.Do(context.TODO(), db, func(ctx context.Context, cc *sql.Conn) error {
    nativeDriver, err := ydb.Unwrap(cc)
    if err != nil {
        return err // return err to retryer
    }
    res, err := nativeDriver.Scripting().Execute(ctx,
        "SELECT 1+1",
        table.NewQueryParameters(),
    )
    if err != nil {
        return err // return err to retryer
    }
    // work with cc
    rows, err := cc.QueryContext(ctx, "SELECT 1;")
    if err != nil {
        return err // return err to retryer
    }
    ...
    return nil // good final of retry operation
}, retry.WithIdempotent(true))
```

--------------------------------

### Connect to YDB

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/README.md

Establish a connection to a YDB instance using the ydb.Open function.

```go
db, err := ydb.Open(ctx, "grpc://localhost:2136/local")
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Perform scaled arithmetic with decimal types

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/pkg/decimal/README.md

Demonstrates how to correctly perform addition on decimal types by applying a scale factor to the math/big.Int values.

```go
import (
	"ydb/decimal"
	"math/big"
)

var scaleFactor = big.NewInt(10000000000) // Default scale is 9.

func main() {
	x := decimal.FromInt128([16]byte{...})
	x.Add(x, big.NewInt(42)) // Incorrect.
	x.Add(x, scale(42))      // Correct.
}

func scale(n int64) *big.Int {
	x := big.NewInt(n)
	return x.Mul(x, scaleFactor)
}
```

--------------------------------

### Build and run healthcheck as application

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/serverless/healthcheck/README.md

Clone the repository, build the binary, and run it with YDB credentials and URL flags. The YDB endpoint is specified with -ydb and multiple -url flags can be provided.

```bash
git clone github.com/ydb-platform/ydb-go-sdk/v3 ydb-go-sdk
cd ydb-go-sdk/examples/serverless/healthcheck
go build -o healthcheck .
YDB_SERVICE_ACCOUNT_KEY_FILE_CREDENTIALS=/path/to/sa/key/file \
healthcheck \
   -ydb=grpcs://types.serverless.yandexcloud.net:2135/ru-central1/b1g8skpblkos03malf3s/etn01f8gv9an9sedo9fu \
   -url=www.ya.ru
   -url=google.com
   -url=rampler.ru
```

--------------------------------

### Run the worker application with YDB Docker

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/coordination/README.md

Build the Go application and run it with anonymous credentials against a local YDB instance. The command sets the semaphore prefix to 'job-', processes 10 tasks, and uses a capacity of 4.

```bash
$ go build 
$ YDB_ANONYMOUS_CREDENTIALS=1 ./lock -ydb grpc://localhost:2136/local -path /local/test --semaphore-prefix job- --tasks 10 --capacity 4
```

--------------------------------

### Run Arrow tests and benchmarks

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/tests/integration/arrow/README.md

Commands to run tests with race detection, integration tags, coverage, and benchmarks. Requires Go 1.25 or newer and the module's local replace build.

```sh
go test -race ./...
go test -race -tags integration ./...
go test -mod=readonly -race -tags integration \
  -coverpkg=github.com/ydb-platform/ydb-go-sdk/v3/... \
  -coverprofile arrow.txt -covermode atomic ./...
go test -tags integration -run '^$' -bench BenchmarkFormats -benchtime=100x -count=5 -cpu=4 -v
```

--------------------------------

### Unwrap native driver from *sql.DB

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/SQL.md

Opens a database connection with sql.Open and unwraps the native YDB driver using ydb.Unwrap. The native driver is then used to perform a table operation within a session.

```go
db, err := sql.Open("ydb", "grpc://localhost:2136/local")
if err != nil {
  t.Fatal(err)
}
nativeDriver, err = ydb.Unwrap(db)
if err != nil {
  t.Fatal(err)
}
nativeDriver.Table().Do(ctx, func(ctx context.Context, s table.Session) error {
  // doing with native YDB session
  return nil
})
```

--------------------------------

### Run the code snippet with go run

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/transaction/database/sql/README.md

Use this command to execute the Go program that uses the database/sql driver for YDB. The -ydb flag specifies the YDB endpoint and database in the format grpcs://endpoint/?database=database.

```bash
go run -ydb="grpcs://endpoint/?database=database"
```

--------------------------------

### TestBinding: Verify query bindings with TablePathPrefix, Declare, and Positional

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/SQL.md

Unit test that creates a query binder with TablePathPrefix, Declare, and Positional options, then checks the generated YQL and parameters. Requires the query, table, and types packages from the ydb-go-sdk.

```go
func TestBinding(t *testing.T) {
  bindings := query.NewBind(
    query.TablePathPrefix("/local/path/to/my/folder"), // bind pragma TablePathPrefix
    query.Declare(),                                   // bind parameters declare
    query.Positional(),                                // auto-replace positional args
  )
  query, params, err := bindings.ToYQL("SELECT ?, ?, ?", 1, uint64(2), "3")
  require.NoError(t, err)
  require.Equal(t, `-- bind TablePathPrefix
PRAGMA TablePathPrefix("/local/path/to/my/folder");

-- bind declares
DECLARE $p0 AS Int32;
DECLARE $p1 AS Uint64;
DECLARE $p2 AS Utf8;

-- origin query with positional args replacement
SELECT $p0, $p1, $p2`, query)
  require.Equal(t, table.NewQueryParameters(
    table.ValueParam("$p0", types.Int32Value(1)),
    table.ValueParam("$p1", types.Uint64Value(2)),
    table.ValueParam("$p2", types.TextValue("3")),
  ), params)
}
```

--------------------------------

### Run static_credentials authentication

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/auth/static_credentials/README.md

Use the static_credentials command to connect to a YDB endpoint with a specified database, user, and password.

```bash
static_credentials -ydb="grpcs://endpoint/?database=database" -user="user" -password="password"
```

--------------------------------

### Usage with database/sql

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/README.md

Use the standard database/sql interface to interact with YDB.

```go
import (
    "context"
    "database/sql"
    "log"

    _ "github.com/ydb-platform/ydb-go-sdk/v3"
)

...

db, err := sql.Open("ydb", "grpc://localhost:2136/local")
if err != nil {
    log.Fatal(err)
}
defer db.Close() // cleanup resources
var (
    id    int32
    myStr string
)
row := db.QueryRowContext(context.TODO(), `SELECT 42 as id, "my string" as myStr`)
if err = row.Scan(&id, &myStr); err != nil {
    log.Printf("select failed: %v", err)
    return
}
log.Printf("id = %d, myStr = \"%s\"", id, myStr)
```

--------------------------------

### Check SLO stack services

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/tests/slo/SLO.md

Lists the running services of the SLO stack. Use this to verify that the stack is up and that grafana and prometheus are present.

```bash
docker compose ps
```

--------------------------------

### Open YDB console

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/tests/slo/SLO.md

Opens the YDB console in the default browser.

```bash
open "http://127.0.0.1:$(docker compose port storage-1 8765 | cut -d: -f2)"
```

--------------------------------

### Execute SELECT query with Query service

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/README.md

Execute a query using the Query service client with automatic retry logic.

```go
// Do retry operation on errors with best effort
err := db.Query().Do( // Do retry operation on errors with best effort
	ctx, // context manage exiting from Do
	func(ctx context.Context, s query.Session) (err error) { // retry operation
		streamResult, err := s.Query(ctx, `SELECT 42 as id, "myStr" as myStr;`)
		if err != nil {
			return err // for auto-retry with driver
		}
		defer func() { _ = streamResult.Close(ctx) }() // cleanup resources
		for rs, err := range streamResult.ResultSets(ctx) {
			if err != nil {
				return err
			}
			for row, err := range rs.Rows(ctx) {
				if err != nil {
					return err
				}
				type myStruct struct {
					Id  int32  `sql:"id"`
					Str string `sql:"myStr"`
				}
				var s myStruct
				if err = row.ScanStruct(&s); err != nil {
					return err // generally scan error not retryable, return it for driver check error
				}
			}
		}

		return nil
	},
	query.WithIdempotent(),
)
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Follow workload logs

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/tests/slo/SLO.md

Follows the logs of the workload-current service to observe workload progress and errors.

```bash
docker compose logs -f workload-current
```

--------------------------------

### Create Yandex serverless function version

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/serverless/healthcheck/README.md

Create a function version using yc sls fn version create with the specified service account, runtime, entrypoint, memory, timeout, and environment variables. The environment variables include YDB_METADATA_CREDENTIALS, YDB, and URLS.

```bash
yc sls fn version create \
   --service-account-id=aje46n285h0re8nmm5u6 \
   --runtime=golang118 \
   --entrypoint=main.Serverless \
   --memory=128m \
   --execution-timeout=1s \
   --environment YDB_METADATA_CREDENTIALS="1" \
   --environment YDB="grpcs://ydb.serverless.yandexcloud.net:2135/ru-central1/b1g8skpblkos03malf3s/etnpa7o3qltdfgu9vsap" \
   --environment URLS="https://ya.ru,https://google.com,https://rambler.ru" \
   --source-path=./archive.zip \
   --function-id=d4empp866m0b4m2gspu9
```

--------------------------------

### Recreate YDB container for tracing

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/opentelemetry/README.md

Use this command to recreate the YDB container after updating the configuration files to include tracing settings.

```bash
# Recreate the ydb container after changing ./ydb_config/ydb-config.yaml
docker-compose -f compose-e2e.yaml up -d --force-recreate ydb
```

--------------------------------

### Using table.ParameterOption arguments

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/SQL.md

Shows how to pass query parameters using table.ValueParam, which requires the parameter name to include the '$' prefix. This method uses YDB types directly.

```go
rows, err := db.QueryContext(ctx, 
  `
    DECLARE $title AS Text;
    DECLARE $views AS Uint64;
    SELECT season_id FROM seasons WHERE title LIKE $title AND views > $views;
  `,
  table.ValueParam("$seasonTitle", types.TextValue("%Season 1%")),
  table.ValueParam("$views", types.Uint64Value((1000)),
)
```

--------------------------------

### Acquire an ephemeral semaphore (lock) in Go

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/coordination/README.md

Pseudocode showing the loop to open a coordination session and acquire an exclusive ephemeral semaphore. It handles errors by closing the session and retrying, and stops work when the lease context is done.

```go
for {
    session, err := db.Coordination().OpenSession(ctx, path)
    if err != nil {
		// The context is canceled.
        break		
    }

    lease, err := session.AcquireSemaphore(ctx, semaphore, coordination.Exclusive, options.WithEphemeral(true))
    if err != nil {
        session.Close(ctx)
        continue
    }

    // The lock is acquired. 
    go doWork(lease.Context())
	
    // Wait until the lock is released.
    <-lease.Context().Done():
	
    // The lock is not acquired anymore.
    cancelWork()
}
```

--------------------------------

### ydb.Open with WithQueryDefaultResultFormatArrow

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/QUERY.md

Opens a driver with a default result format of Arrow IPC for queries. The default applies to queries and transactions through Query Service connectors.

```APIDOC
## [OPEN] ydb.Open(ctx, dsn, ydb.WithQueryDefaultResultFormatArrow(ipc.NewReader))

### Description
Opens a driver with a default result format of Arrow IPC for queries. The default applies to queries and transactions through Query Service connectors.

### Method
Open

### Endpoint
`ydb.Open(ctx, dsn, opts...)`

### Parameters
#### Options
- **ydb.WithQueryDefaultResultFormatArrow(ipc.NewReader, opts...)** - Required - Sets the default reader factory and options for queries.

### Request Example
```go
db, err := ydb.Open(ctx, dsn,
    ydb.WithQueryDefaultResultFormatArrow(ipc.NewReader),
)
if err != nil {
    return err
}
defer db.Close(ctx)
```

### Response
#### Success Response
- **db** (Driver) - The opened driver.

#### Response Example
```go
db, err := ydb.Open(ctx, dsn,
    ydb.WithQueryDefaultResultFormatArrow(ipc.NewReader),
)
if err != nil {
    return err
}
defer db.Close(ctx)
```
```

--------------------------------

### Add Prometheus metrics for driver events

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/SQL.md

Adds Prometheus monitoring to the native driver using ydbMetrics.WithTraces. Requires opening the connection via ydb.Connector and then using sql.OpenDB.

```go
import (
    "github.com/ydb-platform/ydb-go-sdk/v3/trace"
    ydbMetrics "github.com/ydb-platform/ydb-go-sdk-prometheus"
)
...
nativeDriver, err := ydb.Open(ctx, connectionString,
    ...
    ydbMetrics.WithTraces(registry, ydbMetrics.WithDetails(trace.DetailsAll)),
)
if err != nil {
    // fallback on error
}
connector, err := ydb.Connector(nativeDriver)
if err != nil {
    // fallback on error
}
db := sql.OpenDB(connector)
```

--------------------------------

### Add zap logging for driver events

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/SQL.md

Adds zap logging to the native driver by using ydbZap.WithTraces. Requires opening the connection via ydb.Connector and then using sql.OpenDB.

```go
import (
    "github.com/ydb-platform/ydb-go-sdk/v3/trace"
    ydbZap "github.com/ydb-platform/ydb-go-sdk-zap"
)
...
nativeDriver, err := ydb.Open(ctx, connectionString,
    ...
    ydbZap.WithTraces(log, trace.DetailsAll),
)
if err != nil {
    // fallback on error
}
connector, err := ydb.Connector(nativeDriver)
if err != nil {
    // fallback on error
}
db := sql.OpenDB(connector)
```

--------------------------------

### Retry helper over sql.Tx with retry.DoTx

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/SQL.md

Uses retry.DoTx to execute a custom lambda with a *sql.Tx, automatically handling commit/rollback. The lambda must return an error to trigger retry or nil on success. Options include retry.WithIdempotent(true) and retry.WithTxOptions to set isolation level and read-only.

```go
import (
    "github.com/ydb-platform/ydb-go-sdk/v3/retry"
)
...
err := retry.DoTx(context.TODO(), db, func(ctx context.Context, tx *sql.Tx) error {
    // work with tx
    rows, err := tx.QueryContext(ctx, "SELECT 1;")
    if err != nil {
        return err // return err to retryer
    }
    ...
    return nil // good final of retry tx operation
}, retry.WithIdempotent(true), retry.WithTxOptions(&sql.TxOptions{
    Isolation: sql.LevelSnapshot,
    ReadOnly:  true,
}))

```

--------------------------------

### Troubleshoot workload connection error

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/tests/slo/SLO.md

Checks service status and database-readiness logs when the workload exits immediately with a connection error. Wait for database-readiness to complete.

```bash
docker compose ps
docker compose logs database-readiness
```

--------------------------------

### Export default config from ydb-local container

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/opentelemetry/ydb_config/README.md

Use this command to copy the default YDB config from a running 'ydb-local' container to the local file 'ydb_config/ydb-config.yaml'.

```bash
docker cp ydb-local:/ydb_data/cluster/kikimr_configs/config.yaml ./ydb_config/ydb-config.yaml
```

--------------------------------

### Query Prometheus for sdk_operations_total

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/tests/slo/SLO.md

Queries Prometheus for the sdk_operations_total metric. Resolves the port via docker compose port.

```bash
curl "http://127.0.0.1:$(docker compose port prometheus 9090 | cut -d: -f2)/api/v1/query?query=sdk_operations_total"
```

--------------------------------

### Ping the server with redis-cli

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/redis_over_ydb/README.md

Sends a PING command to the running server to verify connectivity.

```bash
redis-cli -p 6379 PING
```

--------------------------------

### Add Jaeger tracing for driver events

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/SQL.md

Adds Jaeger tracing to the native driver using ydbOpentracing.WithTraces. Requires opening the connection via ydb.Connector and then using sql.OpenDB.

```go
import (
    "github.com/ydb-platform/ydb-go-sdk/v3/trace"
    ydbOpentracing "github.com/ydb-platform/ydb-go-sdk-opentracing"
)
...
nativeDriver, err := ydb.Open(ctx, connectionString,
    ...
    ydbOpentracing.WithTraces(trace.DriverConnEvents | trace.DriverClusterEvents | trace.DriverRepeaterEvents | trace.DiscoveryEvents),
)
if err != nil {
    // fallback on error
}
connector, err := ydb.Connector(nativeDriver)
if err != nil {
    // fallback on error
}
db := sql.OpenDB(connector)
```

--------------------------------

### QueryRow with Ydb.Value and Arrow formats

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/apache_arrow/README.md

Shows the same row API with the usual Ydb.Value wire format and with Arrow IPC on the wire. The Arrow variant uses `query.WithResultFormatArrow(ipc.NewReader)` and `ScanNamed` to scan by column name. The option is experimental and requires server support.

```go
// With the usual Ydb.Value wire format:
row, err := db.Query().QueryRow(ctx, `SELECT 42 AS id, "hello"u AS name;`)
if err != nil {
    return err
}
var id int32
var name string
if err := row.Scan(&id, &name); err != nil {
    return err
}

// With Arrow IPC on the wire and the same SDK scans:
row, err = db.Query().QueryRow(ctx, `SELECT 42 AS id, "hello"u AS name;`,
    query.WithResultFormatArrow(ipc.NewReader),
)
if err != nil {
    return err
}
if err := row.ScanNamed(query.Named("id", &id), query.Named("name", &name)); err != nil {
    return err
}
```

--------------------------------

### PromQL queries for SLO metrics

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/tests/slo/SLO.md

Useful PromQL queries for monitoring SLO test metrics: operation rate, read latency p99, and retry rate.

```promql
rate(sdk_operations_total[1m])
sdk_operation_latency_p99_seconds{operation_type="read"}
rate(sdk_retry_attempts_total[1m])
```

--------------------------------

### Go build tag for integration tests

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/tests/integration/README.md

Required build tag for all integration test files in this package. Without it, the tests will not run as integration tests in the GitHub Actions workflow.

```go
//go:build integration
// +build integration
```

--------------------------------

### Restart YDB with overridden config

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/examples/opentelemetry/ydb_config/README.md

Restart the YDB container using docker-compose with the overridden config. The main compose file passes '--config-path /ydb_config/ydb-config.yaml'.

```bash
docker-compose -f compose-e2e.yaml up -d --force-recreate ydb
```

--------------------------------

### Retry helper over sql.Conn with retry.Do

Source: https://github.com/ydb-platform/ydb-go-sdk/blob/master/SQL.md

Uses retry.Do to execute a custom lambda with a *sql.Conn, automatically retrying transient errors. The lambda must return an error to trigger retry or nil on success. The retry.WithIdempotent(true) option marks the operation as idempotent.

```go
import (
   "github.com/ydb-platform/ydb-go-sdk/v3/retry"
)
...
err := retry.Do(context.TODO(), db, func(ctx context.Context, cc *sql.Conn) error {
   // work with cc
   rows, err := cc.QueryContext(ctx, "SELECT 1;")
   if err != nil {
       return err // return err to retryer
   }
   ...
   return nil // good final of retry operation
}, retry.WithIdempotent(true))

```
Tokens:
Raw