-
Notifications
You must be signed in to change notification settings - Fork 85
/
instance.py
587 lines (477 loc) · 21.4 KB
/
instance.py
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
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
# Copyright 2016 Google LLC 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.
"""User friendly container for Cloud Spanner Instance."""
import google.api_core.operation
import re
from google.cloud.spanner_admin_instance_v1 import Instance as InstancePB
from google.cloud.spanner_admin_database_v1.types import backup
from google.cloud.spanner_admin_database_v1.types import spanner_database_admin
from google.cloud.spanner_admin_database_v1 import ListBackupsRequest
from google.cloud.spanner_admin_database_v1 import ListBackupOperationsRequest
from google.cloud.spanner_admin_database_v1 import ListDatabasesRequest
from google.cloud.spanner_admin_database_v1 import ListDatabaseOperationsRequest
from google.protobuf.empty_pb2 import Empty
from google.protobuf.field_mask_pb2 import FieldMask
# pylint: disable=ungrouped-imports
from google.cloud.exceptions import NotFound
from google.cloud.spanner_v1._helpers import _metadata_with_prefix
from google.cloud.spanner_v1.backup import Backup
from google.cloud.spanner_v1.database import Database
# pylint: enable=ungrouped-imports
_INSTANCE_NAME_RE = re.compile(
r"^projects/(?P<project>[^/]+)/" r"instances/(?P<instance_id>[a-z][-a-z0-9]*)$"
)
DEFAULT_NODE_COUNT = 1
_OPERATION_METADATA_MESSAGES = (
backup.Backup,
backup.CreateBackupMetadata,
spanner_database_admin.CreateDatabaseMetadata,
spanner_database_admin.Database,
spanner_database_admin.OptimizeRestoredDatabaseMetadata,
spanner_database_admin.RestoreDatabaseMetadata,
spanner_database_admin.UpdateDatabaseDdlMetadata,
)
_OPERATION_METADATA_TYPES = {
"type.googleapis.com/{}".format(message._meta.full_name): message
for message in _OPERATION_METADATA_MESSAGES
}
_OPERATION_RESPONSE_TYPES = {
backup.CreateBackupMetadata: backup.Backup,
spanner_database_admin.CreateDatabaseMetadata: spanner_database_admin.Database,
spanner_database_admin.OptimizeRestoredDatabaseMetadata: spanner_database_admin.Database,
spanner_database_admin.RestoreDatabaseMetadata: spanner_database_admin.Database,
spanner_database_admin.UpdateDatabaseDdlMetadata: Empty,
}
def _type_string_to_type_pb(type_string):
return _OPERATION_METADATA_TYPES.get(type_string, Empty)
class Instance(object):
"""Representation of a Cloud Spanner Instance.
We can use a :class:`Instance` to:
* :meth:`reload` itself
* :meth:`create` itself
* :meth:`update` itself
* :meth:`delete` itself
:type instance_id: str
:param instance_id: The ID of the instance.
:type client: :class:`~google.cloud.spanner_v1.client.Client`
:param client: The client that owns the instance. Provides
authorization and a project ID.
:type configuration_name: str
:param configuration_name: Name of the instance configuration defining
how the instance will be created.
Required for instances which do not yet exist.
:type node_count: int
:param node_count: (Optional) Number of nodes allocated to the instance.
:type display_name: str
:param display_name: (Optional) The display name for the instance in the
Cloud Console UI. (Must be between 4 and 30
characters.) If this value is not set in the
constructor, will fall back to the instance ID.
:type labels: dict (str -> str) or None
:param labels: (Optional) User-assigned labels for this instance.
"""
def __init__(
self,
instance_id,
client,
configuration_name=None,
node_count=DEFAULT_NODE_COUNT,
display_name=None,
emulator_host=None,
labels=None,
):
self.instance_id = instance_id
self._client = client
self.configuration_name = configuration_name
self.node_count = node_count
self.display_name = display_name or instance_id
self.emulator_host = emulator_host
if labels is None:
labels = {}
self.labels = labels
def _update_from_pb(self, instance_pb):
"""Refresh self from the server-provided protobuf.
Helper for :meth:`from_pb` and :meth:`reload`.
"""
if not instance_pb.display_name: # Simple field (string)
raise ValueError("Instance protobuf does not contain display_name")
self.display_name = instance_pb.display_name
self.configuration_name = instance_pb.config
self.node_count = instance_pb.node_count
self.labels = instance_pb.labels
@classmethod
def from_pb(cls, instance_pb, client):
"""Creates an instance from a protobuf.
:type instance_pb:
:class:`~google.spanner.v2.spanner_instance_admin_pb2.Instance`
:param instance_pb: A instance protobuf object.
:type client: :class:`~google.cloud.spanner_v1.client.Client`
:param client: The client that owns the instance.
:rtype: :class:`Instance`
:returns: The instance parsed from the protobuf response.
:raises ValueError:
if the instance name does not match
``projects/{project}/instances/{instance_id}`` or if the parsed
project ID does not match the project ID on the client.
"""
match = _INSTANCE_NAME_RE.match(instance_pb.name)
if match is None:
raise ValueError(
"Instance protobuf name was not in the " "expected format.",
instance_pb.name,
)
if match.group("project") != client.project:
raise ValueError(
"Project ID on instance does not match the " "project ID on the client"
)
instance_id = match.group("instance_id")
configuration_name = instance_pb.config
result = cls(instance_id, client, configuration_name)
result._update_from_pb(instance_pb)
return result
@property
def name(self):
"""Instance name used in requests.
.. note::
This property will not change if ``instance_id`` does not,
but the return value is not cached.
The instance name is of the form
``"projects/{project}/instances/{instance_id}"``
:rtype: str
:returns: The instance name.
"""
return self._client.project_name + "/instances/" + self.instance_id
def __eq__(self, other):
if not isinstance(other, self.__class__):
return NotImplemented
# NOTE: This does not compare the configuration values, such as
# the display_name. Instead, it only compares
# identifying values instance ID and client. This is
# intentional, since the same instance can be in different states
# if not synchronized. Instances with similar instance
# settings but different clients can't be used in the same way.
return other.instance_id == self.instance_id and other._client == self._client
def __ne__(self, other):
return not self == other
def copy(self):
"""Make a copy of this instance.
Copies the local data stored as simple types and copies the client
attached to this instance.
:rtype: :class:`~google.cloud.spanner_v1.instance.Instance`
:returns: A copy of the current instance.
"""
new_client = self._client.copy()
return self.__class__(
self.instance_id,
new_client,
self.configuration_name,
node_count=self.node_count,
display_name=self.display_name,
)
def create(self):
"""Create this instance.
See
https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.instance.v1#google.spanner.admin.instance.v1.InstanceAdmin.CreateInstance
.. note::
Uses the ``project`` and ``instance_id`` on the current
:class:`Instance` in addition to the ``display_name``.
To change them before creating, reset the values via
.. code:: python
instance.display_name = 'New display name'
instance.instance_id = 'i-changed-my-mind'
before calling :meth:`create`.
:rtype: :class:`~google.api_core.operation.Operation`
:returns: an operation instance
:raises Conflict: if the instance already exists
"""
api = self._client.instance_admin_api
instance_pb = InstancePB(
name=self.name,
config=self.configuration_name,
display_name=self.display_name,
node_count=self.node_count,
labels=self.labels,
)
metadata = _metadata_with_prefix(self.name)
future = api.create_instance(
parent=self._client.project_name,
instance_id=self.instance_id,
instance=instance_pb,
metadata=metadata,
)
return future
def exists(self):
"""Test whether this instance exists.
See
https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.instance.v1#google.spanner.admin.instance.v1.InstanceAdmin.GetInstanceConfig
:rtype: bool
:returns: True if the instance exists, else false
"""
api = self._client.instance_admin_api
metadata = _metadata_with_prefix(self.name)
try:
api.get_instance(name=self.name, metadata=metadata)
except NotFound:
return False
return True
def reload(self):
"""Reload the metadata for this instance.
See
https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.instance.v1#google.spanner.admin.instance.v1.InstanceAdmin.GetInstanceConfig
:raises NotFound: if the instance does not exist
"""
api = self._client.instance_admin_api
metadata = _metadata_with_prefix(self.name)
instance_pb = api.get_instance(name=self.name, metadata=metadata)
self._update_from_pb(instance_pb)
def update(self):
"""Update this instance.
See
https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.instance.v1#google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstance
.. note::
Updates the ``display_name``, ``node_count`` and ``labels``. To change those
values before updating, set them via
.. code:: python
instance.display_name = 'New display name'
instance.node_count = 5
before calling :meth:`update`.
:rtype: :class:`google.api_core.operation.Operation`
:returns: an operation instance
:raises NotFound: if the instance does not exist
"""
api = self._client.instance_admin_api
instance_pb = InstancePB(
name=self.name,
config=self.configuration_name,
display_name=self.display_name,
node_count=self.node_count,
labels=self.labels,
)
field_mask = FieldMask(paths=["config", "display_name", "node_count", "labels"])
metadata = _metadata_with_prefix(self.name)
future = api.update_instance(
instance=instance_pb, field_mask=field_mask, metadata=metadata
)
return future
def delete(self):
"""Mark an instance and all of its databases for permanent deletion.
See
https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.instance.v1#google.spanner.admin.instance.v1.InstanceAdmin.DeleteInstance
Immediately upon completion of the request:
* Billing will cease for all of the instance's reserved resources.
Soon afterward:
* The instance and all databases within the instance will be deleted.
All data in the databases will be permanently deleted.
"""
api = self._client.instance_admin_api
metadata = _metadata_with_prefix(self.name)
api.delete_instance(name=self.name, metadata=metadata)
def database(
self,
database_id,
ddl_statements=(),
pool=None,
logger=None,
encryption_config=None,
):
"""Factory to create a database within this instance.
:type database_id: str
:param database_id: The ID of the database.
:type ddl_statements: list of string
:param ddl_statements: (Optional) DDL statements, excluding the
'CREATE DATABASE' statement.
:type pool: concrete subclass of
:class:`~google.cloud.spanner_v1.pool.AbstractSessionPool`.
:param pool: (Optional) session pool to be used by database.
:type logger: :class:`logging.Logger`
:param logger: (Optional) a custom logger that is used if `log_commit_stats`
is `True` to log commit statistics. If not passed, a logger
will be created when needed that will log the commit statistics
to stdout.
:type encryption_config:
:class:`~google.cloud.spanner_admin_database_v1.types.EncryptionConfig`
or :class:`~google.cloud.spanner_admin_database_v1.types.RestoreDatabaseEncryptionConfig`
or :class:`dict`
:param encryption_config:
(Optional) Encryption configuration for the database.
If a dict is provided, it must be of the same form as either of the protobuf
messages :class:`~google.cloud.spanner_admin_database_v1.types.EncryptionConfig`
or :class:`~google.cloud.spanner_admin_database_v1.types.RestoreDatabaseEncryptionConfig`
:rtype: :class:`~google.cloud.spanner_v1.database.Database`
:returns: a database owned by this instance.
"""
return Database(
database_id,
self,
ddl_statements=ddl_statements,
pool=pool,
logger=logger,
encryption_config=encryption_config,
)
def list_databases(self, page_size=None):
"""List databases for the instance.
See
https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.database.v1#google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases
:type page_size: int
:param page_size:
Optional. The maximum number of databases in each page of results
from this request. Non-positive values are ignored. Defaults
to a sensible value set by the API.
:rtype: :class:`~google.api._ore.page_iterator.Iterator`
:returns:
Iterator of :class:`~google.cloud.spanner_admin_database_v1.types.Database`
resources within the current instance.
"""
metadata = _metadata_with_prefix(self.name)
request = ListDatabasesRequest(parent=self.name, page_size=page_size)
page_iter = self._client.database_admin_api.list_databases(
request=request, metadata=metadata
)
return page_iter
def backup(
self,
backup_id,
database="",
expire_time=None,
version_time=None,
encryption_config=None,
):
"""Factory to create a backup within this instance.
:type backup_id: str
:param backup_id: The ID of the backup.
:type database: :class:`~google.cloud.spanner_v1.database.Database`
:param database:
Optional. The database that will be used when creating the backup.
Required if the create method needs to be called.
:type expire_time: :class:`datetime.datetime`
:param expire_time:
Optional. The expire time that will be used when creating the backup.
Required if the create method needs to be called.
:type version_time: :class:`datetime.datetime`
:param version_time:
Optional. The version time that will be used to create the externally
consistent copy of the database. If not present, it is the same as
the `create_time` of the backup.
:type encryption_config:
:class:`~google.cloud.spanner_admin_database_v1.types.CreateBackupEncryptionConfig`
or :class:`dict`
:param encryption_config:
(Optional) Encryption configuration for the backup.
If a dict is provided, it must be of the same form as the protobuf
message :class:`~google.cloud.spanner_admin_database_v1.types.CreateBackupEncryptionConfig`
:rtype: :class:`~google.cloud.spanner_v1.backup.Backup`
:returns: a backup owned by this instance.
"""
try:
return Backup(
backup_id,
self,
database=database.name,
expire_time=expire_time,
version_time=version_time,
encryption_config=encryption_config,
)
except AttributeError:
return Backup(
backup_id,
self,
database=database,
expire_time=expire_time,
version_time=version_time,
encryption_config=encryption_config,
)
def list_backups(self, filter_="", page_size=None):
"""List backups for the instance.
:type filter_: str
:param filter_:
Optional. A string specifying a filter for which backups to list.
:type page_size: int
:param page_size:
Optional. The maximum number of databases in each page of results
from this request. Non-positive values are ignored. Defaults to a
sensible value set by the API.
:rtype: :class:`~google.api_core.page_iterator.Iterator`
:returns:
Iterator of :class:`~google.cloud.spanner_admin_database_v1.types.Backup`
resources within the current instance.
"""
metadata = _metadata_with_prefix(self.name)
request = ListBackupsRequest(
parent=self.name, filter=filter_, page_size=page_size,
)
page_iter = self._client.database_admin_api.list_backups(
request=request, metadata=metadata
)
return page_iter
def list_backup_operations(self, filter_="", page_size=None):
"""List backup operations for the instance.
:type filter_: str
:param filter_:
Optional. A string specifying a filter for which backup operations
to list.
:type page_size: int
:param page_size:
Optional. The maximum number of operations in each page of results
from this request. Non-positive values are ignored. Defaults to a
sensible value set by the API.
:rtype: :class:`~google.api_core.page_iterator.Iterator`
:returns:
Iterator of :class:`~google.api_core.operation.Operation`
resources within the current instance.
"""
metadata = _metadata_with_prefix(self.name)
request = ListBackupOperationsRequest(
parent=self.name, filter=filter_, page_size=page_size,
)
page_iter = self._client.database_admin_api.list_backup_operations(
request=request, metadata=metadata
)
return map(self._item_to_operation, page_iter)
def list_database_operations(self, filter_="", page_size=None):
"""List database operations for the instance.
:type filter_: str
:param filter_:
Optional. A string specifying a filter for which database operations
to list.
:type page_size: int
:param page_size:
Optional. The maximum number of operations in each page of results
from this request. Non-positive values are ignored. Defaults to a
sensible value set by the API.
:rtype: :class:`~google.api_core.page_iterator.Iterator`
:returns:
Iterator of :class:`~google.api_core.operation.Operation`
resources within the current instance.
"""
metadata = _metadata_with_prefix(self.name)
request = ListDatabaseOperationsRequest(
parent=self.name, filter=filter_, page_size=page_size,
)
page_iter = self._client.database_admin_api.list_database_operations(
request=request, metadata=metadata
)
return map(self._item_to_operation, page_iter)
def _item_to_operation(self, operation_pb):
"""Convert an operation protobuf to the native object.
:type operation_pb: :class:`~google.longrunning.operations.Operation`
:param operation_pb: An operation returned from the API.
:rtype: :class:`~google.api_core.operation.Operation`
:returns: The next operation in the page.
"""
operations_client = self._client.database_admin_api.transport.operations_client
metadata_type = _type_string_to_type_pb(operation_pb.metadata.type_url)
response_type = _OPERATION_RESPONSE_TYPES[metadata_type]
return google.api_core.operation.from_gapic(
operation_pb, operations_client, response_type, metadata_type=metadata_type
)