spannertest

README

This directory contains spannertest, an in-memory fake Cloud Spanner. A sibling directory, spansql, contains types and parser for the Cloud Spanner SQL dialect.

spansql is reusable for anything that interacts with Cloud Spanner on a syntactic basis, such as tools for handling Spanner schema (DDL).

spannertest builds on spansql for testing code that uses Cloud Spanner client libraries.

Neither of these packages aims to be performant nor exact replicas of the production Cloud Spanner. They are reasonable for building tools, or writing unit or integration tests. Full-scale performance testing or serious workloads should use the production Cloud Spanner instead.

See INTERNALS.md for an explanation of the implementation.

Here's a list of features that are missing or incomplete. It is roughly ordered by ascending esotericism:

• expression functions
• NUMERIC
• JSON
• more aggregation functions
• SELECT HAVING
• more literal types
• DEFAULT
• expressions that return null for generated columns
• generated columns referencing other generated columns
• checking dependencies on a generated column before deleting a column
• expression type casting, coercion
• multiple joins
• subselects
• case insensitivity of table and column names and query aliases
• transaction simulation
• FOREIGN KEY and CHECK constraints
• set operations (UNION, INTERSECT, EXCEPT)
• STRUCT types
• partition support
• conditional expressions
• table sampling (implementation)

Documentation

Overview

Package spannertest contains test helpers for working with Cloud Spanner.

This package is EXPERIMENTAL, and is lacking several features. See the README.md file in this directory for more details.

In-memory fake

This package has an in-memory fake implementation of spanner. To use it, create a Server, and then connect to it with no security:

srv, err := spannertest.NewServer("localhost:0")
...
conn, err := grpc.DialContext(ctx, srv.Addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
...
client, err := spanner.NewClient(ctx, db, option.WithGRPCConn(conn))
...

Alternatively, create a Server, then set the SPANNER_EMULATOR_HOST environment variable and use the regular spanner.NewClient:

srv, err := spannertest.NewServer("localhost:0")
...
os.Setenv("SPANNER_EMULATOR_HOST", srv.Addr)
client, err := spanner.NewClient(ctx, db)
...

The same server also supports database admin operations for use with the cloud.google.com/go/spanner/admin/database/apiv1 package. This only simulates the existence of a single database; its name is ignored.

Index

• type Logger
• type Server
  • func NewServer(laddr string) (*Server, error)
  • func (s *Server) Close()
  • func (s *Server) SetLogger(l Logger)
  • func (s *Server) UpdateDDL(ddl *spansql.DDL) error

Types

type Logger

type Logger func(format string, args ...interface{})

Logger is something that can be used for logging. It is matched by log.Printf and testing.T.Logf.

type Server

type Server struct {
	Addr string
	// contains filtered or unexported fields
}

Server is an in-memory Cloud Spanner fake. It is unauthenticated, non-performant, and only a rough approximation.

func NewServer

func NewServer(laddr string) (*Server, error)

NewServer creates a new Server. The Server will be listening for gRPC connections, without TLS, on the provided TCP address. The resolved address is available in the Addr field.

func (*Server) Close

func (s *Server) Close()

Close shuts down the server.

func (*Server) SetLogger

func (s *Server) SetLogger(l Logger)

SetLogger sets a logger for the server. You can use a *testing.T as this argument to collate extra information from the execution of the server.

func (*Server) UpdateDDL

func (s *Server) UpdateDDL(ddl *spansql.DDL) error

UpdateDDL applies the given DDL to the server.

This is a convenience method for tests that may assume an existing schema. The more general approach is to dial this server using an admin client, and use the UpdateDatabaseDdl RPC method.