App in Go (archived version 1)

• 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 v1 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"
  "github.com/yandex-cloud/ydb-go-sdk/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 = `
    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(),
    )
    if err != nil {
      return err
    }
    return res.Err()
  }),
)
if err != nil {
  // handling the query execution error
}

Processing execution results

Query results:

log.Println("> select_simple_transaction:")
for res.NextSet() {
  for res.NextRow() {
    res.SeekItem("series_id")
    id := res.OUint64()
    res.NextItem()
    title := res.OUTF8()
    res.NextItem()
    date := res.OString()
    log.Printf(
      "#  SeriesID: %d , Title: %s, Date: %s\n",
      id, title, date,
    )
  }
}

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 = `
    DECLARE $series AS List<UInt64>;
    SELECT series_id, season_id, title, CAST(CAST(first_aired AS Date) AS String) AS first_aired
    FROM seasons
    WHERE series_id IN $series
  `
  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(
        table.ValueParam("$series",
          ydb.ListValue(
            ydb.Uint64Value(1),
            ydb.Uint64Value(10),
          ),
        ),
      ),
    )
    if err != nil {
      return err
    }
    return res.Err()
  }),
)
if err != nil {
  // handling the query execution error
}

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:

log.Println("> scan_query_select:")
for res.NextStreamSet(ctx) {
  if err = res.Err(); err != nil {
    return err
  }
  for res.NextRow() {
    res.SeekItem("series_id")
    id := res.OUint64()
    res.SeekItem("season_id")
    season := res.OUint64()
    res.SeekItem("title")
    title := res.OUTF8()
    res.SeekItem("first_aired")
    date := res.OString()
    log.Printf("#  Season, SeriesId: %d, SeasonId: %d, Title: %s, Air date: %s\n", id, season, title, date)
  }
}
if err = res.Err(); err != nil {
  return err
}
return nil

Handling errors

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