forked from googleapis/google-cloud-go
-
Notifications
You must be signed in to change notification settings - Fork 0
/
doc.go
319 lines (221 loc) · 9.65 KB
/
doc.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
/*
Copyright 2017 Google Inc. All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
/*
Package spanner provides a client for reading and writing to Cloud Spanner
databases. See the packages under admin for clients that operate on databases
and instances.
Note: This package is in alpha. Backwards-incompatible changes may occur
without notice.
See https://cloud.google.com/spanner/docs/getting-started/go/ for an introduction
to Cloud Spanner and additional help on using this API.
Creating a Client
To start working with this package, create a client that refers to the database
of interest:
ctx := context.Background()
client, err := spanner.NewClient(ctx, "projects/P/instances/I/databases/D")
if err != nil {
// TODO: Handle error.
}
Simple Reads and Writes
Two Client methods, Apply and Single, work well for simple reads and writes. As
a quick introduction, here we write a new row to the database and read it back:
_, err := client.Apply(ctx, []*spanner.Mutation{
spanner.Insert("Users",
[]string{"name", "email"},
[]interface{}{"alice", "a@example.com"})})
if err != nil {
// TODO: Handle error.
}
row, err := client.Single().ReadRow(ctx, "Users",
spanner.Key{"alice"}, []string{"email"})
if err != nil {
// TODO: Handle error.
}
All the methods used above are discussed in more detail below.
Keys
Every Cloud Spanner row has a unique key, composed of one or more columns.
Construct keys with a literal of type Key:
key1 := spanner.Key{"alice"}
KeyRanges
The keys of a Cloud Spanner table are ordered. You can specify ranges of keys
using the KeyRange type:
kr1 := spanner.KeyRange{Start: key1, End: key2}
By default, a KeyRange includes its start key but not its end key. Use
the Kind field to specify other boundary conditions:
// include both keys
kr2 := spanner.KeyRange{Start: key1, End: key2, Kind: spanner.ClosedClosed}
KeySets
A KeySet represents a set of keys. AllKeys returns a KeySet that refers to all
the keys in a table:
ks1 := spanner.AllKeys()
To construct a set of specific keys, use the Keys function:
ks2 := spanner.Keys(key1, key2, key3)
You can also build KeySets from ranges of keys:
ks3 := spanner.Range(kr1)
Use UnionKeySets to build up more complex KeySets, or construct one directly
using a KeySet literal:
ks4 := spanner.KeySet{
Keys: []spanner.Keys{key1, key2},
Ranges: []spanner.KeyRange{kr1, kr2},
}
Transactions
All Cloud Spanner reads and writes occur inside transactions. There are two
types of transactions, read-only and read-write. Read-only transactions cannot
change the database, do not acquire locks, and may access either the current
database state or states in the past. Read-write transactions can read the
database before writing to it, and always apply to the most recent database
state.
Single Reads
The simplest and fastest transaction is a ReadOnlyTransaction that supports a
single read operation. Use Client.Single to create such a transaction. You can
chain the call to Single with a call to a Read method.
When you only want one row whose key you know, use ReadRow. Provide the table
name, key, and the columns you want to read:
row, err := client.Single().ReadRow(ctx, "Accounts", spanner.Key{"alice"}, []string{"balance"})
Read multiple rows with the Read method. It takes a table name, KeySet, and list
of columns:
iter := client.Single().Read(ctx, "Accounts", keyset1, columns)
Read returns a RowIterator. You can call the Do method on the iterator and pass
a callback:
err := iter.Do(func(row *Row) error {
// TODO: use row
return nil
})
RowIterator also follows the standard pattern for the Google
Cloud Client Libraries:
defer iter.Stop()
for {
row, err := iter.Next()
if err == iterator.Done {
break
}
if err != nil {
// TODO: Handle error.
}
// TODO: use row
}
Always call Stop when you finish using an iterator this way, whether or not you
iterate to the end. (Failing to call Stop could lead you to exhaust the
database's session quota.)
To read rows with an index, use ReadUsingIndex.
Statements
The most general form of reading uses SQL statements. Construct a Statement
with NewStatement, setting any parameters using the Statement's Params map:
stmt := spanner.NewStatement("SELECT First, Last FROM SINGERS WHERE Last >= @start")
stmt.Params["start"] = "Dylan"
You can also construct a Statement directly with a struct literal, providing
your own map of parameters.
Use the Query method to run the statement and obtain an iterator:
iter := client.Single().Query(ctx, stmt)
Rows
Once you have a Row, via an iterator or a call to ReadRow, you can extract
column values in several ways. Pass in a pointer to a Go variable of the
appropriate type when you extract a value.
You can extract by column position or name:
err := row.Column(0, &name)
err = row.ColumnByName("balance", &balance)
You can extract all the columns at once:
err = row.Columns(&name, &balance)
Or you can define a Go struct that corresponds to your columns, and extract
into that:
var s struct { Name string; Balance int64 }
err = row.ToStruct(&s)
For Cloud Spanner columns that may contain NULL, use one of the NullXXX types,
like NullString:
var ns spanner.NullString
if err =: row.Column(0, &ns); err != nil {
// TODO: Handle error.
}
if ns.Valid {
fmt.Println(ns.StringVal)
} else {
fmt.Println("column is NULL")
}
Multiple Reads
To perform more than one read in a transaction, use ReadOnlyTransaction:
txn := client.ReadOnlyTransaction()
defer txn.Close()
iter := txn.Query(ctx, stmt1)
// ...
iter = txn.Query(ctx, stmt2)
// ...
You must call Close when you are done with the transaction.
Timestamps and Timestamp Bounds
Cloud Spanner read-only transactions conceptually perform all their reads at a
single moment in time, called the transaction's read timestamp. Once a read has
started, you can call ReadOnlyTransaction's Timestamp method to obtain the read
timestamp.
By default, a transaction will pick the most recent time (a time where all
previously committed transactions are visible) for its reads. This provides the
freshest data, but may involve some delay. You can often get a quicker response
if you are willing to tolerate "stale" data. You can control the read timestamp
selected by a transaction by calling the WithTimestampBound method on the
transaction before using it. For example, to perform a query on data that is at
most one minute stale, use
client.Single().
WithTimestampBound(spanner.MaxStaleness(1*time.Minute)).
Query(ctx, stmt)
See the documentation of TimestampBound for more details.
Mutations
To write values to a Cloud Spanner database, construct a Mutation. The spanner
package has functions for inserting, updating and deleting rows. Except for the
Delete methods, which take a Key or KeyRange, each mutation-building function
comes in three varieties.
One takes lists of columns and values along with the table name:
m1 := spanner.Insert("Users",
[]string{"name", "email"},
[]interface{}{"alice", "a@example.com"})
One takes a map from column names to values:
m2 := spanner.InsertMap("Users", map[string]interface{}{
"name": "alice",
"email": "a@example.com",
})
And the third accepts a struct value, and determines the columns from the
struct field names:
type User struct { Name, Email string }
u := User{Name: "alice", Email: "a@example.com"}
m3, err := spanner.InsertStruct("Users", u)
Writes
To apply a list of mutations to the database, use Apply:
_, err := client.Apply(ctx, []*spanner.Mutation{m1, m2, m3})
If you need to read before writing in a single transaction, use a
ReadWriteTransaction. ReadWriteTransactions may abort and need to be retried.
You pass in a function to ReadWriteTransaction, and the client will handle the
retries automatically. Use the transaction's BufferWrite method to buffer
mutations, which will all be executed at the end of the transaction:
_, err := client.ReadWriteTransaction(ctx, func(txn *spanner.ReadWriteTransaction) error {
var balance int64
row, err := txn.ReadRow(ctx, "Accounts", spanner.Key{"alice"}, []string{"balance"})
if err != nil {
// This function will be called again if this is an IsAborted error.
return err
}
if err := row.Column(0, &balance); err != nil {
return err
}
if balance <= 10 {
return errors.New("insufficient funds in account")
}
balance -= 10
m := spanner.Update("Accounts", []string{"user", "balance"}, []interface{}{"alice", balance})
txn.BufferWrite([]*spanner.Mutation{m})
// The buffered mutation will be committed. If the commit
// fails with an IsAborted error, this function will be called
// again.
return nil
})
Authentication
See examples of authorization and authentication at
https://godoc.org/cloud.google.com/go#pkg-examples.
*/
package spanner // import "cloud.google.com/go/spanner"