Help us shape the future of Go! Take the 2026 Go Developer Survey

gcpspanner

package
v1.9.0 Latest Latest
Warning

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

 Go to latest Published: Oct 27, 2026 License: MIT Imports: 48 Imported by: 0

README

Cloud Spanner

Parity grade: B · SDK cloud.google.com/go/spanner@v1.96.1 · last audited 2026-10-22 (364908f83)

Coverage

Metric Value
PARITY entries audited 18 (17 ok, 1 partial)
Feature families 4 (1 ok, 3 partial)
Known gaps 6
Deferred items 0
Resource leaks clean
Known gaps
  • Table data is in the emulator's memory only: it is lost on restart. Persistence stores instances, policies, databases and their DDL, and replays the schema into a fresh emulator on first use.
  • Without a container runtime database DDL is stored but not validated or executed: GetDatabaseDdl returns the statements as submitted, DROP and ALTER statements are not folded in.
  • RestoreDatabase and ListDatabaseOperations are UNIMPLEMENTED: restoring would create emulator databases the backend does not track. Backups created through the proxy live only in the emulator and are lost on restart.
  • User-managed instance configs (Create/Update/DeleteInstanceConfig), instance partitions, MoveInstance, autoscaling_config, replica_compute_capacity and the ListInstances filter are not implemented.
  • The emulator runs every instance in its single emulator-config with 1 node; node_count and processing_units are metadata only, and the data plane is one shared emulator process.
  • Customer-managed encryption on databases is UNIMPLEMENTED; backend instance and database create_time values are not shared with the emulator.

More

Documentation

Index

Constants

View Source 
const (
	// DefaultPort is the dedicated gRPC and REST listener's default TCP port.
	DefaultPort = 8135
	// EngineAuto runs the Cloud Spanner emulator container when a container runtime is reachable.
	EngineAuto = "auto"
	// EngineNone never starts a container: instances and databases are metadata only.
	EngineNone = "none"
	// DefaultImage is the pinned Google Cloud Spanner emulator image.
	DefaultImage = "gcr.io/cloud-spanner-emulator/emulator:1.5.40"
	// DefaultStartupTimeout bounds how long the emulator may take to pull its image and accept calls.
	DefaultStartupTimeout = 5 * time.Minute
)

Variables

View Source 
var ErrNilAppContext = errors.New("gcpspanner: nil app context")

ErrNilAppContext is returned when Init is called with a nil AppContext.

View Source 
var (

	// ErrRuntimeUnavailable is returned by a launcher when no container runtime can be reached.
	ErrRuntimeUnavailable = errors.New("container runtime unavailable")
)

Functions

This section is empty.

Types

type API 

type API struct {
	Instances instancepb.InstanceAdminServer
	Databases databasepb.DatabaseAdminServer
}

API groups the Spanner admin services for in-process callers (dashboard proxy).

type ConfigProvider 

type ConfigProvider interface {
	GetGCPSpannerSettings() Settings
}

ConfigProvider extracts Cloud Spanner configuration from the AppContext Config.

type Handler 

type Handler struct {
	Backend *InMemoryBackend

	Port int
	// contains filtered or unexported fields
}

Handler serves the Cloud Spanner instance and database admin APIs and, through the emulator, the data plane on a dedicated gRPC and REST listener.

func NewHandler 

func NewHandler(backend *InMemoryBackend) *Handler

NewHandler creates a Handler; callers override Port from Settings.

func (*Handler) API 

func (h *Handler) API() *API

API exposes the instance and database admin services.

func (*Handler) Addr 

func (h *Handler) Addr() string

Addr returns the bound listener address, or "" before StartWorker.

func (*Handler) ExtractOperation 

func (h *Handler) ExtractOperation(*echo.Context) string

ExtractOperation is unused: requests never reach the shared router.

func (*Handler) ExtractResource 

func (h *Handler) ExtractResource(*echo.Context) string

ExtractResource is unused: requests never reach the shared router.

func (*Handler) GetSupportedOperations 

func (h *Handler) GetSupportedOperations() []string

GetSupportedOperations lists the operations the backend answers itself; every other Spanner and DatabaseAdmin method is proxied to the emulator.

func (*Handler) Handler 

func (h *Handler) Handler() echo.HandlerFunc

Handler returns a 404 handler; the real API is on the dedicated port.

func (*Handler) MatchPriority 

func (h *Handler) MatchPriority() int

MatchPriority is irrelevant because RouteMatcher never matches.

func (*Handler) Name 

func (h *Handler) Name() string

Name returns the service name.

func (*Handler) Reset 

func (h *Handler) Reset()

Reset clears all state and stops the emulator.

func (*Handler) Restore 

func (h *Handler) Restore(ctx context.Context, data []byte) error

Restore implements persistence.Persistable by delegating to the backend.

func (*Handler) RouteMatcher 

func (h *Handler) RouteMatcher() service.Matcher

RouteMatcher never matches: Cloud Spanner runs on its own listener.

func (*Handler) Shutdown 

func (h *Handler) Shutdown(ctx context.Context)

Shutdown stops the listener and the emulator, forcing a close after a short grace period.

func (*Handler) Snapshot 

func (h *Handler) Snapshot(ctx context.Context) []byte

Snapshot implements persistence.Persistable by delegating to the backend.

func (*Handler) StartWorker 

func (h *Handler) StartWorker(ctx context.Context) error

StartWorker binds the dedicated listener synchronously so a port conflict is returned to the caller.

type InMemoryBackend 

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

InMemoryBackend holds all Cloud Spanner admin state under one lock. The data plane lives in the emulator.

func NewInMemoryBackend 

func NewInMemoryBackend() *InMemoryBackend

NewInMemoryBackend creates an empty backend with no data plane; see SetLauncher.

func (*InMemoryBackend) Close 

func (b *InMemoryBackend) Close()

Close stops the emulator and waits for background work.

func (*InMemoryBackend) CreateDatabase 

func (b *InMemoryBackend) CreateDatabase(
	ctx context.Context, in *databasepb.CreateDatabaseRequest,
) (*longrunningpb.Operation, error)

CreateDatabase creates a database, executing its DDL in the emulator when one is available.

func (*InMemoryBackend) CreateInstance 

func (b *InMemoryBackend) CreateInstance(in *instancepb.CreateInstanceRequest) (*longrunningpb.Operation, error)

CreateInstance starts creating an instance; the operation completes once the data plane has it too.

func (*InMemoryBackend) DeleteInstance 

func (b *InMemoryBackend) DeleteInstance(name string) (*emptypb.Empty, error)

DeleteInstance deletes an instance together with its databases.

func (*InMemoryBackend) DropDatabase 

func (b *InMemoryBackend) DropDatabase(ctx context.Context, name string) (*emptypb.Empty, error)

DropDatabase deletes a database unless drop protection is on.

func (*InMemoryBackend) GetDatabase 

func (b *InMemoryBackend) GetDatabase(name string) (*databasepb.Database, error)

GetDatabase returns a database.

func (*InMemoryBackend) GetDatabaseDdl 

func (b *InMemoryBackend) GetDatabaseDdl(name string) (*databasepb.GetDatabaseDdlResponse, error)

GetDatabaseDdl returns the DDL statements of a database.

func (*InMemoryBackend) GetIamPolicy 

func (b *InMemoryBackend) GetIamPolicy(resource string, version int32) (*iampb.Policy, error)

GetIamPolicy returns the policy of an instance at the requested version.

func (*InMemoryBackend) GetInstance 

func (b *InMemoryBackend) GetInstance(name string) (*instancepb.Instance, error)

GetInstance returns an instance.

func (*InMemoryBackend) GetInstanceConfig 

func (b *InMemoryBackend) GetInstanceConfig(name string) (*instancepb.InstanceConfig, error)

GetInstanceConfig returns one configuration.

func (*InMemoryBackend) ListDatabases 

func (b *InMemoryBackend) ListDatabases(
	in *databasepb.ListDatabasesRequest,
) (*databasepb.ListDatabasesResponse, error)

ListDatabases lists the databases of an instance.

func (*InMemoryBackend) ListInstanceConfigs 

func (b *InMemoryBackend) ListInstanceConfigs(
	in *instancepb.ListInstanceConfigsRequest,
) (*instancepb.ListInstanceConfigsResponse, error)

ListInstanceConfigs lists the Google-managed configurations of a project.

func (*InMemoryBackend) ListInstances 

func (b *InMemoryBackend) ListInstances(
	in *instancepb.ListInstancesRequest,
) (*instancepb.ListInstancesResponse, error)

ListInstances lists the instances of a project.

func (*InMemoryBackend) Reset 

func (b *InMemoryBackend) Reset()

Reset stops the emulator and clears all state.

func (*InMemoryBackend) Restore 

func (b *InMemoryBackend) Restore(ctx context.Context, data []byte) error

Restore loads a snapshot. Instances caught mid-creation are dropped; the emulator starts empty on first use and is rebuilt from the restored schema.

func (*InMemoryBackend) SetIamPolicy 

func (b *InMemoryBackend) SetIamPolicy(in *iampb.SetIamPolicyRequest) (*iampb.Policy, error)

SetIamPolicy replaces the policy of an instance; a stale etag aborts the call.

func (*InMemoryBackend) SetLauncher 

func (b *InMemoryBackend) SetLauncher(l launcher)

SetLauncher connects the data plane to an emulator launcher; nil leaves the backend metadata only.

func (*InMemoryBackend) Snapshot 

func (b *InMemoryBackend) Snapshot(ctx context.Context) []byte

Snapshot serialises instances, policies, databases and their DDL. Table data lives in the emulator and is not persisted: it is lost on restart, while the schema is replayed into a fresh emulator.

func (*InMemoryBackend) TestIamPermissions 

func (b *InMemoryBackend) TestIamPermissions(
	in *iampb.TestIamPermissionsRequest,
) (*iampb.TestIamPermissionsResponse, error)

TestIamPermissions reports the requested Spanner permissions as granted: the emulator authorises all callers.

func (*InMemoryBackend) UpdateDatabase 

func (b *InMemoryBackend) UpdateDatabase(in *databasepb.UpdateDatabaseRequest) (*longrunningpb.Operation, error)

UpdateDatabase updates enable_drop_protection, the only mutable database field.

func (*InMemoryBackend) UpdateDatabaseDdl 

func (b *InMemoryBackend) UpdateDatabaseDdl(
	ctx context.Context, in *databasepb.UpdateDatabaseDdlRequest,
) (*longrunningpb.Operation, error)

UpdateDatabaseDdl applies DDL statements, in the emulator when one is available.

func (*InMemoryBackend) UpdateInstance 

func (b *InMemoryBackend) UpdateInstance(in *instancepb.UpdateInstanceRequest) (*longrunningpb.Operation, error)

UpdateInstance applies the masked fields of the instance.

type Provider 

type Provider struct{}

Provider implements service.Provider for Google Cloud Spanner. It serves gRPC and REST on its own listener (see Handler.StartWorker) and never matches on the shared AWS router.

func (*Provider) Init 

func (p *Provider) Init(ctx *service.AppContext) (service.Registerable, error)

Init creates the backend and handler; the port is bound in StartWorker.

func (*Provider) Name 

func (p *Provider) Name() string

Name returns the service provider name.

type Settings 

type Settings struct {
	Engine string `` //nolint:lll // config struct tags are intentionally verbose
	/* 267-byte string literal not displayed */
	Image string `` //nolint:lll // config struct tags are intentionally verbose
	/* 228-byte string literal not displayed */
	Port int `` //nolint:lll // config struct tags are intentionally verbose
	/* 265-byte string literal not displayed */
	StartupTimeout time.Duration `` //nolint:lll // config struct tags are intentionally verbose
	/* 235-byte string literal not displayed */
}

Settings holds service-level configuration, embedded in the root CLI command as CLI.GCPSpanner.

func DefaultSettings 

func DefaultSettings() Settings

DefaultSettings returns the settings used when no ConfigProvider is available.

Source Files

View all Source files

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.