PITR(point-in-time recovery) 작업

이 페이지에서는 PITR(point-in-time recovery)을 사용하여 Datastore 모드의 Firestore에서 데이터를 보관하고 복구하는 방법을 설명합니다.

PITR 개념을 이해하려면 PITR(point-in-time recovery)을 참조하세요.

권한

PITR 설정을 관리하는 데 필요한 권한을 얻으려면 관리자에게 PITR 설정을 사용 설정하려는 프로젝트에 대한 Cloud Datastore 소유자(roles/datastore.owner) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이 사전 정의된 역할에는 PITR 설정을 관리하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

PITR 설정을 관리하려면 다음 권한이 필요합니다.

데이터베이스를 만들 때 PITR 사용 설정: datastore.databases.create
기존 데이터베이스에서 PITR 설정 업데이트: datastore.databases.update,datastore.databases.list
PITR 데이터에서 읽기 수행: datastore.databases.get,datastore.entities.get,datastore.entities.list,datastore.namespaces.get,datastore.namespaces.list,datastore.statistics.get,datastore.statistics.list
PITR 데이터 내보내기: datastore.databases.export
PITR 데이터 가져오기: datastore.databases.import

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

시작하기 전에

PITR을 사용하기 전에 다음 사항에 유의하세요.

PITR을 사용 설정한 직후에는 7일 전 데이터를 읽을 수 없습니다.
데이터베이스를 만들 때 PITR을 사용 설정하려면 gcloud firestore databases create 명령어를 사용해야 합니다. 데이터베이스를 만드는 동안 Google Cloud 콘솔을 사용하여 PITR을 사용 설정할 수 없습니다.
Datastore 모드는 PITR을 사용 설정한 후부터 버전을 유지합니다.
PITR을 사용 중지한 후에는 PITR 기간의 PITR 데이터를 읽을 수 없습니다.
PITR을 중지한 직후에 다시 사용 설정하면 이전 PITR 데이터를 더 이상 사용할 수 없습니다. PITR을 사용 중지하기 전에 생성된 모든 PITR 데이터는 PITR 만료일 이후에 삭제됩니다.
실수로 지난 1시간 동안의 데이터를 삭제하고 PITR이 사용 중지된 경우, 삭제 후 1시간 이내에 PITR을 사용 설정하여 데이터를 복원할 수 있습니다.
만료된 PITR 데이터에 대해 수행된 모든 읽기는 실패합니다.

PITR 사용 설정

PITR을 사용하기 전에 Google Cloud 프로젝트에 결제를 사용 설정합니다. 결제가 사용 설정된 Google Cloud 프로젝트에서만 PITR 기능을 사용할 수 있습니다.

데이터베이스에 PITR을 사용 설정하려면 다음 안내를 따르세요.

콘솔

Google Cloud 콘솔에서 데이터베이스 페이지로 이동합니다.

데이터베이스로 이동
데이터베이스 목록에서 필요한 데이터베이스를 선택합니다.
탐색 메뉴에서 재해 복구를 클릭합니다.
수정을 클릭하여 설정을 수정합니다.
PITR(point-in-time recovery) 사용 설정 체크박스를 선택한 다음 저장을 클릭합니다.

PITR을 사용 설정하면 스토리지 비용이 발생합니다. 자세한 내용은 가격 책정을 참조하세요.

PITR을 사용 중지하려면 Google Cloud 콘솔의 재해 복구 페이지에서 PITR(point-in-time recovery) 사용 설정 체크박스를 선택 해제합니다.

gcloud

데이터베이스를 만드는 동안 다음과 같이 gcloud firestore databases create 명령어로 PITR을 사용 설정합니다.

gcloud firestore databases create\
  --location=LOCATION\
  [--database=DATABASE_ID; default="(default)"]\
  [--type=TYPE; default="firestore-native"]\
  --enable-pitr

값을 다음과 같이 바꿉니다.

LOCATION - 데이터베이스를 만들 위치
DATABASE_ID - 데이터베이스 ID 또는 (default)로 설정합니다.
TYPE - datastore-mode로 설정합니다.

다음과 같이 gcloud firestore databases update 명령어를 사용하여 PITR을 사용 중지할 수 있습니다.

gcloud firestore databases update\
  [--database=DATABASE_ID; default="(default)"]\
  --no-enable-pitr

값을 다음과 같이 바꿉니다.

DATABASE_ID - 데이터베이스 ID 또는 (default)로 설정

보관 기간 및 가장 초기 버전 시간 가져오기

콘솔

Google Cloud 콘솔에서 데이터베이스 페이지로 이동합니다.

데이터베이스로 이동
데이터베이스 목록에서 필요한 데이터베이스를 선택합니다.
탐색 메뉴에서 재해 복구를 클릭합니다.
설정 섹션에서 보관 기간 및 가장 초기 버전 시간을 확인합니다.
- 보관 기간: Datastore 모드가 데이터베이스의 모든 버전의 데이터를 보관하는 기간입니다. 값은 PITR이 사용 중지된 경우 1시간, PITR이 사용 설정된 경우 7일입니다.
- 가장 초기 버전 시간: PITR 기간에서 이전 버전의 데이터를 읽을 수 있는 가장 이른 타임스탬프입니다. 이 값은 Datastore 모드에 의해 지속적으로 업데이트되고 쿼리될 때 비활성 상태가 됩니다. 이 값을 사용하여 데이터를 복구하는 경우, 값이 쿼리된 순간부터 복구를 시작하는 순간까지의 기간을 고려해야 합니다.
- PITR(point-in-time recovery): PITR이 사용 설정된 경우 Enabled가 표시됩니다. PITR이 사용 중지되면 Disabled가 표시됩니다.

gcloud

다음과 같이 gcloud firestore databases describe 명령어를 실행합니다.

gcloud firestore databases describe --database=DATABASE_ID

DATABASE_ID를 데이터베이스 ID 또는 default로 바꿉니다.

출력은 다음과 같습니다.

    appEngineIntegrationMode: ENABLED
    concurrencyMode: PESSIMISTIC
    createTime: '2021-03-24T17:02:35.234Z'
    deleteProtectionState: DELETE_PROTECTION_DISABLED
    earliestVersionTime: '2023-06-12T16:17:25.222474Z'
    etag: IIDayqOevv8CMNTvyNK4uv8C
    keyPrefix: s
    locationId: nam5
    name: projects/PROJECT_ID/databases/(default)
    pointInTimeRecoveryEnablement: POINT_IN_TIME_RECOVERY_DISABLED
    type: DATASTORE_MODE
    uid: 5230c382-dcd2-468f-8cb3-2a1acfde2b32
    updateTime: '2021-11-17T17:48:22.171180Z'
    versionRetentionPeriod: 3600s

각 항목의 의미는 다음과 같습니다.

earliestVersionTime - 저장된 가장 이른 PITR 데이터의 타임스탬프입니다.
pointInTimeRecoveryEnablement: PITR이 사용 설정된 경우 POINT_IN_TIME_RECOVERY_ENABLED가 표시됨. PITR이 사용 중지되면 POINT_IN_TIME_RECOVERY_DISABLED가 표시되거나 pointInTimeRecoveryEnablement 필드가 표시되지 않을 수 있습니다.
versionRetentionPeriod - PITR 데이터가 유지되는 기간(밀리초)입니다. 값은 PITR이 사용 중지된 경우 1시간, PITR이 사용 설정된 경우 7일입니다.

PITR 데이터 읽기

클라이언트 라이브러리, REST API 메서드 또는 FirestoreIO Apache Beam 커넥터를 사용하여 PITR 데이터를 읽을 수 있습니다.

클라이언트 라이브러리

자바

PITR 데이터를 읽으려면 ReadOption 클래스의 readTime 메서드를 사용해야 합니다. ReadOnly 트랜잭션을 사용하여 읽기를 수행할 수 없습니다. 자세한 내용은 ReadOption 샘플 코드를 참조하세요.

  Datastore datastore = ...
  Timestamp timestamp = ...

  // lookup
  Key key = ...
  Entity entity = datastore.get(key, ReadOption.readTime(timestamp));

  // runQuery
  Query<Entity> query = ...
  QueryResults<Entity> queryResult = datastore.run(query, ReadOption.readTime(timestamp));

  // runAggregationQuery
  AggregationQuery countAggregationQuery = ...
  Long count = getOnlyElement(datastore.runAggregation(countAggregationQuery, ReadOption.readTime(timestamp))).get("total_count");

readTime 예시의 전체 목록은 GitHub 저장소를 참조하세요.

Python

readTime 메서드를 사용하여 Datastore 모드 Python SDK에서 PITR 읽기를 사용하거나 readTime과 함께 ReadOnly 트랜잭션을 사용하여 읽기를 수행합니다.

  from datetime import datetime, timezone

  read_time = datetime.now(tz=timezone.utc)

  key = …
  # read without PITR read time
  entity = client.get(key)

  # read with PITR read time
  entity = client.get(key, read_time=read_time)

  # PITR read using read_only transaction
  with client.transaction(read_only=True, read_time=read_time):
      entity = client.get(key)

  query = client.query…
  # run query without PITR read time
  iterator = query.fetch()

  # run query with PITR read time
  iterator = query.fetch(read_time=read_time)

  # PITR read query using read_only transaction
  with client.transaction(read_only=True, read_time=read_time):
      iterator = query.fetch()

readTime 예시의 전체 목록은 GitHub 저장소를 참조하세요.

REST API

PITR 읽기는 Datastore 모드 V1 읽기 메서드에서 지원되며, 이러한 메서드는 lookup, runQuery, runAggregationQuery입니다.

REST 메서드를 사용하여 읽기를 수행하려면 다음 옵션 중 하나를 사용해 보세요.

읽기 메서드 요청에서 readTime 값을 readOptions 메서드에 지원되는 PITR 타임스탬프로 전달합니다. PITR 타임스탬프는 지난 1시간 이내의 마이크로초 정밀도의 타임스탬프이거나 지난 1시간 이후의 1분 타임스탬프일 수 있지만 earliestVersionTime보다 빠를 수는 없습니다.
여러 PITR 읽기의 경우 ReadOnly 트랜잭션의 일부로 readTime 매개변수를 BeginTransaction 메서드와 함께 사용합니다.

Apache Beam

Datastore 모드 IO Apache Beam 커넥터를 사용하면 Dataflow로 Datastore 모드 데이터베이스에서 대규모로 항목을 읽고 쓸 수 있습니다.

DatastoreV1.Read 객체에서 withReadTime(Instant readTime) 메서드를 지정합니다. DatastoreV1.Read 객체를 사용하는 모든 후속 읽기는 동일한 readTime에서 읽습니다.

자바

다음 코드에서는 PITR 읽기에 withReadTime 메서드를 사용하는 방법을 보여줍니다.

  com.google.datastore.v1.Query query = ...
    Instant readTime = Instant.ofEpochSecond(1684098540L);

    DatastoreV1.Read read =
            DatastoreIO.v1()
                .read()
                .withProjectId(project)
                .withQuery(query)
                .withNamespace(namespace)
                .withReadTime(readTime);

    PCollection<Entity> entities = pipeline.apply(read);
    ...

withReadTime 예시의 전체 목록은 GitHub 저장소를 참조하세요.

PITR 데이터에서 내보내기 및 가져오기

gcloud firestore export 명령어를 사용하여 데이터베이스를 PITR 데이터에서 Cloud Storage로 내보낼 수 있습니다. 타임스탬프가 지난 7일 이내의 1분 타임스탬프이고 earliestVersionTime 이후인 PITR 데이터를 내보낼 수 있습니다. 데이터가 더 이상 지정된 타임스탬프에 없으면 내보내기 작업이 실패합니다.

PITR 내보내기 작업은 모든 항목 내보내기와 특정 종류 또는 네임스페이스 내보내기를 포함한 모든 필터를 지원합니다.

snapshot-time 매개변수를 필요한 복구 타임스탬프로 지정하여 데이터베이스를 내보냅니다.
gcloud
다음 명령어를 실행하여 데이터베이스를 버킷으로 내보냅니다.
```
gcloud firestore export gs://[BUCKET_NAME_PATH] \
    --snapshot-time=[PITR_TIMESTAMP] \
    --collection-ids=[COLLECTION_IDS] \
    --namespace-ids=[NAMESPACE_IDS]
```
각 항목의 의미는 다음과 같습니다.
- BUCKET_NAME_PATH - 내보내기 파일이 저장되는 경로 프리픽스(선택사항)가 있는 유효한 Cloud Storage 버킷
- PITR_TIMESTAMP - 분 단위의 PITR 타임스탬프입니다(예: 2023-05-26T10:20:00.00Z 또는 2023-10-19T10:30:00.00-07:00).
- COLLECTION_IDS - 컬렉션 ID 또는 컬렉션 그룹 ID의 목록입니다(예: 'specific collection group1', 'specific collection group2').
- NAMESPACE_IDS - 네임스페이스 ID 목록입니다(예: 'customer', 'orders').
항목 필터를 사용하여 종류 또는 네임스페이스의 특정 하위 집합 내보내기도 지원됩니다.

PITR 데이터를 내보내기 전에 다음 사항에 유의하세요.
- RFC 3339 형식으로 타임스탬프를 지정합니다. 예를 들면 2023-05-26T10:20:00.00Z 또는 2023-10-19T10:30:00.00-07:00입니다.
- 지정한 타임스탬프가 지난 7일 이내의 1분 타임스탬프여야 하지만 earliestVersionTime 이전이어야 합니다. 지정된 타임스탬프에 데이터가 더 이상 존재하지 않으면 오류가 발생합니다. 타임스탬프는 지정된 시간이 지난 1시간 이내인 경우에도 1분이어야 합니다.
- 실패한 PITR 내보내기 작업에는 요금이 청구되지 않습니다.
데이터베이스로 가져옵니다.

모든 항목 가져오기의 단계에 따라 내보낸 데이터베이스를 가져옵니다. 데이터베이스에 이미 항목이 있으면 덮어쓰게 됩니다. 항목 필터를 사용하여 종류 또는 네임스페이스의 특정 하위 집합 가져오기도 지원됩니다.