feat: expose Firestore PITR fields in Database to stable (#811)

* feat: expose Firestore PITR fields in Database to stable feat: expose Firestore snapshot_time field in export API to stable feat: expose Firestore namespace ID fields in import/export APIs to stable docs: assorted typo fixes and whitespace updates PiperOrigin-RevId: 587811576 Source-Link: googleapis/googleapis@fbe1c8e Source-Link: googleapis/googleapis-gen@5fe704d Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiNWZlNzA0ZDk0ZmEyZDlhMWRjZTc1Mjk0MmI3MzA4ODczMTI0YjdkZCJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --------- Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

Author: gcf-owl-bot[bot]

google/cloud/firestore_admin_v1/services/firestore_admin/async_client.py

@@ -55,8 +55,10 @@
 from google.cloud.firestore_admin_v1.types import operation as gfa_operation
 from google.cloud.location import locations_pb2 # type: ignore
 from google.longrunning import operations_pb2 # type: ignore
+from google.protobuf import duration_pb2 # type: ignore
 from google.protobuf import empty_pb2 # type: ignore
 from google.protobuf import field_mask_pb2 # type: ignore
+from google.protobuf import timestamp_pb2 # type: ignore
 from .transports.base import FirestoreAdminTransport, DEFAULT_CLIENT_INFO
 from .transports.grpc_asyncio import FirestoreAdminGrpcAsyncIOTransport
 from .client import FirestoreAdminClient
@@ -1201,11 +1203,8 @@ async def sample_export_documents():
  google.api_core.operation_async.AsyncOperation:
  An object representing a long-running operation.
 
- The result type for the operation will be
- :class:`google.cloud.firestore_admin_v1.types.ExportDocumentsResponse`
- Returned in the
- [google.longrunning.Operation][google.longrunning.Operation]
- response field.
+ The result type for the operation will be :class:`google.cloud.firestore_admin_v1.types.ExportDocumentsResponse` Returned in the [google.longrunning.Operation][google.longrunning.Operation]
+ response field.
 
  """
  # Create or coerce a protobuf request object.

google/cloud/firestore_admin_v1/services/firestore_admin/client.py

@@ -59,8 +59,10 @@
 from google.cloud.firestore_admin_v1.types import operation as gfa_operation
 from google.cloud.location import locations_pb2 # type: ignore
 from google.longrunning import operations_pb2 # type: ignore
+from google.protobuf import duration_pb2 # type: ignore
 from google.protobuf import empty_pb2 # type: ignore
 from google.protobuf import field_mask_pb2 # type: ignore
+from google.protobuf import timestamp_pb2 # type: ignore
 from .transports.base import FirestoreAdminTransport, DEFAULT_CLIENT_INFO
 from .transports.grpc import FirestoreAdminGrpcTransport
 from .transports.grpc_asyncio import FirestoreAdminGrpcAsyncIOTransport
@@ -1432,11 +1434,8 @@ def sample_export_documents():
  google.api_core.operation.Operation:
  An object representing a long-running operation.
 
- The result type for the operation will be
- :class:`google.cloud.firestore_admin_v1.types.ExportDocumentsResponse`
- Returned in the
- [google.longrunning.Operation][google.longrunning.Operation]
- response field.
+ The result type for the operation will be :class:`google.cloud.firestore_admin_v1.types.ExportDocumentsResponse` Returned in the [google.longrunning.Operation][google.longrunning.Operation]
+ response field.
 
  """
  # Create or coerce a protobuf request object.

google/cloud/firestore_admin_v1/types/database.py

@@ -19,6 +19,9 @@
 
 import proto # type: ignore
 
+from google.protobuf import duration_pb2 # type: ignore
+from google.protobuf import timestamp_pb2 # type: ignore
+
 
 __protobuf__ = proto.module(
  package="google.firestore.admin.v1",
@@ -39,7 +42,7 @@ class Database(proto.Message):
  ``projects/{project}/databases/{database}``
  location_id (str):
  The location of the database. Available
- databases are listed at
+ locations are listed at
  https://cloud.google.com/firestore/docs/locations.
  type_ (google.cloud.firestore_admin_v1.types.Database.DatabaseType):
  The type of the database.
@@ -49,6 +52,32 @@ class Database(proto.Message):
  concurrency_mode (google.cloud.firestore_admin_v1.types.Database.ConcurrencyMode):
  The concurrency control mode to use for this
  database.
+ version_retention_period (google.protobuf.duration_pb2.Duration):
+ Output only. The period during which past versions of data
+ are retained in the database.
+
+ Any [read][google.firestore.v1.GetDocumentRequest.read_time]
+ or
+ [query][google.firestore.v1.ListDocumentsRequest.read_time]
+ can specify a ``read_time`` within this window, and will
+ read the state of the database at that time.
+
+ If the PITR feature is enabled, the retention period is 7
+ days. Otherwise, the retention period is 1 hour.
+ earliest_version_time (google.protobuf.timestamp_pb2.Timestamp):
+ Output only. The earliest timestamp at which older versions
+ of the data can be read from the database. See
+ [version_retention_period] above; this field is populated
+ with ``now - version_retention_period``.
+
+ This value is continuously updated, and becomes stale the
+ moment it is queried. If you are using this value to recover
+ data, make sure to account for the time from the moment when
+ the value is queried to the moment when you initiate the
+ recovery.
+ point_in_time_recovery_enablement (google.cloud.firestore_admin_v1.types.Database.PointInTimeRecoveryEnablement):
+ Whether to enable the PITR feature on this
+ database.
  app_engine_integration_mode (google.cloud.firestore_admin_v1.types.Database.AppEngineIntegrationMode):
  The App Engine integration mode to use for
  this database.
@@ -120,6 +149,30 @@ class ConcurrencyMode(proto.Enum):
  PESSIMISTIC = 2
  OPTIMISTIC_WITH_ENTITY_GROUPS = 3
 
+ class PointInTimeRecoveryEnablement(proto.Enum):
+ r"""Point In Time Recovery feature enablement.
+
+ Values:
+ POINT_IN_TIME_RECOVERY_ENABLEMENT_UNSPECIFIED (0):
+ Not used.
+ POINT_IN_TIME_RECOVERY_ENABLED (1):
+ Reads are supported on selected versions of the data from
+ within the past 7 days:
+
+ - Reads against any timestamp within the past hour
+ - Reads against 1-minute snapshots beyond 1 hour and within
+ 7 days
+
+ ``version_retention_period`` and ``earliest_version_time``
+ can be used to determine the supported versions.
+ POINT_IN_TIME_RECOVERY_DISABLED (2):
+ Reads are supported on any version of the
+ data from within the past 1 hour.
+ """
+ POINT_IN_TIME_RECOVERY_ENABLEMENT_UNSPECIFIED = 0
+ POINT_IN_TIME_RECOVERY_ENABLED = 1
+ POINT_IN_TIME_RECOVERY_DISABLED = 2
+
  class AppEngineIntegrationMode(proto.Enum):
  r"""The type of App Engine integration mode.
 
@@ -134,8 +187,11 @@ class AppEngineIntegrationMode(proto.Enum):
  database, as well as disabling writes to the
  database.
  DISABLED (2):
- Appengine has no affect on the ability of
+ App Engine has no effect on the ability of
  this database to serve requests.
+
+ This is the default setting for databases
+ created with the Firestore API.
  """
  APP_ENGINE_INTEGRATION_MODE_UNSPECIFIED = 0
  ENABLED = 1
@@ -159,6 +215,21 @@ class AppEngineIntegrationMode(proto.Enum):
  number=15,
  enum=ConcurrencyMode,
  )
+ version_retention_period: duration_pb2.Duration = proto.Field(
+ proto.MESSAGE,
+ number=17,
+ message=duration_pb2.Duration,
+ )
+ earliest_version_time: timestamp_pb2.Timestamp = proto.Field(
+ proto.MESSAGE,
+ number=18,
+ message=timestamp_pb2.Timestamp,
+ )
+ point_in_time_recovery_enablement: PointInTimeRecoveryEnablement = proto.Field(
+ proto.ENUM,
+ number=21,
+ enum=PointInTimeRecoveryEnablement,
+ )
  app_engine_integration_mode: AppEngineIntegrationMode = proto.Field(
  proto.ENUM,
  number=19,

google/cloud/firestore_admin_v1/types/firestore_admin.py

@@ -23,6 +23,7 @@
 from google.cloud.firestore_admin_v1.types import field as gfa_field
 from google.cloud.firestore_admin_v1.types import index as gfa_index
 from google.protobuf import field_mask_pb2 # type: ignore
+from google.protobuf import timestamp_pb2 # type: ignore
 
 
 __protobuf__ = proto.module(
@@ -412,6 +413,25 @@ class ExportDocumentsRequest(proto.Message):
  https://cloud.google.com/storage/docs/naming. If the URI is
  a bucket (without a namespace path), a prefix will be
  generated based on the start time.
+ namespace_ids (MutableSequence[str]):
+ Unspecified means all namespaces. This is the
+ preferred usage for databases that don't use
+ namespaces.
+
+ An empty string element represents the default
+ namespace. This should be used if the database
+ has data in non-default namespaces, but doesn't
+ want to include them. Each namespace in this
+ list must be unique.
+ snapshot_time (google.protobuf.timestamp_pb2.Timestamp):
+ The timestamp that corresponds to the version of the
+ database to be exported. The timestamp must be in the past,
+ rounded to the minute and not older than
+ [earliestVersionTime][google.firestore.admin.v1.Database.earliest_version_time].
+ If specified, then the exported documents will represent a
+ consistent view of the database at the provided time.
+ Otherwise, there are no guarantees about the consistency of
+ the exported documents.
  """
 
  name: str = proto.Field(
@@ -426,6 +446,15 @@ class ExportDocumentsRequest(proto.Message):
  proto.STRING,
  number=3,
  )
+ namespace_ids: MutableSequence[str] = proto.RepeatedField(
+ proto.STRING,
+ number=4,
+ )
+ snapshot_time: timestamp_pb2.Timestamp = proto.Field(
+ proto.MESSAGE,
+ number=5,
+ message=timestamp_pb2.Timestamp,
+ )
 
 
 class ImportDocumentsRequest(proto.Message):
@@ -444,6 +473,16 @@ class ImportDocumentsRequest(proto.Message):
  output_uri_prefix of an ExportDocumentsResponse from an
  export that has completed successfully. See:
  [google.firestore.admin.v1.ExportDocumentsResponse.output_uri_prefix][google.firestore.admin.v1.ExportDocumentsResponse.output_uri_prefix].
+ namespace_ids (MutableSequence[str]):
+ Unspecified means all namespaces. This is the
+ preferred usage for databases that don't use
+ namespaces.
+
+ An empty string element represents the default
+ namespace. This should be used if the database
+ has data in non-default namespaces, but doesn't
+ want to include them. Each namespace in this
+ list must be unique.
  """
 
  name: str = proto.Field(
@@ -458,6 +497,10 @@ class ImportDocumentsRequest(proto.Message):
  proto.STRING,
  number=3,
  )
+ namespace_ids: MutableSequence[str] = proto.RepeatedField(
+ proto.STRING,
+ number=4,
+ )
 
 
 __all__ = tuple(sorted(__protobuf__.manifest))

google/cloud/firestore_admin_v1/types/operation.py

@@ -199,7 +199,7 @@ class ChangeType(proto.Enum):
  )
 
  class TtlConfigDelta(proto.Message):
- r"""Information about an TTL configuration change.
+ r"""Information about a TTL configuration change.
 
  Attributes:
  change_type (google.cloud.firestore_admin_v1.types.FieldOperationMetadata.TtlConfigDelta.ChangeType):
@@ -291,7 +291,14 @@ class ExportDocumentsMetadata(proto.Message):
  collection_ids (MutableSequence[str]):
  Which collection ids are being exported.
  output_uri_prefix (str):
- Where the entities are being exported to.
+ Where the documents are being exported to.
+ namespace_ids (MutableSequence[str]):
+ Which namespace ids are being exported.
+ snapshot_time (google.protobuf.timestamp_pb2.Timestamp):
+ The timestamp that corresponds to the version
+ of the database that is being exported. If
+ unspecified, there are no guarantees about the
+ consistency of the documents being exported.
  """
 
  start_time: timestamp_pb2.Timestamp = proto.Field(
@@ -327,6 +334,15 @@ class ExportDocumentsMetadata(proto.Message):
  proto.STRING,
  number=7,
  )
+ namespace_ids: MutableSequence[str] = proto.RepeatedField(
+ proto.STRING,
+ number=8,
+ )
+ snapshot_time: timestamp_pb2.Timestamp = proto.Field(
+ proto.MESSAGE,
+ number=9,
+ message=timestamp_pb2.Timestamp,
+ )
 
 
 class ImportDocumentsMetadata(proto.Message):
@@ -352,6 +368,8 @@ class ImportDocumentsMetadata(proto.Message):
  Which collection ids are being imported.
  input_uri_prefix (str):
  The location of the documents being imported.
+ namespace_ids (MutableSequence[str]):
+ Which namespace ids are being imported.
  """
 
  start_time: timestamp_pb2.Timestamp = proto.Field(
@@ -387,6 +405,10 @@ class ImportDocumentsMetadata(proto.Message):
  proto.STRING,
  number=7,
  )
+ namespace_ids: MutableSequence[str] = proto.RepeatedField(
+ proto.STRING,
+ number=8,
+ )
 
 
 class ExportDocumentsResponse(proto.Message):

scripts/fixup_firestore_admin_v1_keywords.py

@@ -48,11 +48,11 @@ class firestore_adminCallTransformer(cst.CSTTransformer):
  'create_database': ('parent', 'database', 'database_id', ),
  'create_index': ('parent', 'index', ),
  'delete_index': ('name', ),
- 'export_documents': ('name', 'collection_ids', 'output_uri_prefix', ),
+ 'export_documents': ('name', 'collection_ids', 'output_uri_prefix', 'namespace_ids', 'snapshot_time', ),
  'get_database': ('name', ),
  'get_field': ('name', ),
  'get_index': ('name', ),
- 'import_documents': ('name', 'collection_ids', 'input_uri_prefix', ),
+ 'import_documents': ('name', 'collection_ids', 'input_uri_prefix', 'namespace_ids', ),
  'list_databases': ('parent', ),
  'list_fields': ('parent', 'filter', 'page_size', 'page_token', ),
  'list_indexes': ('parent', 'filter', 'page_size', 'page_token', ),