go-gorm-spanner

Google Cloud Spanner ORM for Go's GORM implementation.

import (
    "gorm.io/gorm"
    _ "github.com/googleapis/go-sql-spanner"

    spannergorm "github.com/googleapis/go-gorm-spanner"
)

db, err := gorm.Open(spannergorm.New(spannergorm.Config{
    DriverName: "spanner",
    DSN:        "projects/PROJECT/instances/INSTANCE/databases/DATABASE",
}), &gorm.Config{PrepareStmt: true})
if err != nil {
    log.Fatal(err)
}

// Print singers with more than 500 likes.
type Singer struct {
    gorm.Model
    Text         string
    Likes        int
}
var singers []Singer
if err := db.Where("likes > ?", 500).Find(&singers).Error; err != nil {
    log.Fatal(err)
}
for s := range singers {
    fmt.Println(s.ID, s.Text)
}

Emulator

See the Google Cloud Spanner Emulator support to learn how to start the emulator. When the emulator has been started and the environment variable has been set, gorm will automatically connect to the emulator instead of Cloud Spanner.

$ gcloud emulators spanner start
$ export SPANNER_EMULATOR_HOST=localhost:9010

Go Versions Supported

Our libraries are compatible with at least the three most recent, major Go releases. They are currently compatible with:

• Go 1.21
• Go 1.20
• Go 1.19

Data Types

Cloud Spanner supports the following data types in combination with gorm.

Cloud Spanner Type	gorm / go type
bool	bool, sql.NullBool
int64	uint, int64, sql.NullInt64
string	string, sql.NullString
json	string, sql.NullString
float64	float64, sql.NullFloat64
numeric	decimal.NullDecimal
timestamp with time zone	time.Time, sql.NullTime
date	datatypes.Date
bytes	[]byte

Limitations

The Cloud Spanner gorm dialect has the following known limitations:

Limitation	Workaround
OnConflict	OnConflict clauses are not supported
Nested transactions	Nested transactions and savepoints are not supported. It is therefore recommended to set the configuration option DisableNestedTransaction: true,
Locking	Lock clauses (e.g. clause.Locking{Strength: "UPDATE"}) are not supported. These are generally speaking also not required, as the default isolation level that is used by Cloud Spanner is serializable.
Auto-save associations	Auto saved associations are not supported, as these will automatically use an OnConflict clause
gorm.Automigrate with interleaved tables	Interleaved tables are supported by the Cloud Spanner gorm dialect, but Auto-Migration does not support interleaved tables. It is therefore recommended to create interleaved tables manually.
Cloud Spanner stale reads	Stale reads are not supported by gorm.

For the complete list of the limitations, see the Cloud Spanner GORM limitations.

OnConflict Clauses

OnConflict clauses are not supported by Cloud Spanner and should not be used. The following will therefore not work.

user := User{
    ID:   1,
    Name: "User Name",
}
// OnConflict is not supported and this will return an error.
db.Clauses(clause.OnConflict{DoNothing: true}).Create(&user)

Auto-save Associations

Auto-saving associations will automatically use an OnConflict clause in gorm. These are not supported. Instead, the parent entity of the association must be created before the child entity is created.

blog := Blog{
    ID:     1,
    Name:   "",
    UserID: 1,
    User: User{
        ID:   1,
        Name: "User Name",
    },
}
// This will fail, as the insert statement for User will use an OnConflict clause.
db.Create(&blog).Error

Instead, do the following:

user := User{
    ID:   1,
    Name: "User Name",
    Age:  20,
}
blog := Blog{
    ID:     1,
    Name:   "",
    UserID: 1,
}
db.Create(&user)
db.Create(&blog)

Nested Transactions

gorm uses savepoints for nested transactions. Savepoints are currently not supported by Cloud Spanner. Nested transactions can therefore not be used with GORM.

Locking

Locking clauses, like clause.Locking{Strength: "UPDATE"}, are not supported. These are generally speaking also not required, as Cloud Spanner uses isolation level serializable for read/write transactions.

Authorization

By default, each API will use Google Application Default Credentials for authorization credentials used in calling the API endpoints. This will allow your application to run in many environments without requiring explicit configuration.

Contributing

Contributions are welcome. Please, see the CONTRIBUTING document for details.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See Contributor Code of Conduct for more information.