sproto

package module
v1.6.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 14, 2025 License: Apache-2.0 Imports: 22 Imported by: 1

README

Sproto: Streamlined CRUD Operations with Google Cloud Spanner and Protocol Buffers

Go Reference

The sproto package offers a collection of CRUD operations for interaction with Google Cloud Spanner, utilizing Protocol Buffers for serialization purposes.

Installation

Get the package

go get go.alis.build/sproto

Import the package

import "go.alis.build/sproto"

Usage

Create a new Sproto instance using New or NewClient

Using New
var spannerClient *spanner.Client
sproto := New(spannerClient)
defer sproto.Close()
Using NewClient
sproto, err := NewClient(context.Background(), "GOOGLE_PROJECT", "SPANNER_INSTANCE", "SPANNER_DATABASE")
if err != nil {
    log.Fatalf("failed to create client: %v", err)
}
defer sproto.Close()

If the Sproto instance was created using NewClient you can use Client() to get the underlying spanner.Client instance.

Examples

QueryProtos

Given the following Protocol Buffer message:

syntax = "proto3";

package com.example;

message User {
    string id = 1;
    string name = 2;
    Address address = 3;
    
    message Address {
        string street = 1;
    }
}

And the following table schema:

CREATE TABLE table_name (
    user_id STRING(MAX) NOT NULL,
    secondary_id STRING(MAX) NOT NULL,
    user com.example.User
) PRIMARY KEY (user_id, secondary_id);

You can read a User using ReadProto:

_, err := sproto.ReadProto(ctx, "table_name", spanner.Key{"123","456"},"user", &com.example.User{}, nil)

You can query for User using QueryProtos:

_, err := sproto.QueryProtos(ctx, "table_name", []string{"user"}, []proto.Message{&com.example.User{}}, 
            &spanner.Statement{
                    SQL: "user.name = @name",
                    Params: map[string]interface{}{
                        "name": "John Doe",
                    },
            },
            nil,
)

Documentation

Overview

Package sproto provides a collection of utilities for working with Google Cloud Spanner, utilizing Protocol Buffers for serialization purposes.

Index

Constants

This section is empty.

Variables

View Source 
var ErrInvalidFieldMask = errors.New("invalid field mask")

ErrInvalidFieldMask is returned when the field mask is invalid.

Functions

func NewPrimaryKeyColumn added in v1.5.7 

func NewPrimaryKeyColumn(name string, isGenerated, isStored bool) *primaryKeyColumn

NewPrimaryKeyColumn creates a new instance of primaryKeyColumn

  • name - the name of the column
  • isGenerated - whether the column is generated
  • isStored - whether the column is stored

In most cases, isGenerated and isStored are the same, very rarely is one true and the other false

Types

type Client added in v1.0.0 

type Client struct {
	// contains filtered or unexported fields
}

Client provides methods to easily read and write proto messages with Google Cloud Spanner(https://cloud.google.com/spanner/docs/).

It also provides methods to easily perform CRUD operations on tables in Google Cloud Spanner.

func New 

func New(client *spanner.Client) *Client

New creates a new Client instance with the provided spanner.Client instance.

func NewClient 

func NewClient(ctx context.Context, googleProject, spannerInstance, databaseName, databaseRole string) (*Client, error)

NewClient creates a new Client instance with the provided Google Cloud Spanner configuration. Leave databaseRole empty if you are not using fine grained roles on the database.

func (*Client) BatchDeleteRows added in v1.0.0 

func (s *Client) BatchDeleteRows(ctx context.Context, tableName string, rowKeys []spanner.Key) error

BatchDeleteRows deletes multiple rows from the specified table using the provided row keys.

func (*Client) BatchInsertRows added in v1.0.0 

func (s *Client) BatchInsertRows(ctx context.Context, tableName string, rows []map[string]interface{}) error

BatchInsertRows inserts multiple rows into the specified table using the provided column values.

The primary key value(s) must be included in the rows.

The rows are represented as a slice of maps where each map represents a row. Each map contains column names and their respective values. The value types must match the column types in the table schema.

func (*Client) BatchReadProtos added in v1.0.0 

func (s *Client) BatchReadProtos(ctx context.Context, tableName string, rowKeys []spanner.Key, columnName string, message proto.Message, readMask *fieldmaskpb.FieldMask) ([]proto.Message, error)

BatchReadProtos reads multiple proto messages from the specified table using the provided row keys and column name.

The row keys are tuples of the rows' primary keys values and are used to identify the rows to read. The order of the keys must match the order of the primary key columns in the table schema. For example if the primary key is (id, name), the row key must be spanner.Key{{id}, {name}} where {id} and {name} are the primary key values.

The column name is used to specify the column where the proto messages are stored. The column must be of type PROTO.

The method returns a slice of proto messages.

func (*Client) BatchReadRows added in v1.0.0 

func (s *Client) BatchReadRows(ctx context.Context, tableName string, rowKeys []spanner.Key, columns []string, opts *spanner.ReadOptions) ([]map[string]interface{}, error)

BatchReadRows reads multiple rows from the specified table using the provided row keys and column names.

The row keys are tuples of the row's primary keys values and are used to identify the rows to read. If the primary key is composite, the order of the keys must match the order of the primary key columns in the table schema. For example if the primary key is (id, name), the row key must be spanner.Key{{id}, {name}} where {id} and {name} are the primary key values.

The column names are used to specify which columns to read. The order of the columns does not matter.

The method returns a slice of maps where each map represents a row. The maps contain column names and their respective values. Note that the order of the rows in the result is not guaranteed to match the order of the row keys provided.

func (*Client) BatchUpdateRows added in v1.0.0 

func (s *Client) BatchUpdateRows(ctx context.Context, tableName string, rows []map[string]interface{}) error

BatchUpdateRows updates multiple rows in the specified table using the provided column values. If a row does not exist, the operation returns an error

The primary key value(s) must be included in each row.

The rows are represented as a slice of maps where each map represents a row. Each map contains column names and their respective values. The value types must match the column types in the table schema.

func (*Client) BatchUpsertRows added in v1.0.0 

func (s *Client) BatchUpsertRows(ctx context.Context, tableName string, rows []map[string]interface{}) error

BatchUpsertRows performs upserts for multiple rows into the specified table using the provided column values. If a row already exists, it will be updated with the new values. If a row does not exist, it will be inserted with the provided values.

The primary key value(s) must be included in each row.

The rows are represented as a slice of maps where each map represents a row. Each map contains column names and their respective values. The value types must match the column types in the table schema.

func (*Client) BatchWriteMutations added in v1.0.0 

func (s *Client) BatchWriteMutations(ctx context.Context, mutations []*spanner.Mutation) error

BatchWriteMutations writes the provided mutations to the database. This method provides a convenient way to write custom mutations to the database.

func (*Client) BatchWriteProtos added in v1.0.0 

func (s *Client) BatchWriteProtos(ctx context.Context, tableName string, rowKeys []spanner.Key, columnNames []string, messages []proto.Message) error

BatchWriteProtos writes multiple proto messages to the provided table.

The row keys are tuples of the rows' primary keys values and are used to identify the rows to write. The row keys must match the length of the messages and are a 1-to-1 mapping. Index i of the row keys corresponds to index i of the messages. The order of the keys must match the order of the primary key columns in the table schema. For example if the primary key is (id, name), the row key must be spanner.Key{{id}, {name}} where {id} and {name} are the primary key values.

The column names are used to specify the columns where the proto messages will be stored. The column names must match the length of the messages and are a 1-to-1 mapping. Index i of the column names corresponds to index i of the messages.

The proto messages will be serialized to bytes and stored in the specified columns. The columns must be of type PROTO.

func (*Client) Client added in v1.0.0 

func (s *Client) Client() *spanner.Client

Client returns the underlying spanner.Client instance. This client can be used to perform custom queries and mutations.

func (*Client) Close added in v1.0.0 

func (s *Client) Close()

Close closes the underlying spanner.Client instance.

func (*Client) DeleteRow added in v1.0.0 

func (s *Client) DeleteRow(ctx context.Context, tableName string, rowKey spanner.Key) error

DeleteRow deletes a row from the specified table using the provided row key.

func (*Client) InsertRow added in v1.0.0 

func (s *Client) InsertRow(ctx context.Context, tableName string, row map[string]interface{}) error

InsertRow inserts a row into the specified table using the provided column values.

The primary key value(s) must be included in the row.

The row is represented as a map where the key is the column name and the value is the column value. The value types must match the column types in the table schema.

func (*Client) ListProtos added in v1.0.0 

func (s *Client) ListProtos(ctx context.Context, tableName string, columnName string, message proto.Message, opts *ReadOptions) ([]proto.Message, string, error)

ListProtos lists all proto messages from the specified table using the provided column name.

The column name is used to specify the column where the proto messages are stored. The column must be of type PROTO.

The method returns a slice of proto messages. The second return value is the next page token which can be used to get the next page of results.

func (*Client) ListRows added in v1.0.0 

func (s *Client) ListRows(ctx context.Context, tableName string, columns []string, opts *spanner.ReadOptions) ([]map[string]interface{}, error)

ListRows reads all rows from the specified table using the provided column names.

The column names are used to specify which columns to read. The order of the columns does not matter.

The method returns a slice of maps where each map represents a row. The maps contain column names and their respective values.

func (*Client) PurgeRows added in v1.0.0 

func (s *Client) PurgeRows(ctx context.Context, tableName string) error

PurgeRows deletes all rows from the specified table.

func (*Client) QueryProtos added in v1.0.0 

func (s *Client) QueryProtos(ctx context.Context, tableName string, columnNames []string, messages []proto.Message, filter *spanner.Statement, opts *ReadOptions) ([]map[string]proto.Message, string, error)

QueryProtos reads multiple protos from the specified table using the provided column names and filtering condition.

The column names are used to specify the columns where the proto messages are stored. Each column name must have a corresponding proto message in the messages slice at the same index. Specified columns must be of type PROTO.

The filter is a SQL statement that is used to filter the rows to read. The statement should not include the WHERE keyword. The filter can include placeholders for parameters. The parameters are provided as a map where the key is the parameter name and the value is the parameter value. An example of a filter statement with parameters is "proto_column.name = @name" where "name" is the parameter name. Keep in mind that GoogleSQL uses parameters(@) whereas PostgreSQL uses placeholders($).

Opts can be used to specify sorting, limiting and offsetting conditions.

The method returns a slice of maps where each map represents a row. The maps contain column names and their respective values. The second return value is the next page token which can be used to get the next page of results.

func (*Client) QueryRows added in v1.0.0 

func (s *Client) QueryRows(ctx context.Context, tableName string, columns []string, filter *spanner.Statement, opts *ReadOptions) ([]map[string]interface{}, string, error)

QueryRows reads multiple rows from the specified table using the provided column names and filtering condition.

The column names are used to specify which columns to read. The order of the columns does not matter.

The filter is a SQL statement that is used to filter the rows to read. The statement should not include the WHERE keyword. The filter can include placeholders for parameters. The parameters are provided as a map where the key is the parameter name and the value is the parameter value. An example of a filter statement with parameters is "name = @name" where "name" is the parameter name. Keep in mind that GoogleSQL uses parameters(@) whereas PostgreSQL uses placeholders($).

Opts can be used to specify sorting, limiting and offsetting conditions.

The method returns a slice of maps where each map represents a row. The maps contain column names and their respective values. The second return value is the next page token which can be used to get the next page of results.

func (*Client) ReadProto added in v1.0.0 

func (s *Client) ReadProto(ctx context.Context, tableName string, rowKey spanner.Key, columnName string, message proto.Message, readMask *fieldmaskpb.FieldMask) error

ReadProto reads a proto message from the specified table using the provided row key and column name.

The row key is a tuple of the row's primary keys values and is used to identify the row to read. If the primary key is composite, the order of the keys must match the order of the primary key columns in the table schema. For example if the primary key is (id, name), the row key must be spanner.Key{{id}, {name}} where {id} and {name} are the primary key values.

The column name is used to specify the column where the proto message is stored.

func (*Client) ReadRow added in v1.0.0 

func (s *Client) ReadRow(ctx context.Context, tableName string, rowKey spanner.Key, columns []string, opts *spanner.ReadOptions) (map[string]interface{}, error)

ReadRow reads a row from the specified table using the provided row key and column names.

The row key is a tuple of the row's primary keys values and is used to identify the row to read. If the primary key is composite, the order of the keys must match the order of the primary key columns in the table schema. For example if the primary key is (id, name), the row key must be spanner.Key{{id}, {name}} where {id} and {name} are the primary key values.

The column names are used to specify which columns to read. The order of the columns does not matter.

The method returns a map of column names and their respective values.

func (*Client) StreamProtos added in v1.0.0 

func (s *Client) StreamProtos(ctx context.Context, tableName string, columnName string, message proto.Message, opts *spanner.ReadOptions) *StreamResponse[proto.Message]

StreamProtos streams proto messages from the specified table using the provided column name.

The column name is used to specify the column where the proto messages are stored. The column must be of type PROTO.

The method returns a StreamResponse[proto.Message] which can be used to iterate over the proto messages. Call Next() on the StreamResponse to get the next item from the stream. Remember to check for io.EOF to determine when the stream is closed.

func (*Client) StreamQueryProtos added in v1.0.0 

func (s *Client) StreamQueryProtos(ctx context.Context, tableName string, columnNames []string, messages []proto.Message, filter *spanner.Statement, opts *ReadOptions) *StreamResponse[map[string]proto.Message]

StreamQueryProtos streams proto messages from the specified table using the provided column names and filtering condition.

The column names are used to specify the columns where the proto messages are stored. Each column name must have a corresponding proto message in the messages slice at the same index. Specified columns must be of type PROTO.

The filter is a SQL statement that is used to filter the rows to read. The statement should not include the WHERE keyword. The filter can include placeholders for parameters. The parameters are provided as a map where the key is the parameter name and the value is the parameter value. An example of a filter statement with parameters is "proto_column.name = @name" where "name" is the parameter name. Keep in mind that GoogleSQL uses parameters(@) whereas PostgreSQL uses placeholders($).

Opts can be used to specify sorting, limiting and offsetting conditions.

The method returns a StreamResponse[map[string]proto.Message] which can be used to iterate over the proto messages. The keys of the map are the column names and the values are the proto messages. Call Next() on the StreamResponse to get the next item from the stream. Remember to check for io.EOF to determine when the stream is closed.

func (*Client) StreamRows added in v1.0.0 

func (s *Client) StreamRows(ctx context.Context, tableName string, columns []string, filter *spanner.Statement, opts *ReadOptions) (*StreamResponse[map[string]interface{}], error)

StreamRows reads multiple rows from the specified table using the provided column names and filtering condition.

The column names are used to specify which columns to read. The order of the columns does not matter.

The filter is a SQL statement that is used to filter the rows to read. The statement should not include the WHERE keyword. The filter can include placeholders for parameters. The parameters are provided as a map where the key is the parameter name and the value is the parameter value. An example of a filter statement with parameters is "name = @name" where "name" is the parameter name. Keep in mind that GoogleSQL uses parameters(@) whereas PostgreSQL uses placeholders($).

Opts can be used to specify sorting, limiting and offsetting conditions.

The method returns a StreamResponse that can be used to get the items from the stream. Call Next() on the StreamResponse to get the next item from the stream. Remember to check for io.EOF to determine when the stream is closed.

func (*Client) UpdateProto added in v1.0.0 

func (s *Client) UpdateProto(ctx context.Context, tableName string, rowKey spanner.Key, columnName string, message proto.Message, updateMask *fieldmaskpb.FieldMask) error

UpdateProto updates a proto message in the specified table using the provided row key and column name.

The row key is a tuple of the row's primary keys values and is used to identify the row to update. If the primary key is composite, the order of the keys must match the order of the primary key columns in the table schema. For example if the primary key is (id, name), the row key must be spanner.Key{{id}, {name}} where {id} and {name} are the primary key values.

The column name is used to specify the column where the proto message will be stored. This is still required even if it is included in the row key.

func (*Client) UpdateRow added in v1.0.0 

func (s *Client) UpdateRow(ctx context.Context, tableName string, row map[string]interface{}) error

UpdateRow updates a row in the specified table using the provided column values. If the row does not exist, the operation returns an error

The primary key value(s) must be included in the row.

The row is represented as a map where the key is the column name and the value is the column value. The value types must match the column types in the table schema.

func (*Client) UpsertRow added in v1.0.0 

func (s *Client) UpsertRow(ctx context.Context, tableName string, row map[string]interface{}) error

UpsertRow performs an upsert into the specified table using the provided column values. If the row already exists, it will be updated with the new values. If the row does not exist, it will be inserted with the provided values.

The primary key value(s) must be included in the row.

The row is represented as a map where the key is the column name and the value is the column value. The value types must match the column types in the table schema.

func (*Client) WriteProto added in v1.0.0 

func (s *Client) WriteProto(ctx context.Context, tableName string, rowKey spanner.Key, columnName string, message proto.Message) error

WriteProto writes a provided proto message to the provided table.

The row key is a tuple of the row's primary keys values and is used to identify the row to write. The order of the keys must match the order of the primary key columns in the table schema. For example if the primary key is (id, name), the row key must be spanner.Key{{id}, {name}} where {id} and {name} are the primary key values.

The column name is used to specify the column where the proto message will be stored. This is still required even if it is included in the row key.

The proto message will be stored as is in the specified column. The column's type must match the full message name including the proto package. See https://cloud.google.com/spanner/docs/reference/standard-sql/protocol-buffers

type DbClient added in v1.1.0 

type DbClient struct {
	// contains filtered or unexported fields
}

func NewDbClient added in v1.1.0 

func NewDbClient(googleProject, spannerInstance, databaseName, databaseRole string) (*DbClient, error)

NewClient creates a new Database Client instance with the provided Google Cloud Spanner configuration. Leave databaseRole empty if you are not using fine grained roles on the database.

func (*DbClient) NewResourceClient added in v1.2.0 

func (d *DbClient) NewResourceClient(tableName string, msg proto.Message, options *ResourceTblOptions) *ResourceClient

NewResourceClient creates a new ResourceClient for the given table name and resource message.

func (*DbClient) NewTableClient added in v1.1.0 

func (d *DbClient) NewTableClient(tableName string, defaultQueryRowLimit int, tableClientOptions ...TableClientOption) (*TableClient, error)

NewTableClient creates a new Table Client instance with the provided table name. During setup, it queries the table to get the primary key columns and the mapping of proto message types to columns. The defaultQueryRowLimit is used as the default limit for queries if not provided in the QueryOptions.

type ErrAlreadyExists added in v1.4.3 

type ErrAlreadyExists struct {
	// contains filtered or unexported fields
}

ErrAlreadyExists is returned when the desired resource already exists in Spanner.

func (ErrAlreadyExists) Error added in v1.4.3 

func (e ErrAlreadyExists) Error() string

func (ErrAlreadyExists) GRPCStatus added in v1.4.3 

func (e ErrAlreadyExists) GRPCStatus() *status.Status

func (ErrAlreadyExists) Is added in v1.4.3 

func (e ErrAlreadyExists) Is(target error) bool

type ErrInvalidArguments added in v1.0.0 

type ErrInvalidArguments struct {
	// contains filtered or unexported fields
}

ErrInvalidArguments is returned when the arguments are invalid.

func (ErrInvalidArguments) Error added in v1.0.0 

func (e ErrInvalidArguments) Error() string

func (ErrInvalidArguments) GRPCStatus added in v1.4.3 

func (e ErrInvalidArguments) GRPCStatus() *status.Status

func (ErrInvalidArguments) Is added in v1.0.1 

func (e ErrInvalidArguments) Is(target error) bool

type ErrInvalidPageToken added in v1.0.0 

type ErrInvalidPageToken struct {
	// contains filtered or unexported fields
}

ErrInvalidPageToken is returned when the page token is invalid.

func (ErrInvalidPageToken) Error added in v1.0.0 

func (e ErrInvalidPageToken) Error() string

func (ErrInvalidPageToken) GRPCStatus added in v1.4.3 

func (e ErrInvalidPageToken) GRPCStatus() *status.Status

func (ErrInvalidPageToken) Is added in v1.0.1 

func (e ErrInvalidPageToken) Is(target error) bool

type ErrMismatchedTypes 

type ErrMismatchedTypes struct {
	Expected reflect.Type
	Actual   reflect.Type
}

ErrMismatchedTypes is returned when the expected and actual types do not match.

func (ErrMismatchedTypes) Error 

func (e ErrMismatchedTypes) Error() string

func (ErrMismatchedTypes) GRPCStatus added in v1.4.3 

func (e ErrMismatchedTypes) GRPCStatus() *status.Status

func (ErrMismatchedTypes) Is added in v1.0.1 

func (e ErrMismatchedTypes) Is(target error) bool

type ErrNegativePageSize 

type ErrNegativePageSize struct{}

ErrNegativePageSize is returned when the page size is less than 0.

func (ErrNegativePageSize) Error 

func (e ErrNegativePageSize) Error() string

func (ErrNegativePageSize) GRPCStatus added in v1.4.3 

func (e ErrNegativePageSize) GRPCStatus() *status.Status

func (ErrNegativePageSize) Is added in v1.0.1 

func (e ErrNegativePageSize) Is(target error) bool

type ErrNotFound 

type ErrNotFound struct {
	RowKey string // unavailable locations
	// contains filtered or unexported fields
}

ErrNotFound is returned when the desired resource is not found in Spanner.

func (ErrNotFound) Error 

func (e ErrNotFound) Error() string

func (ErrNotFound) GRPCStatus added in v1.4.3 

func (e ErrNotFound) GRPCStatus() *status.Status

func (ErrNotFound) Is added in v1.0.1 

func (e ErrNotFound) Is(target error) bool

type QueryOptions added in v1.1.0 

type QueryOptions struct {
	// SortColumns is a map of column names and their respective sort order.
	SortColumns map[string]SortOrder
	// Limit is the maximum number of rows to read.
	Limit int32
	// PageToken is the token to get the next page of results.
	// This is typically retrieved from a previous response's next page token.
	// It's a base64 encoded string(base64.StdEncoding.EncodeToString(offset)) of the offset of the last row(s) read.
	PageToken string
	// Read masks for the proto messages
	ReadMasks []*fieldmaskpb.FieldMask
}

type ReadOptions 

type ReadOptions struct {
	// SortColumns is a map of column names and their respective sort order.
	SortColumns map[string]SortOrder
	// Limit is the maximum number of rows to read.
	Limit int32
	// PageToken is the token to get the next page of results.
	//
	// This is typically retrieved from a previous response's next page token.
	// It's a base64 encoded string(base64.StdEncoding.EncodeToString(offset)) of the offset of the last row(s) read.
	PageToken string
}

ReadOptions represents the options for reading rows from a table.

type ResourceClient added in v1.2.0 

type ResourceClient struct {
	RowKeyConv *RowKeyConverter
	// contains filtered or unexported fields
}

ResourceClient is a client for a resource table. It provides methods for creating, reading, updating, and deleting resources and policies.

func (*ResourceClient) BatchCreate added in v1.3.6 

func (rt *ResourceClient) BatchCreate(ctx context.Context, names []string, resources []proto.Message, policies []*iampb.Policy) ([]*ResourceRow, error)

BatchCreate inserts multiple resources in the database. If any of the resources already exist, the method will return an error.

func (*ResourceClient) BatchDelete added in v1.3.7 

func (rt *ResourceClient) BatchDelete(ctx context.Context, names []string) error

func (*ResourceClient) BatchRead added in v1.2.0 

func (rt *ResourceClient) BatchRead(ctx context.Context, names []string, fieldMaskPaths ...string) ([]*ResourceRow, []string, error)

Batch read resources. The names must be of the same resource type.

func (*ResourceClient) BatchUpdatePolicies added in v1.3.3 

func (rt *ResourceClient) BatchUpdatePolicies(ctx context.Context, rows []*ResourceRow, names ...string) error

Batch update policies. The rows must have the same resource type. Pass in names if the rows were retrieved from a list/query operation, meaning the keys are not set. No need for names from Read or BatchRead operations.

func (*ResourceClient) BatchUpdateResources added in v1.3.3 

func (rt *ResourceClient) BatchUpdateResources(ctx context.Context, rows []*ResourceRow, names ...string) error

Batch update resources. The rows must have the same resource type. Pass in names if the rows were retrieved from a list/query operation, meaning the keys are not set. No need for names from Read or BatchRead operations.

func (*ResourceClient) BatchWrite added in v1.6.1 

func (rt *ResourceClient) BatchWrite(ctx context.Context, names []string, resources []proto.Message, policies []*iampb.Policy) ([]*ResourceRow, error)

BatchWrite inserts or updates multiple resources in the database.

func (*ResourceClient) Client added in v1.4.2 

func (rt *ResourceClient) Client() *spanner.Client

Client returns the underlying spanner.Client instance. This client can be used to perform custom queries and mutations.

func (*ResourceClient) Create added in v1.2.0 

func (rt *ResourceClient) Create(ctx context.Context, name string, resource proto.Message, policy *iampb.Policy) (*ResourceRow, error)

Create inserts a resource in the database. If the resource already exists, the method will return an error.

func (*ResourceClient) List added in v1.2.0 

func (rt *ResourceClient) List(ctx context.Context, parent string, filter *spanner.Statement, opts *QueryOptions) ([]*ResourceRow, string, error)

func (*ResourceClient) Query added in v1.2.0 

func (rt *ResourceClient) Query(ctx context.Context, filter *spanner.Statement, opts *QueryOptions) ([]*ResourceRow, string, error)

func (*ResourceClient) Read added in v1.2.0 

func (rt *ResourceClient) Read(ctx context.Context, name string, fieldMaskPaths ...string) (*ResourceRow, error)

func (*ResourceClient) Stream added in v1.4.1 

func (rt *ResourceClient) Stream(ctx context.Context, parent string, opts *QueryOptions) (*StreamResponse[ResourceRow], error)

func (*ResourceClient) UpdatePolicy added in v1.2.3 

func (rt *ResourceClient) UpdatePolicy(ctx context.Context, name string, policy *iampb.Policy) error

func (*ResourceClient) Write added in v1.6.1 

func (rt *ResourceClient) Write(ctx context.Context, name string, resource proto.Message, policy *iampb.Policy) (*ResourceRow, error)

Write inserts or updates a resource in the database.

type ResourceRow added in v1.2.0 

type ResourceRow struct {
	// The row key of the resource
	RowKey string
	// The resource itself as a proto.Message. This can be cast to the appropriate message type.
	Resource proto.Message
	// The IAM policy for the resource. This will be nil if the resource does not have IAM policies.
	Policy *iampb.Policy
	// contains filtered or unexported fields
}

ResourceRow represents a row in a resource table. It contains the row key, the resource(proto.Message), and the policy(*iampb.Policy).

func (*ResourceRow) Delete added in v1.2.1 

func (rr *ResourceRow) Delete(ctx context.Context) error

Delete deletes the resource from the database.

func (*ResourceRow) Merge added in v1.2.4 

func (rr *ResourceRow) Merge(updatedMsg proto.Message, fieldMaskPaths ...string)

Merge merges the updatedMsg into the resource. The fieldMaskPaths are the paths of the fields to update.

func (*ResourceRow) SetRowKey added in v1.4.5 

func (rr *ResourceRow) SetRowKey(name string) error

Set the row key for the row. This is needed if a list/query/stream was run and any of the rows returned by the query needs to be updated/deleted.

func (*ResourceRow) Update added in v1.2.3 

func (rr *ResourceRow) Update(ctx context.Context) error

Update the resource in the database. Does not update the policy.

This method may return a ErrNotFound error if the row does not exist in the table.

type ResourceTblOptions added in v1.2.0 

type ResourceTblOptions struct {
	// whether the resource is a version, i.e. the name has the format .../versions/%d-%d-%d
	// If set, the conversion from the resource name to the row key will be such that
	// the latest version is returned first when doing a query (which orders keys lexicographically)
	IsVersion bool
	// The default limit for queries if not provided in QueryOptions. If not provided, 100 is used.
	DefaultLimit int
	// Whether this resource type has iam policies stored next to it. If true, the ResourceRow's policy field
	// will be populated with the policy for the resource when doing a read.
	HasIamPolicy bool
	// Whether to return permission denied for not found resources instead of not found error
	// when doing a read or delete operation.
	ReturnPermissionDeniedForNotFound bool
	// The name of the column that contains the row key in the table. If not provided, 'key' is used.
	KeyColumnName string
	// Whether the table only has standard columns, i.e.
	// - the primary key column called "key"
	// - a proto column with the same name as the last part of the proto message (e.g. "Time" for "google.protobuf.Time")
	// - a proto column with the name "Policy" for the google.iam.v1.Policy message
	// If true, startup would be faster since the columns do not need to be fetched from the database to setup the client.
	StandardColumnsOnly bool
	// If set, the resource name will not be shortened by using the first letter of each collection identifier.
	KeepFullCollectionIdentifiers bool
}

type Row added in v1.1.0 

type Row struct {
	//	Key is a tuple of the row's primary keys values and is used to identify the row to write.
	//	The order of the keys must match the order of the primary key columns in the table schema.
	//	For example if the primary key is (id, name), the row key must be spanner.Key{{id}, {name}} where {id} and {name} are the primary key values.
	Key spanner.Key
	// Messages is a list of proto messages to write to the row.
	// The provided messages must match the types of the PROTO columns in the table schema.
	Messages []proto.Message
}

Row represents a row in a table and messages for any PROTO columns.

type RowKeyConverter added in v1.2.0 

type RowKeyConverter struct {
	// If set, the resource name will be shortened by using the first letter of each collection identifier
	// E.g. /projects/{project}/instances/{instance}/databases/{database} -> /p/{project}/i/{instance}/d/{database}
	AbbreviateCollectionIdentifiers bool
	// If set, the version in the resource id will be converted to a number such that the latest version is shown first
	// when listed lexicographically (most common default ordering in databases like Bigtable and Spanner)
	LatestVersionFirst bool
}

func (*RowKeyConverter) GetRowKey added in v1.2.0 

func (r *RowKeyConverter) GetRowKey(resource string) (string, error)

func (*RowKeyConverter) GetRowKeyPrefix added in v1.2.0 

func (r *RowKeyConverter) GetRowKeyPrefix(parentResource string) (string, error)

type SortOrder 

type SortOrder int64

SortOrder represents the order of sorting. 

const (
	// SortOrderAsc sorts values in ascending order.
	SortOrderAsc SortOrder = iota
	// SortOrderDesc sorts values in descending order.
	SortOrderDesc
)

func (SortOrder) String 

func (s SortOrder) String() string

String returns the string representation of the SortOrder.

type StreamOptions added in v1.3.1 

type StreamOptions struct {
	// SortColumns is a map of column names and their respective sort order.
	SortColumns map[string]SortOrder
	// Limit is the maximum number of rows to read.
	Limit int32
	// Read masks for the proto messages
	ReadMasks []*fieldmaskpb.FieldMask
}

type StreamResponse 

type StreamResponse[T interface{}] struct {
	// contains filtered or unexported fields
}

StreamResponse is a response for a stream Call Next to get the next item from the stream

func NewStreamResponse 

func NewStreamResponse[T interface{}]() *StreamResponse[T]

NewStreamResponse creates a new StreamResponse

func (*StreamResponse[T]) Next 

func (r *StreamResponse[T]) Next() (*T, error)

Next gets the next item from the stream. It returns io.EOF when the stream is closed.

type TableClient added in v1.1.0 

type TableClient struct {
	// contains filtered or unexported fields
}

func (*TableClient) BatchCreate added in v1.2.0 

func (t *TableClient) BatchCreate(ctx context.Context, rows []*Row) error

BatchCreate creates multiple rows in the table with the provided row keys and proto messages.

This method may return a ErrInvalidArguments error if the row key length does not match the primary key columns length, or if the message type is not found in the table schema. It may also return a ErrAlreadyExists error if any of the rows already exist in the table.

func (*TableClient) BatchDelete added in v1.1.0 

func (t *TableClient) BatchDelete(ctx context.Context, rowKeys []spanner.Key) error

BatchDelete deletes multiple rows in the table with the provided row keys.

The row keys are tuples of the rows' primary keys values and are used to identify the rows to write. The row keys must match the length of the messages and are a 1-to-1 mapping. Index i of the row keys corresponds to index i of the messages. The order of the keys must match the order of the primary key columns in the table schema. For example if the primary key is (id, name), the row key must be spanner.Key{{id}, {name}} where {id} and {name} are the primary key values.

func (*TableClient) BatchRead added in v1.1.0 

func (t *TableClient) BatchRead(ctx context.Context, rowKeys []spanner.Key, messages ...proto.Message) ([]*Row, error)

BatchRead reads multiple rows along with the provided messages/columns

The row keys are tuples of the rows' primary keys values and are used to identify the rows to write. The row keys must match the length of the messages and are a 1-to-1 mapping. Index i of the row keys corresponds to index i of the messages. The order of the keys must match the order of the primary key columns in the table schema. For example if the primary key is (id, name), the row key must be spanner.Key{{id}, {name}} where {id} and {name} are the primary key values.

This method may return a ErrInvalidFieldMask if an invalid field mask is provided.

func (*TableClient) BatchReadWithFieldMask added in v1.1.4 

func (t *TableClient) BatchReadWithFieldMask(ctx context.Context, rowKeys []spanner.Key, messages []proto.Message, readMasks []*fieldmaskpb.FieldMask) ([]*Row, error)

BatchReadWithFieldMask reads multiple rows along with the provided messages/columns and applies the provided read masks.

The row keys are tuples of the rows' primary keys values and are used to identify the rows to write. The row keys must match the length of the messages and are a 1-to-1 mapping. Index i of the row keys corresponds to index i of the messages. The order of the keys must match the order of the primary key columns in the table schema. For example if the primary key is (id, name), the row key must be spanner.Key{{id}, {name}} where {id} and {name} are the primary key values.

The length of the read masks should match the length of messages and should be a 1-to-1 mapping. Index i of the read masks corresponds to index i of the messages.

This method may return a ErrInvalidFieldMask if an invalid field mask is provided.

func (*TableClient) BatchUpdate added in v1.2.0 

func (t *TableClient) BatchUpdate(ctx context.Context, rows []*Row) error

BatchUpdate updates multiple rows in the table with the provided row keys and proto messages.

This method may return a ErrInvalidArguments error if the row key length does not match the primary key columns length, or if the message type is not found in the table schema. It may also return a ErrNotFound error if any of the rows do not exist in the table.

func (*TableClient) BatchWrite added in v1.1.0 

func (t *TableClient) BatchWrite(ctx context.Context, rows []*Row) error

BatchWrite writes multiple rows in the table with the provided row keys and proto messages. The main difference between BatchWrite and BatchCreate is that BatchWrite will update the rows if they already exist, else create new rows.

This method may return a ErrInvalidArguments error if the row key length does not match the primary key columns length, or if the message type is not found in the table schema.

func (*TableClient) Client added in v1.4.2 

func (t *TableClient) Client() *spanner.Client

Client returns the underlying spanner.Client instance. This client can be used to perform custom queries and mutations.

func (*TableClient) Create added in v1.2.0 

func (t *TableClient) Create(ctx context.Context, rowKey spanner.Key, messages ...proto.Message) error

Create creates a new row in the table with the provided row key and proto messages.

The row key is a tuple of the row's primary keys values and is used to identify the row to write. The order of the keys must match the order of the primary key columns in the table schema. For example if the primary key is (id, name), the row key must be spanner.Key{{id}, {name}} where {id} and {name} are the primary key values.

This method may return a ErrInvalidArguments error if the row key length does not match the primary key columns length, or if the message type is not found in the table schema. It may also return a ErrAlreadyExists error if the row already exists in the table.

func (*TableClient) Delete added in v1.1.0 

func (t *TableClient) Delete(ctx context.Context, rowKey spanner.Key) error

Delete deletes a row in the table with the provided row key.

The row key is a tuple of the row's primary keys values and is used to identify the row to write. The order of the keys must match the order of the primary key columns in the table schema. For example if the primary key is (id, name), the row key must be spanner.Key{{id}, {name}} where {id} and {name} are the primary key values.

func (*TableClient) Query added in v1.1.0 

func (t *TableClient) Query(ctx context.Context, messages []proto.Message, filter *spanner.Statement, opts *QueryOptions) ([]*Row, string, error)

Query queries the table with the provided filter and options and return a list of rows along with the next page token.

This method may return a ErrInvalidPageToken error if the provided page token is invalid. It may also return a ErrInvalidFieldMask error if an invalid field mask is provided.

func (*TableClient) Read added in v1.1.0 

func (t *TableClient) Read(ctx context.Context, rowKey spanner.Key, messages ...proto.Message) error

Read reads a single row along with the provided messages/columns

The row key is a tuple of the row's primary keys values and is used to identify the row to write. The order of the keys must match the order of the primary key columns in the table schema. For example if the primary key is (id, name), the row key must be spanner.Key{{id}, {name}} where {id} and {name} are the primary key values.

This method may return a ErrNotFound error if the row does not exist in the table.

func (*TableClient) ReadWithFieldMask added in v1.1.4 

func (t *TableClient) ReadWithFieldMask(ctx context.Context, rowKey spanner.Key, messages []proto.Message, readMasks []*fieldmaskpb.FieldMask) error

ReadWithFieldMask reads a single row along with the provided messages/columns and applies the provided read masks.

The row key is a tuple of the row's primary keys values and is used to identify the row to write. The order of the keys must match the order of the primary key columns in the table schema. For example if the primary key is (id, name), the row key must be spanner.Key{{id}, {name}} where {id} and {name} are the primary key values.

The length of the read masks should match the length of messages and should be a 1-to-1 mapping. Index i of the read masks corresponds to index i of the messages.

This method may return a ErrNotFound error if the row does not exist in the table. It may also return a ErrInvalidFieldMask if an invalid field mask is provided

func (*TableClient) Stream added in v1.3.1 

func (t *TableClient) Stream(ctx context.Context, messages []proto.Message, filter *spanner.Statement, opts *StreamOptions) (*StreamResponse[Row], error)

Stream queries the table with the provided filter and options and return a stream of rows

This method may return a ErrInvalidFieldMask error if an invalid field mask is provided.

func (*TableClient) Update added in v1.2.0 

func (t *TableClient) Update(ctx context.Context, rowKey spanner.Key, messages ...proto.Message) error

Update updates a row in the table with the provided row key and proto messages.

The row key is a tuple of the row's primary keys values and is used to identify the row to write. The order of the keys must match the order of the primary key columns in the table schema. For example if the primary key is (id, name), the row key must be spanner.Key{{id}, {name}} where {id} and {name} are the primary key values.

This method may return a ErrNotFound error if the row does not exist in the table.

func (*TableClient) Write added in v1.1.0 

func (t *TableClient) Write(ctx context.Context, rowKey spanner.Key, messages ...proto.Message) error

Write writes a row in the table with the provided row key and proto messages. The main difference between Write and Create is that Write will update the row if it already exists, else create a new row.

The row key is a tuple of the row's primary keys values and is used to identify the row to write. The order of the keys must match the order of the primary key columns in the table schema. For example if the primary key is (id, name), the row key must be spanner.Key{{id}, {name}} where {id} and {name} are the primary key values.

This method may return a ErrInvalidArguments error if the row key length does not match the primary key columns length, or if the message type is not found in the table schema.

type TableClientOption added in v1.5.1 

type TableClientOption func(*TableClientOptions)

func WithMsgTypeToColumnMap added in v1.5.1 

func WithMsgTypeToColumnMap(msgTypeToColumn map[string]string) TableClientOption

func WithPrimaryKeyColumns added in v1.5.1 

func WithPrimaryKeyColumns(pkCols []*primaryKeyColumn) TableClientOption

type TableClientOptions added in v1.5.1 

type TableClientOptions struct {
	// contains filtered or unexported fields
}

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.