PITR(point-in-time recovery) 작업
이 페이지에서는 PITR(point-in-time recovery)을 사용하여 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 -
PITR 데이터 내보내기:
datastore.databases.export -
PITR 데이터 가져오기:
datastore.databases.import
커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.
시작하기 전에
PITR을 사용하기 전에 다음 사항에 유의하세요.
- PITR을 사용 설정한 직후에는 7일 전 데이터를 읽을 수 없습니다.
- 데이터베이스를 만들 때 PITR을 사용 설정하려면
gcloud firestore databases create명령어를 사용해야 합니다. 데이터베이스를 만드는 동안 Google Cloud 콘솔을 사용하여 PITR을 사용 설정할 수 없습니다. - Firestore는 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- Firestore 기반으로 설정
다음과 같이 gcloud firestore databases update 명령어를 사용하여 PITR을 사용 중지할 수 있습니다.
gcloud firestore databases update\
[--database=DATABASE_ID; default="(default)"]\
--no-enable-pitr
값을 다음과 같이 바꿉니다.
DATABASE_ID- 데이터베이스 ID 또는 (default)로 설정
보관 기간 및 가장 초기 버전 시간 가져오기
콘솔
Google Cloud 콘솔에서 데이터베이스 페이지로 이동합니다.
데이터베이스 목록에서 필요한 데이터베이스를 선택합니다.
탐색 메뉴에서 재해 복구를 클릭합니다.
설정 섹션에서 보관 기간 및 가장 초기 버전 시간을 확인합니다.
- 보관 기간: Firestore에서 데이터베이스의 모든 데이터 버전을 보관하는 기간입니다. 값은 PITR이 사용 중지된 경우 1시간, PITR이 사용 설정된 경우 7일입니다.
- 가장 초기 버전 시간: PITR 기간에서 이전 버전의 데이터를 읽을 수 있는 가장 이른 타임스탬프입니다. 이 값은 Firestore에 의해 지속적으로 업데이트되고 쿼리될 때 비활성 상태가 됩니다. 이 값을 사용하여 데이터를 복구하는 경우, 값이 쿼리된 순간부터 복구를 시작하는 순간까지의 기간을 고려해야 합니다.
- 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: FIRESTORE_NATIVE
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 데이터를 읽을 수 있습니다.
클라이언트 라이브러리
Java
PITR 데이터를 읽으려면 ReadOnly 트랜잭션을 사용해야 합니다. 읽기에서 readTime을 직접 지정할 수 없습니다.
자세한 내용은 트랜잭션 및 일괄 쓰기를 참조하세요.
Firestore firestore = …
TransactionOptions options =
TransactionOptions.createReadOnlyOptionsBuilder()
.setReadTime(
com.google.protobuf.Timestamp.newBuilder()
.setSeconds(1684098540L)
.setNanos(0))
.build();
ApiFuture<Void> futureTransaction = firestore.runTransaction(
transaction -> {
// Does a snapshot read document lookup
final DocumentSnapshot documentResult =
transaction.get(documentReference).get();
// Executes a snapshot read query
final QuerySnapshot queryResult =
transaction.get(query).get();
},
options);
// Blocks on transaction to complete
futureTransaction.get();
노드
PITR 데이터를 읽으려면 ReadOnly 트랜잭션을 사용해야 합니다. 읽기에서 readTime을 직접 지정할 수 없습니다.
자세한 내용은 트랜잭션 및 일괄 쓰기를 참조하세요.
const documentSnapshot = await firestore.runTransaction(
updateFunction => updateFunction.get(documentRef),
{readOnly: true, readTime: new Firestore.Timestamp(1684098540, 0)}
);
const querySnapshot = await firestore.runTransaction(
updateFunction => updateFunction.get(query),
{readOnly: true, readTime: new Firestore.Timestamp(1684098540, 0)}
)
REST API
PITR 읽기는 모든 Firestore 읽기 메서드(get, list, batchGet, listCollectionIds, listDocuments, runQuery, runAggregationQuery, partitionQuery)에서 지원됩니다.
REST 메서드를 사용하여 읽기를 수행하려면 다음 옵션 중 하나를 시도합니다.
읽기 메서드 요청에서
readTime값을readOptions메서드에 지원되는 PITR 타임스탬프로 전달합니다. PITR 타임스탬프는 지난 1시간 이내의 마이크로초 정밀도의 타임스탬프이거나 지난 1시간 이후의 1분 타임스탬프일 수 있지만earliestVersionTime보다 빠를 수는 없습니다.여러 PITR 읽기의 경우
ReadOnly트랜잭션의 일부로readTime매개변수를BeginTransaction메서드와 함께 사용합니다.
Apache Beam
FirestoreIO Apache Beam 커넥터를 사용하면 Dataflow로 Firestore 데이터베이스에서 대규모로 문서를 읽고 쓸 수 있습니다.
PITR 읽기는 FirestoreIO 커넥터의 다음 읽기 메서드에서 지원됩니다. 이러한 읽기 메서드는 PITR 읽기에 사용할 수 있는 withReadTime(@Nullable Instant readTime) 메서드를 지원합니다.
- FirestoreV1.BatchGetDocuments
- FirestoreV1.ListCollectionIds
- FirestoreV1.ListDocuments
- FirestoreV1.PartitionQuery
Java
일괄 읽기 또는 쓰기 작업에 다음 코드를 Dataflow 파이프라인 코드 예시와 함께 사용할 수 있습니다. 이 예시에서는 PITR 읽기에 withReadTime(@Nullable Instant readTime) 메서드를 사용합니다.
Instant readTime = Instant.ofEpochSecond(1684098540L);
PCollection<Document> documents =
pipeline
.apply(Create.of(collectionId))
.apply(
new FilterDocumentsQuery(
firestoreOptions.getProjectId(), firestoreOptions.getDatabaseId()))
.apply(FirestoreIO.v1().read().runQuery().withReadTime(readTime).withRpcQosOptions(rpcQosOptions).build())
...
Dataflow 파이프라인의 readTime 예시 전체 목록은 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이전이어야 합니다. 지정된 타임스탬프에 데이터가 더 이상 존재하지 않으면 오류가 발생합니다. - 실패한 PITR 내보내기에 대해서는 요금이 청구되지 않습니다.
데이터베이스로 가져옵니다.
모든 문서 가져오기의 단계에 따라 내보낸 데이터베이스를 가져옵니다. 데이터베이스에 이미 문서가 있으면 덮어쓰게 됩니다.