Cloudspannerecosystem Yo Save

yo is a command-line tool to generate Go code for Google Cloud Spanner.

Project README


yo is a command-line tool to generate Go code for Google Cloud Spanner, forked from xo :rose:.

yo uses database schema to generate code by using Information Schema. yo runs SQL queries against tables in INFORMATION_SCHEMA to fetch metadata for a database, and applies the metadata to Go templates to generate code/models to access Cloud Spanner.

Please feel free to report issues and send pull requests, but note that this application is not officially supported as part of the Cloud Spanner product.


$ go get -u


The following is a quick overview of using yo on the command-line:

# change to project directory
$ cd $GOPATH/src/path/to/project

# make an output directory
$ mkdir -p models

# generate code for a schema

Command line options

The following are yo's command-line arguments and options:

$ yo --help
yo is a command-line tool to generate Go code for Google Cloud Spanner.


  # Generate models under models directory

  # Generate models under models directory with custom types
  yo $SPANNER_PROJECT_NAME $SPANNER_INSTANCE_NAME $SPANNER_DATABASE_NAME -o models --custom-types-file custom_column_types.yml

      --custom-type-package string   Go package name to use for custom or unknown types
      --custom-types-file string     custom table field type definition file
  -h, --help                         help for yo
      --ignore-fields stringArray    fields to exclude from the generated Go code types
      --ignore-tables stringArray    tables to exclude from the generated Go code types
      --inflection-rule-file string  custom inflection rule file
  -o, --out string                   output path or file name
  -p, --package string               package name used in generated Go code
      --single-file                  toggle single file output
      --suffix string                output file suffix (default ".yo.go")
      --tags string                  build tags to add to package header
      --template-path string         user supplied template path

Generated code

yo generates 1 file per table by default. Each file has struct, metadata and methods for that table.


From this table definition:


This struct is generated:

type Example struct {
	PKey      string    `spanner:"PKey" json:"PKey"`           // PKey
	Num       int64     `spanner:"Num" json:"Num"`             // Num
	CreatedAt time.Time `spanner:"CreatedAt" json:"CreatedAt"` // CreatedAt

Mutation methods

An operation against a table is represented as mutation in Cloud Spanner. yo generates methods to create mutations to modify a table.

  • Insert
    • A wrapper method of spanner.Insert, which embeds struct values implicitly to insert a new record with struct values.
  • Update
    • A wrapper method of spanner.Update, which embeds struct values implicitly to update all columns into struct values.
  • InsertOrUpdate
    • A wrapper method of spanner.InsertOrUpdate, which embeds struct values implicitly to insert a new record or update all columns to struct values.
  • UpdateColumns
    • A wrapper method of spanner.Update, which updates specified columns into struct values.

Read functions

yo generates functions to read data from Cloud Spanner. The functions are generated based on index.

Naming convention of generated functions is FindXXXByYYY. The XXX is table name and YYY is index name. XXX will be singular if the index is unique index, or plural if the index is not unique.


  • Generated functions use Query only even if it is secondary index. Need a function to use Read.

Error handling

yo wraps all errors as internal yoError. It has some methods for error handling.

  • GRPCStatus()
    • This returns gRPC's *status.Status. It is intended by used from status package.
  • DBTableName()
    • A table name where the error happens.
  • NotFound()
    • A helper to check the error is NotFound.

The yoError inherits an original error from google-cloud-go. It can still be used with status.FromError or status.Code to check status code of the error. So the typical error handling will be like:

result, err := SomeFunction()
if err != nil {
	code := status.Code(err)
	if code == codes.InvalidArgument {
		// error handling for invalid argument

Templates for code generation

yo uses Go template package to generate code. You can use your own template for code generation by using --template-path option.

yo provides default templates and uses them when --template-path option is not specified. The templates exist in templates directory. The templates are embedded into yo binary.

Custom Template Quickstart

The following is a quick overview of copying the base templates contained in the yo project's templates/ directory, editing to suit, and using with yo:

# change to working project directory
$ cd $GOPATH/src/path/to/my/project

# create a template directory
$ mkdir -p templates

# copy yo templates
$ cp "$GOPATH/src/*" templates/

# remove yo binary data
$ rm templates/*.go

# edit base templates
$ vi templates/*.tpl.go

# use with yo

See the Custom Template example below for more information on adapting the base templates in the yo source tree for use within your own project.

Template files

Template File Description
templates/type.go.tpl Template for schema tables
templates/index.go.tpl Template for schema indexes
templates/yo_db.go.tpl Package level template generated once per package
templates/yo_package.go.tpl File header template generated once per file

Helper functions

This is not a stable feature

yo provides some helper functions which can be used in templates. Those are defined in generator/funcs.go. Those are not well documented and are likely to change.

Custom inflection rule file

yo use inflection to convert singular or plural name each other. If you want to add own rule, add --inflection-rule-file option with rule yaml file. rule yaml file sample is

- singular: person
  plural: people
- singular: live
  plural: lives

See for details.


Please read the contribution guidelines before submitting pull requests.


Copyright 2018 Mercari, Inc.

yo is released under the MIT License.

Open Source Agenda is not affiliated with "Cloudspannerecosystem Yo" Project. README Source: cloudspannerecosystem/yo
Open Issues
Last Commit
1 month ago

Open Source Agenda Badge

Open Source Agenda Rating