Home

Awesome

An emulator for Cloud Spanner

Install

go get github.com/gcpug/handy-spanner/cmd/handy-spanner

NOTE: If you want to use some features (e.g. array literal [] in DML), require "json1" build tag. The Spanner emulator uses sqlite3 internally. You may need to build go-sqlite3 explicitly. It also requires cgo to use sqlite3.

go get -u github.com/mattn/go-sqlite3
go install github.com/mattn/go-sqlite3

Usage

Run as an independent process

./handy-spanner

or

docker run --rm -it -p 9999:9999 handy-spanner

It runs a hand-spanner server as a process. It serves spanner gRPC server by port 9999 by default.

Access to the server

The google-cloud-go, the official Spanner SDK, supports to access an emulator server. Set the address to an emulator server to environment variable SPANNER_EMULATOR_HOST, then google-cloud-go transparently use the server in the client.

So if you want to replace spanner server with the handy-spanner you run, just do:

export SPANNER_EMULATOR_HOST=localhost:9999

Schema setup

The handy-spanner server has no databases nor tables by default. You need to create them by yourself. You can prepare them at startup.

handy-spanner accepts some command-line arguments to prepare schema.

If you prepare schema at startup, these 4 arguments are required.

Implicit creation of databases

Without schema setup, databases are created automatically by your database access.

handy-spanner creates a database when a session to the database is created. In detail, when CreateSession or BatchCreateSessions is called, the accessed database is created.

Database operations

You can also operate databases by your applications. If you need additional databases or database alterations, you need to follow this section.

As Cloud Spanner supports, there are dedicated gRPC service for instance and database operations for Spanner.

handy-spanner also supports these gRPC services so that you can operate databases. The gRPC services are provided in the same address to the normal gRPC service. It means it is provided in localhost:9999 by default.

It seems most clients for each language for these gRPC services provided Google Cloud Platform dont support SPANNER_EMULATOR_HOST to connect an emulator server, so you need to setup a client to connect an emulator server explicitly. For Go, you can refer examples to connect an emulator server.

Run as a buillt-in server in Go

If you use a handy-spanner server in tests in Go, it's easier to run it in a process. See an example for the details.

Note that the tests highly depend on handhy-spanner, which means you cannot switch the backend depending on the situation. If you want to test on both Cloud Spanner and handy-spanner, it's better to use a handy-spanner server as an independent process.

Database operations

handy-spanner provides utility functions to operate databases. For the detail, please refer examples.

You can also operate databases or instances as Cloud Spanner supports. Please also refer Run as an independent process section.

Can and Cannot

Supported features

Not supported features

Implementation

Transaction simulation

handy-spanner uses sqlite3 in Shared-Cache Mode. There is a characteristic in the trasactions.

If we simply use the transactions, dead lock should happen in read and write locks. To simulate spanner transactions correctly as possible, handy-spanner manages sqlite3 transactions inside.

abort abort

DML

Because of transaction limitations, DML also has limitations.

When a transaction(A) updates a table, other transactions cannot read/write the table until the transaction(A) commits. This limitation may become an inconsistency to the Cloud Spanner. Other limitations are same to mutations with commit.

block

Feature Request and Bug Report

Feature requests and any bug reports are welcome.

There are many things to implement features and make better compatibility to Cloud Spanner. Now I'm prioritizing features by on-demand from users and me. Please create an issue if you find lack of a feature to use handy-spanner or imcompatibility to Cloud Spanner.

Feature request

Please describe what feature you want. It's the best to refer a Cloud Spanner's document for the feature. If the feature is partiality implemented or wrong behavior you expected, please also see a Bug Report section.

Bug report

Please describe a reproducable conditions. If you describe more information about the bug, it makes more easir to fix the bug.

Copyright