spanner

README

Google Cloud Spanner

Usage

See Google Spanner Documentation for more details.

The DSN must be given in the following format.

spanner://projects/{projectId}/instances/{instanceId}/databases/{databaseName}?param=true

as described in README.md#database-urls

Param	WithInstance Config	Description
x-migrations-table	MigrationsTable	Name of the migrations table
x-clean-statements	CleanStatements	Whether to parse and clean DDL statements before running migration towards Spanner (Required for comments and multiple statements)
x-dml-comment-flag	DmlFlag	Comment flag to treat a migration file as DML
url	DatabaseName	The full path to the Spanner database resource. If provided as part of Config it must not contain a scheme or query string to match the format projects/{projectId}/instances/{instanceId}/databases/{databaseName}
projectId		The Google Cloud Platform project id
instanceId		The id of the instance running Spanner
databaseName		The name of the Spanner database

Note: Google Cloud Spanner migrations can take a considerable amount of time. The migrations provided as part of the example take about 6 minutes to run on a small instance.

1481574547/u create_users_table (21.354507597s)
1496539702/u add_city_to_users (41.647359754s)
1496601752/u add_index_on_user_emails (2m12.155787369s)
1496602638/u create_books_table (2m30.77299181s)

DDL with comments

At the moment the GCP Spanner backed does not seem to allow for comments (See https://issuetracker.google.com/issues/159730604) so in order to be able to use migration with DDL containing comments x-clean-stamements is required

Multiple statements

In order to be able to use more than 1 DDL statement in the same migration file, the file has to be parsed and therefore the x-clean-statements flag is required

DML

In order to have a migration file with DML you need to start the migration file with a one line comment for example #DML and use x-dml-comment-flag=DML

Testing

To unit test the spanner driver, SPANNER_DATABASE needs to be set. You'll need to sign-up to Google Cloud Platform (GCP) and have a running Spanner instance since it is not possible to run Google Spanner outside GCP.

Documentation

Index

• Constants
• Variables
• func WithInstance(instance *DB, config *Config) (database.Driver, error)
• type Config
• type DB
  • func NewDB(admin sdb.DatabaseAdminClient, data spanner.Client) *DB
• type Spanner
  • func (s *Spanner) Close() error
  • func (s *Spanner) Drop() error
  • func (s *Spanner) Lock() error
  • func (s *Spanner) Open(url string) (database.Driver, error)
  • func (s *Spanner) Run(migration io.Reader) error
  • func (s *Spanner) SetVersion(version int, dirty bool) error
  • func (s *Spanner) Unlock() error
  • func (s *Spanner) Version() (version int, dirty bool, err error)

Constants

const DefaultMigrationsTable = "SchemaMigrations"

DefaultMigrationsTable is used if no custom table is specified

Variables

var (
	ErrNilConfig      = errors.New("no config")
	ErrNoDatabaseName = errors.New("no database name")
	ErrNoSchema       = errors.New("no schema")
	ErrDatabaseDirty  = errors.New("database is dirty")
	ErrLockHeld       = errors.New("unable to obtain lock")
	ErrLockNotHeld    = errors.New("unable to release already released lock")
)

Driver errors

Functions

func WithInstance

func WithInstance(instance *DB, config *Config) (database.Driver, error)

WithInstance implements database.Driver

Types

type Config

type Config struct {
	MigrationsTable string
	DatabaseName    string
	// Whether to parse the migration DDL with spansql before
	// running them towards Spanner.
	// Parsing outputs clean DDL statements such as reformatted
	// and void of comments.
	CleanStatements bool
	// Comment flag name to treat a migration file as DML
	// Example #DML
	DmlFlag string
}

Config used for a Spanner instance

type DB

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

func NewDB

func NewDB(admin sdb.DatabaseAdminClient, data spanner.Client) *DB

type Spanner

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

Spanner implements database.Driver for Google Cloud Spanner

func (*Spanner) Close

func (s *Spanner) Close() error

Close implements database.Driver

func (*Spanner) Drop

func (s *Spanner) Drop() error

Drop implements database.Driver. Retrieves the database schema first and creates statements to drop the indexes and tables accordingly. Note: The drop statements are created in reverse order to how they're provided in the schema. Assuming the schema describes how the database can be "build up", it seems logical to "unbuild" the database simply by going the opposite direction. More testing

func (*Spanner) Lock

func (s *Spanner) Lock() error

Lock implements database.Driver but doesn't do anything because Spanner only enqueues the UpdateDatabaseDdlRequest.

func (*Spanner) Open

func (s *Spanner) Open(url string) (database.Driver, error)

Open implements database.Driver

func (*Spanner) Run

func (s *Spanner) Run(migration io.Reader) error

Run implements database.Driver

func (*Spanner) SetVersion

func (s *Spanner) SetVersion(version int, dirty bool) error

SetVersion implements database.Driver

func (*Spanner) Unlock

func (s *Spanner) Unlock() error

Unlock implements database.Driver but no action required, see Lock.

func (*Spanner) Version

func (s *Spanner) Version() (version int, dirty bool, err error)

Version implements database.Driver