emulator

Documentation

Overview

Package emulator knows how to launch Cloud Spanner emulator.

It uses a bunch of strategies to run it, depending on the host environment and `CLOUD_SPANNER_EMULATOR_DRIVER` env var.

On Linux by default it would launch the emulator binary directly, by finding it through `gcloud`.

On other OSes it will run it as a container either through Docker (default) or Podman (if `docker` is absent).

In all cases `CLOUD_SPANNER_EMULATOR_DRIVER` can be used to override the default behavior:

• "gcloud": try to find the emulator binary on the host via `gcloud`.
• "docker": use `docker run ...` to run the container with the emulator.
• "podman": use `podman run ...` to run the container with the emulator.

The emulator's gRPC socket will be bound to an available localhost port (different each time, picked by the OS), which is useful when running many tests in parallel.

Only the gRPC port is exposed. The REST port is not exposed (and as a consequence, emulators started this way can't be accessed via gcloud spanner subcommands): unfortunately, when using "gcloud" method, there's no way to simultaneously support the REST port and have it be bound to an available TCP port. Looks like the REST port is exposed by some `gateway` binary, not by the spanner emulator binary itself. This is orchestrated by "gcloud emulators spanner start" command that launches the actual emulator and also the gRPC => REST gateway. Unlike the actual spanner emulator, this wrapper **requires** ports to be given in advance. There were attempts to workaround that by attempting to pick the random port in advance and then "very quickly" pass it to "gcloud emulators spanner start". This approach was unreliable and caused lots of flakiness in the tests.

Note that when running the emulator as a container, this is not a problem, since the host port assignment is done by the containerization engine and it doesn't care that ports inside the container are predefined. But for compatibility with "gcloud" driver (the primary one), the REST port is not exposed at all.

Since nothing in the tests seems to rely on the REST port (the Go Cloud Spanner library uses gRPC API exclusively), it's absence is not a big issue in practice.

Index

• type Emulator
  • func Start(ctx context.Context) (emu *Emulator, err error)
  • func (e *Emulator) ClientOptions() []option.ClientOption
  • func (e *Emulator) GrpcAddr() string
  • func (e *Emulator) Stop()

Types

type Emulator

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

Emulator is a running Cloud Spanner emulator.

func Start

func Start(ctx context.Context) (emu *Emulator, err error)

Start starts a new empty Cloud Spanner emulator instance.

Its gRPC serving port will be bound to some OS-assigned localhost port. The exact endpoint address will be available via [GrpcAddr].

Emulator's output (both stdout and stderr) is logged into the active LUCI logger in the context at Info severity.

func (*Emulator) ClientOptions

func (e *Emulator) ClientOptions() []option.ClientOption

ClientOptions returns a bundle of options to pass to the Cloud Spanner client to tell it to connect to the emulator.

func (*Emulator) GrpcAddr

func (e *Emulator) GrpcAddr() string

GrpcAddr is the "127.0.0.1:<port>" address with the Cloud Spanner gRPC port.

func (*Emulator) Stop

func (e *Emulator) Stop()

Stop terminates the emulator process, wiping its state.