breaking changes to cloud datastore package coming soon

[Jonathan Amsterdam]

These changes apply only to cloud.google.com/go/datastore. The appengine datastore packages are unaffected.

This is the first of two sets of changes we'll soon be making to the cloud datastore package. The changes described in this message alter the surface of the package, but not its semantics. 

The other change, support for entity values, will be described in a subsequent post. It doesn't require any code changes, but does alter how data is stored in Datastore.

If you don't want any of these changes to affect you until you're ready to deal with them, we suggest vendoring the cloud.google.com/go/datastore package. You may want to use an existing package management tool to help you with vendoring. We've provided the repo tag v0.4.0 to support tools that accept tags. Vendoring to that tag (or the value of master as of today) will isolate your code from all these changes.

Most of the surface changes follow from the fact that we will no longer be using contexts to propagate namespaces. Namespaces for keys and queries must be set explicitly. We've taken this opportunity to improve key creation in other ways as well.

Removing WithNamespace

The WithNamespace function will disappear, since its only purpose was to add a namespace to a context. To specify a namespace in a Query, use the Query.Namespace method:

q := datastore.NewQuery("Kind").Namespace("ns")

Query.Namespace is already available, so you can make this change today.

Key Fields Exported

All the fields of Key will be exported. That means you can construct any Key with a struct literal:

k := &Key{Kind: "Kind",  ID: 37, Namespace: "ns"}

The Key methods that returned fields—Key.Kind, Key.ID, Key.Name, Key.Parent and Key.Namespace—will be removed. So will Key.SetParent.

Changes to Key Constructors

Although you can create any Key with a literal or by assigning to its fields, we still provide functions for common cases.

NewIncompleteKey will be replaced by IncompleteKey, which doesn't take a context. You can make this change to your code with the following command:

gofmt -w -r 'datastore.NewIncompleteKey(a, b, c) -> datastore.IncompleteKey(b, c)' *.go

Two important caveats about this command and the two that follow:

• If you do use namespaces, these commands will change the meaning of your program, because they will not set the key's namespace. After running them make sure you set each key's Namespace field manually.
• Because these commands drop the context argument, they may leave you with code that doesn't compile because of unused local variables.

NewKey will be replaced with two functions:

NameKey(kind, name string, parent *Key) *Key

IDKey(kind string, id int64, parent *Key) *Key

 

These functions drop the context argument of NewKey and emphasize that a key can have either a name or an ID, but not both. You can convert most calls of NewKey with the following two commands:

gofmt -w -r 'datastore.NewKey(a, b, c, 0, e) -> datastore.NameKey(b, c, e)' *.go

 

gofmt -w -r 'datastore.NewKey(a, b, "", d, e) -> datastore.IDKey(b, d, e)' *.go

 

In addition to the two caveats mentioned above, these commands will fail to convert a NewKey call if you've provided something other than a literal for the empty string or 0, or if you've (erroneously) specified both a non-empty name and a non-zero ID.

The three new key functions (IncompleteKey, NameKey and IDKey) are already available, so you can start converting your code today.

Other Changes

• The Done variable will be removed. Replace datastore.Done with iterator.Done, where iterator is the package google.golang.org/api/iterator. You can start making this change today.
  
• The Client.Close method will have a return type of error. It will return the result of closing the underlying gRPC connection.
  

[Jonathan Amsterdam]

These changes are in.