CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/golang-cloud-google-com--go--spanner

Official Google Cloud Spanner client library for Go providing comprehensive database operations, transactions, and admin functionality

—

Pending
Overview
Eval results
Files

protobuf-types.mddocs/

Protobuf Types

Overview of protobuf packages and key message types for Spanner APIs.

Package Overview

The Spanner Go client includes several protobuf packages:

  1. spannerpb - Core Spanner API types
  2. databasepb - Database administration types
  3. instancepb - Instance administration types
  4. adapterpb - Adapter API types (internal)
  5. executorpb - Executor API types (internal)

Core Spanner Types (spannerpb)

import "cloud.google.com/go/spanner/apiv1/spannerpb"

Request Types

type CreateSessionRequest struct {
    Database string
    Session  *Session
}

type BatchCreateSessionsRequest struct {
    Database      string
    SessionCount  int32
    SessionTemplate *Session
}

type GetSessionRequest struct {
    Name string
}

type DeleteSessionRequest struct {
    Name string
}

type ExecuteSqlRequest struct {
    Session         string
    Transaction     *TransactionSelector
    Sql             string
    Params          *Struct
    ParamTypes      map[string]*Type
    ResumeToken     []byte
    QueryMode       ExecuteSqlRequest_QueryMode
    PartitionToken  []byte
    Seqno           int64
    QueryOptions    *ExecuteSqlRequest_QueryOptions
    RequestOptions  *RequestOptions
    DirectedReadOptions *DirectedReadOptions
    DataBoostEnabled bool
}

type ReadRequest struct {
    Session        string
    Transaction    *TransactionSelector
    Table          string
    Index          string
    Columns        []string
    KeySet         *KeySet
    Limit          int64
    ResumeToken    []byte
    PartitionToken []byte
    RequestOptions *RequestOptions
    DirectedReadOptions *DirectedReadOptions
    DataBoostEnabled bool
    OrderBy        ReadRequest_OrderBy
    LockHint       ReadRequest_LockHint
}

type BeginTransactionRequest struct {
    Session            string
    Options            *TransactionOptions
    RequestOptions     *RequestOptions
    MutationKey        *RequestOptions_TransactionRoutingInfo
}

type CommitRequest struct {
    Session                     string
    Mutations                   []*Mutation
    ReturnCommitStats           bool
    MaxCommitDelay              *durationpb.Duration
    RequestOptions              *RequestOptions
    PrecommitToken              *MultiplexedSessionPrecommitToken
}

type RollbackRequest struct {
    Session       string
    TransactionId []byte
}

Response Types

type ResultSet struct {
    Metadata *ResultSetMetadata
    Rows     []*Struct
    Stats    *ResultSetStats
    PrecommitToken *MultiplexedSessionPrecommitToken
}

type ResultSetMetadata struct {
    RowType         *StructType
    Transaction     *Transaction
    UndeclaredParameters *StructType
}

type ResultSetStats struct {
    QueryPlan       *QueryPlan
    QueryStats      *Struct
    RowCountExact   int64
    RowCountLowerBound int64
}

type CommitResponse struct {
    CommitTimestamp    *timestamppb.Timestamp
    CommitStats        *CommitResponse_CommitStats
    PrecommitToken     *MultiplexedSessionPrecommitToken
}

Core Data Types

type Type struct {
    Code               TypeCode
    ArrayElementType   *Type
    StructType         *StructType
    TypeAnnotation     TypeAnnotation
    ProtoTypeFqn       string
}

type TypeCode int32
const (
    TYPE_CODE_UNSPECIFIED TypeCode = 0
    BOOL                  TypeCode = 1
    INT64                 TypeCode = 2
    FLOAT64               TypeCode = 3
    FLOAT32               TypeCode = 4
    TIMESTAMP             TypeCode = 5
    DATE                  TypeCode = 6
    STRING                TypeCode = 7
    BYTES                 TypeCode = 8
    ARRAY                 TypeCode = 9
    STRUCT                TypeCode = 10
    NUMERIC               TypeCode = 11
    JSON                  TypeCode = 12
    PROTO                 TypeCode = 13
    ENUM                  TypeCode = 14
)

type Value struct {
    // One of:
    NullValue  structpb.NullValue
    BoolValue  bool
    StringValue string
    NumberValue float64
    ListValue   *ListValue
    StructValue *Struct
}

type KeySet struct {
    Keys     []*ListValue
    Ranges   []*KeyRange
    All      bool
}

type KeyRange struct {
    StartKeyType isKeyRange_StartKeyType
    EndKeyType   isKeyRange_EndKeyType
}

type Mutation struct {
    Operation isMutation_Operation
}

Transaction Types

type TransactionOptions struct {
    Mode           isTransactionOptions_Mode
    ExcludeTxnFromChangeStreams bool
}

type TransactionOptions_ReadWrite struct {
    ReadLockMode    TransactionOptions_ReadWrite_ReadLockMode
    Multiplexed     bool
    IsolationLevel  TransactionOptions_IsolationLevel
}

type TransactionOptions_ReadOnly struct {
    ReturnReadTimestamp bool
    TimestampBound      isTransactionOptions_ReadOnly_TimestampBound
    IsolationLevel      TransactionOptions_IsolationLevel
}

type TransactionOptions_PartitionedDml struct {}

type TransactionOptions_Batch struct {}

type TransactionSelector struct {
    Selector isTransactionSelector_Selector
}

type Transaction struct {
    Id                 []byte
    ReadTimestamp      *timestamppb.Timestamp
    PrecommitToken     *MultiplexedSessionPrecommitToken
}

Session Types

type Session struct {
    Name             string
    Labels           map[string]string
    CreateTime       *timestamppb.Timestamp
    ApproximateLastUseTime *timestamppb.Timestamp
    CreatorRole      string
    Multiplexed      bool
}

Request Options

type RequestOptions struct {
    Priority        RequestOptions_Priority
    RequestTag      string
    TransactionTag  string
    TransactionRoutingInfo *RequestOptions_TransactionRoutingInfo
}

type RequestOptions_Priority int32
const (
    PRIORITY_UNSPECIFIED RequestOptions_Priority = 0
    PRIORITY_LOW         RequestOptions_Priority = 1
    PRIORITY_MEDIUM      RequestOptions_Priority = 2
    PRIORITY_HIGH        RequestOptions_Priority = 3
)

Directed Read Options

type DirectedReadOptions struct {
    Replicas isDirectedReadOptions_Replicas
}

type DirectedReadOptions_IncludeReplicas struct {
    ReplicaSelections []*DirectedReadOptions_ReplicaSelection
    AutoFailoverDisabled bool
}

type DirectedReadOptions_ReplicaSelection struct {
    Location string
    Type     DirectedReadOptions_ReplicaSelection_Type
}

Database Admin Types (databasepb)

import "cloud.google.com/go/spanner/admin/database/apiv1/databasepb"

Database Types

type Database struct {
    Name                 string
    State                Database_State
    CreateTime           *timestamppb.Timestamp
    RestoreInfo          *RestoreInfo
    EncryptionConfig     *EncryptionConfig
    EncryptionInfo       []*EncryptionInfo
    VersionRetentionPeriod string
    EarliestVersionTime  *timestamppb.Timestamp
    DefaultLeader        string
    DatabaseDialect      DatabaseDialect
    EnableDropProtection bool
    ReconciliationState  Database_ReconciliationState
    QuorumInfo           *QuorumInfo
}

type CreateDatabaseRequest struct {
    Parent          string
    CreateStatement string
    ExtraStatements []string
    EncryptionConfig *EncryptionConfig
    DatabaseDialect  DatabaseDialect
    ProtoDescriptors []byte
}

type UpdateDatabaseDdlRequest struct {
    Database        string
    Statements      []string
    OperationId     string
    ProtoDescriptors []byte
}

type GetDatabaseDdlRequest struct {
    Database string
}

type GetDatabaseDdlResponse struct {
    Statements       []string
    ProtoDescriptors []byte
}

type DropDatabaseRequest struct {
    Database string
}

Backup Types

type Backup struct {
    Name                 string
    Database             string
    VersionTime          *timestamppb.Timestamp
    ExpireTime           *timestamppb.Timestamp
    CreateTime           *timestamppb.Timestamp
    SizeBytes            int64
    State                Backup_State
    ReferencingDatabases []string
    EncryptionInfo       *EncryptionInfo
    DatabaseDialect      DatabaseDialect
    ReferencingBackups   []string
    MaxExpireTime        *timestamppb.Timestamp
    BackupSchedules      []string
    IncrementalBackupChainId string
    OldestVersionTime    *timestamppb.Timestamp
    ExclusiveSizeBytes   int64
}

type CreateBackupRequest struct {
    Parent     string
    BackupId   string
    Backup     *Backup
    EncryptionConfig *EncryptionConfig
}

type RestoreDatabaseRequest struct {
    Parent           string
    DatabaseId       string
    Backup           string
    EncryptionConfig *EncryptionConfig
}

type CopyBackupRequest struct {
    Parent           string
    BackupId         string
    SourceBackup     string
    ExpireTime       *timestamppb.Timestamp
    EncryptionConfig *EncryptionConfig
}

Backup Schedule Types

type BackupSchedule struct {
    Name                string
    Spec                *BackupScheduleSpec
    RetentionDuration   *durationpb.Duration
    EncryptionConfig    *EncryptionConfig
    FullBackupSpec      *FullBackupSpec
    IncrementalBackupSpec *IncrementalBackupSpec
    UpdateTime          *timestamppb.Timestamp
}

type CreateBackupScheduleRequest struct {
    Parent         string
    BackupScheduleId string
    BackupSchedule *BackupSchedule
}

Instance Admin Types (instancepb)

import "cloud.google.com/go/spanner/admin/instance/apiv1/instancepb"

Instance Types

type Instance struct {
    Name              string
    Config            string
    DisplayName       string
    NodeCount         int32
    ProcessingUnits   int32
    State             Instance_State
    Labels            map[string]string
    EndpointUris      []string
    CreateTime        *timestamppb.Timestamp
    UpdateTime        *timestamppb.Timestamp
    Autoscaling       *Autoscaling
    Edition           Instance_Edition
    FreeInstanceMetadata *FreeInstanceMetadata
}

type CreateInstanceRequest struct {
    Parent     string
    InstanceId string
    Instance   *Instance
}

type UpdateInstanceRequest struct {
    Instance  *Instance
    FieldMask *fieldmaskpb.FieldMask
}

type DeleteInstanceRequest struct {
    Name string
}

Instance Config Types

type InstanceConfig struct {
    Name          string
    DisplayName   string
    ConfigType    InstanceConfig_Type
    Replicas      []*ReplicaInfo
    OptionalReplicas []*ReplicaInfo
    BaseConfig    string
    Labels        map[string]string
    Etag          string
    LeaderOptions []string
    Reconciling   bool
    State         InstanceConfig_State
    FreeInstanceAvailability []*FreeInstanceAvailability
    QuorumInfo    *QuorumInfo
}

type CreateInstanceConfigRequest struct {
    Parent           string
    InstanceConfigId string
    InstanceConfig   *InstanceConfig
    ValidateOnly     bool
}

Usage Examples

Using Protobuf Types Directly

import (
    "cloud.google.com/go/spanner/apiv1/spannerpb"
    "google.golang.org/protobuf/types/known/structpb"
)

// Create typed request
req := &spannerpb.ExecuteSqlRequest{
    Session: sessionName,
    Sql:     "SELECT * FROM Users WHERE id = @id",
    Params: &structpb.Struct{
        Fields: map[string]*structpb.Value{
            "id": structpb.NewNumberValue(123),
        },
    },
    ParamTypes: map[string]*spannerpb.Type{
        "id": {Code: spannerpb.TypeCode_INT64},
    },
    QueryOptions: &spannerpb.ExecuteSqlRequest_QueryOptions{
        OptimizerVersion: "latest",
    },
    RequestOptions: &spannerpb.RequestOptions{
        Priority:   spannerpb.RequestOptions_PRIORITY_HIGH,
        RequestTag: "user-query",
    },
}

Accessing Protobuf Fields

// From high-level client RowIterator
iter := client.Single().Query(ctx, stmt)
defer iter.Stop()

// Access metadata
if iter.Metadata != nil {
    fmt.Printf("Row type: %v\n", iter.Metadata.RowType)
    if iter.Metadata.Transaction != nil {
        fmt.Printf("Transaction ID: %x\n", iter.Metadata.Transaction.Id)
    }
}

// Access query plan (after QueryWithStats)
if iter.QueryPlan != nil {
    fmt.Printf("Query plan: %v\n", iter.QueryPlan)
}

Best Practices

  1. Use high-level client: Avoid protobuf types unless necessary
  2. Import specific packages: Import only needed protobuf packages
  3. Check nil fields: Protobuf fields may be nil
  4. Use type-safe constructors: Use protobuf helper functions
  5. Understand proto3: Familiarize with proto3 semantics
  6. Reference official docs: See Spanner API documentation

Complete Type Reference

For exhaustive type definitions, see:

Install with Tessl CLI

npx tessl i tessl/golang-cloud-google-com--go--spanner

docs

client.md

dml.md

index.md

keys.md

low-level.md

protobuf-types.md

reads.md

testing.md

transactions.md

types.md

writes.md

tile.json