App in Go (archived version 2)

• Initializing a database connection
• Creating tables
• Retrieving data with a Select
  • Processing execution results
• Scan queries
• Scan queries
• Handling errors

This page contains a detailed description of the code of a test app that is available as part of the v2 Go SDK YDB.

Initializing a database connection

To interact with YDB, create an instance of the driver, client, and session:

• The YDB driver lets the app and YDB interact at the transport layer. The driver must exist throughout the YDB access lifecycle and be initialized before creating a client or session.
• The YDB client runs on top of the YDB driver and enables the handling of entities and transactions.
• The YDB session contains information about executed transactions and prepared queries, and is part of the YDB client context.

To work with YDB in Go, import the ydb-go-sdk driver package:

import (
  // general imports
  "context"
  "path"
  // imports of ydb-go-sdk packages
  "github.com/yandex-cloud/ydb-go-sdk/v2"
  "github.com/yandex-cloud/ydb-go-sdk/v2/table" // to work with the table service
)

App code snippet for driver initialization:

func (cmd *Command) Run(ctx context.Context, params cli.Parameters) error {
  dialer := &ydb.Dialer{
    DriverConfig: cmd.config(params),
    TLSConfig:    cmd.tls(),
    Timeout:      time.Second,
  }
  driver, err := dialer.Dial(ctx, params.Endpoint)
  if err != nil {
    return fmt.Errorf("dial error: %v", err)
  }
  defer driver.Close()

App code snippet for creating a session:

tableClient := table.Client{
  Driver: driver,
}
sp := table.SessionPool{
  IdleThreshold: time.Second,
  Builder:       &tableClient,
}
defer sp.Close(ctx)

Creating tables

Creating tables to be used in operations on a test app. This step results in the creation of DB tables of the series directory data model:

• Series
• Seasons
• Episodes

Once the tables are created, the method for getting information about data schema objects is called and the result of its execution is output.

To create tables, use the Session.CreateTable() method:

func createTables(ctx context.Context, sp *table.SessionPool, prefix string) (err error) {
  err = table.Retry(ctx, sp,
    table.OperationFunc(func(ctx context.Context, s *table.Session) error {
      return s.CreateTable(ctx, path.Join(prefix, "series"),
        table.WithColumn("series_id", ydb.Optional(ydb.TypeUint64)),
        table.WithColumn("title", ydb.Optional(ydb.TypeUTF8)),
        table.WithColumn("series_info", ydb.Optional(ydb.TypeUTF8)),
        table.WithColumn("release_date", ydb.Optional(ydb.TypeUint64)),
        table.WithColumn("comment", ydb.Optional(ydb.TypeUTF8)),
        table.WithPrimaryKeyColumn("series_id"),
      )
    }),
  )

You can use the Session.DescribeTable() method to output information about the table structure and make sure that it was properly created:

func describeTable(ctx context.Context, sp *table.SessionPool, path string) (err error) {
  err = table.Retry(ctx, sp,
    table.OperationFunc(func(ctx context.Context, s *table.Session) error {
      desc, err := s.DescribeTable(ctx, path)
      if err != nil {
        return err
      }
      log.Printf("\n> describe table: %s", path)
      for _, c := range desc.Columns {
        log.Printf("column, name: %s, %s", c.Type, c.Name)
      }
      return nil
    }),
  )

Retrieving data with a Select

Retrieving data using a SELECT statement in YQL. Handling the retrieved data selection in the app.

To execute YQL queries, use the Session.Execute() method.
The SDK lets you explicitly control the execution of transactions and configure the transaction execution mode using the TxControl class.

var (
  query = `--!syntax_v1
    DECLARE $seriesID AS Uint64;
    $format = DateTime::Format("%Y-%m-%d");
    SELECT
      series_id,
      title,
      $format(DateTime::FromSeconds(CAST(DateTime::ToSeconds(DateTime::IntervalFromDays(CAST(release_date AS Int16))) AS Uint32))) AS release_date
    FROM
      series
    WHERE
      series_id = $seriesID;`
  res *table.Result
)
readTx := table.TxControl(
  table.BeginTx(
    table.WithOnlineReadOnly(),
  ),
  table.CommitTx(),
)
err = table.Retry(ctx, sp,
  table.OperationFunc(func(ctx context.Context, s *table.Session) (err error) {
    _, res, err = s.Execute(ctx, readTx, query,
      table.NewQueryParameters(
        table.ValueParam("$seriesID", ydb.Uint64Value(1)),
      ),
      table.WithQueryCachePolicy(
        table.WithQueryCachePolicyKeepInCache(),
      ),
      table.WithCollectStatsModeBasic(),
    )
    return
  }),
)
if err != nil {
  return err
}

Processing execution results

Query results:

    var (
        id    *uint64
        title *string
        date  *[]byte
    )
  log.Println("> select_simple_transaction:")
    for res.NextResultSet(ctx, "series_id", "title", "release_date") {
        for res.NextRow() {
            err = res.Scan(&id, &title, &date)
            if err != nil {
                return err
            }
      log.Printf(
        "#  SeriesID: %d , Title: %s, Date: %s\n",
        *id, *title, *date,
      )
        }
    }
    if err = res.Err(); err != nil {
        return err
    }
    return nil
}

Scan queries

Making a scan query that results in a data stream. Streaming lets you read an unlimited number of rows and amount of data.

var (
  query = `
    SELECT series_id, season_id, COUNT(*) AS episodes_count
    FROM episodes
    GROUP BY series_id, season_id
    ORDER BY series_id, season_id;`
  res *table.Result
)
err = table.Retry(ctx, sp,
  table.OperationFunc(func(ctx context.Context, s *table.Session) (err error) {
    res, err = s.StreamExecuteScanQuery(ctx, query, table.NewQueryParameters())
    return err
  }),
)
if err != nil {
  return err
}

Scan queries

Making a scan query that results in a data stream. Streaming lets you read an unlimited number of rows and amount of data.

Query results:

  var (
    seriesID uint64
    seasonID uint64
    count    uint64
  )
  log.Println("> scan_query_select:")
  for res.NextResultSet(ctx, "series_id", "season_id", "episodes_count") {
    for res.NextRow() {
      err = res.ScanWithDefaults(&seriesID, &seasonID, &count)
      if err != nil {
        return err
      }
      log.Printf("#  Season, SeriesId: %d, SeasonId: %d, Count: %d\n", seriesID, seasonID, count)
    }
  }
  if err = res.Err(); err != nil {
    return err
  }
  return nil
}

Handling errors

For more information about error handling, see Error handling in the API.