README.md
1# Go App Engine packages
2
3[](https://travis-ci.org/golang/appengine)
4
5This repository supports the Go runtime on *App Engine standard*.
6It provides APIs for interacting with App Engine services.
7Its canonical import path is `google.golang.org/appengine`.
8
9See https://cloud.google.com/appengine/docs/go/
10for more information.
11
12File issue reports and feature requests on the [GitHub's issue
13tracker](https://github.com/golang/appengine/issues).
14
15## Upgrading an App Engine app to the flexible environment
16
17This package does not work on *App Engine flexible*.
18
19There are many differences between the App Engine standard environment and
20the flexible environment.
21
22See the [documentation on upgrading to the flexible environment](https://cloud.google.com/appengine/docs/flexible/go/upgrading).
23
24## Directory structure
25
26The top level directory of this repository is the `appengine` package. It
27contains the
28basic APIs (e.g. `appengine.NewContext`) that apply across APIs. Specific API
29packages are in subdirectories (e.g. `datastore`).
30
31There is an `internal` subdirectory that contains service protocol buffers,
32plus packages required for connectivity to make API calls. App Engine apps
33should not directly import any package under `internal`.
34
35## Updating from legacy (`import "appengine"`) packages
36
37If you're currently using the bare `appengine` packages
38(that is, not these ones, imported via `google.golang.org/appengine`),
39then you can use the `aefix` tool to help automate an upgrade to these packages.
40
41Run `go get google.golang.org/appengine/cmd/aefix` to install it.
42
43### 1. Update import paths
44
45The import paths for App Engine packages are now fully qualified, based at `google.golang.org/appengine`.
46You will need to update your code to use import paths starting with that; for instance,
47code importing `appengine/datastore` will now need to import `google.golang.org/appengine/datastore`.
48
49### 2. Update code using deprecated, removed or modified APIs
50
51Most App Engine services are available with exactly the same API.
52A few APIs were cleaned up, and there are some differences:
53
54* `appengine.Context` has been replaced with the `Context` type from `golang.org/x/net/context`.
55* Logging methods that were on `appengine.Context` are now functions in `google.golang.org/appengine/log`.
56* `appengine.Timeout` has been removed. Use `context.WithTimeout` instead.
57* `appengine.Datacenter` now takes a `context.Context` argument.
58* `datastore.PropertyLoadSaver` has been simplified to use slices in place of channels.
59* `delay.Call` now returns an error.
60* `search.FieldLoadSaver` now handles document metadata.
61* `urlfetch.Transport` no longer has a Deadline field; set a deadline on the
62 `context.Context` instead.
63* `aetest` no longer declares its own Context type, and uses the standard one instead.
64* `taskqueue.QueueStats` no longer takes a maxTasks argument. That argument has been
65 deprecated and unused for a long time.
66* `appengine.BackendHostname` and `appengine.BackendInstance` were for the deprecated backends feature.
67 Use `appengine.ModuleHostname`and `appengine.ModuleName` instead.
68* Most of `appengine/file` and parts of `appengine/blobstore` are deprecated.
69 Use [Google Cloud Storage](https://godoc.org/cloud.google.com/go/storage) if the
70 feature you require is not present in the new
71 [blobstore package](https://google.golang.org/appengine/blobstore).
72* `appengine/socket` is not required on App Engine flexible environment / Managed VMs.
73 Use the standard `net` package instead.
74
75## Key Encode/Decode compatibiltiy to help with datastore library migrations
76
77Key compatibility updates have been added to help customers transition from google.golang.org/appengine/datastore to cloud.google.com/go/datastore.
78The `EnableKeyConversion` enables automatic conversion from a key encoded with cloud.google.com/go/datastore to google.golang.org/appengine/datastore key type.
79
80### Enabling key conversion
81
82Enable key conversion by calling `EnableKeyConversion(ctx)` in the `/_ah/start` handler for basic and manual scaling or any handler in automatic scaling.
83
84#### 1. Basic or manual scaling
85
86This start handler will enable key conversion for all handlers in the service.
87
88```
89http.HandleFunc("/_ah/start", func(w http.ResponseWriter, r *http.Request) {
90 datastore.EnableKeyConversion(appengine.NewContext(r))
91})
92```
93
94#### 2. Automatic scaling
95
96`/_ah/start` is not supported for automatic scaling and `/_ah/warmup` is not guaranteed to run, so you must call `datastore.EnableKeyConversion(appengine.NewContext(r))`
97before you use code that needs key conversion.
98
99You may want to add this to each of your handlers, or introduce middleware where it's called.
100`EnableKeyConversion` is safe for concurrent use. Any call to it after the first is ignored.
){kind=link}