Menggunakan pemulihan point-in-time (PITR)

Halaman ini menjelaskan cara menggunakan pemulihan point-in-time (PITR) untuk mempertahankan dan memulihkan data di Firestore dalam mode Datastore.

Untuk memahami konsep PITR, lihat Pemulihan point-in-time.

Izin

Untuk mendapatkan izin yang diperlukan guna mengelola setelan PITR, minta administrator untuk memberi Anda peran IAM Cloud Datastore Owner (roles/datastore.owner) di project yang setelan PITR-nya ingin Anda aktifkan. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin yang diperlukan untuk mengelola setelan PITR. Untuk melihat izin yang benar-benar diperlukan, luaskan bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk mengelola setelan PITR:

  • Untuk mengaktifkan PITR saat membuat database: datastore.databases.create
  • Untuk memperbarui setelan PITR di database yang ada: datastore.databases.update,datastore.databases.list
  • Untuk melakukan pembacaan dari data PITR: datastore.databases.get,datastore.entities.get,datastore.entities.list,datastore.namespaces.get,datastore.namespaces.list,datastore.statistics.get,datastore.statistics.list
  • Untuk mengekspor data PITR: datastore.databases.export
  • Untuk mengimpor data PITR: datastore.databases.import

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Sebelum memulai

Perhatikan poin-poin berikut sebelum Anda mulai menggunakan PITR:

  • Anda tidak dapat langsung membaca dari tujuh hari yang lalu jika Anda baru saja mengaktifkan PITR.
  • Jika ingin mengaktifkan PITR saat membuat database, Anda harus menggunakan perintah gcloud firestore databases create. Mengaktifkan PITR saat membuat database menggunakan Konsol Google Cloud tidak didukung.
  • Mode Datastore mulai mempertahankan versi dari titik setelah mengaktifkan PITR.
  • Setelah menonaktifkan PITR, Anda tidak dapat membaca data PITR selama periode PITR.
  • Jika Anda mengaktifkan kembali PITR segera setelah menonaktifkannya, data PITR sebelumnya tidak lagi tersedia. Setiap data PITR yang dibuat sebelum menonaktifkan PITR akan dihapus setelah tanggal habis masa berlaku PITR.
  • Jika Anda tidak sengaja menghapus data dalam satu jam terakhir dan PITR dinonaktifkan, Anda dapat memulihkan data dengan mengaktifkan PITR dalam waktu satu jam setelah penghapusan.
  • Setiap pembacaan yang dilakukan pada data PITR yang sudah tidak berlaku akan gagal.

Mengaktifkan PITR

Sebelum menggunakan PITR, aktifkan penagihan untuk project Google Cloud Anda. Hanya project Google Cloud dengan penagihan aktif yang dapat menggunakan fitur PITR.

Untuk mengaktifkan PITR untuk database Anda:

Konsol

  1. Di konsol Google Cloud, buka halaman Databases.

    Buka Databases

  2. Pilih database yang diperlukan dari daftar database.

  3. Di menu navigasi, klik Disaster Recovery.

  4. Klik Edit untuk mengedit setelan.

  5. Centang kotak Enable point-in-time recovery, lalu klik Save.

Mengaktifkan PITR akan menimbulkan biaya penyimpanan. Lihat Harga untuk informasi selengkapnya.

Untuk menonaktifkan PITR, hapus centang pada kotak Enable point-in-time recovery dari halaman Disaster Recovery di konsol Google Cloud.

gcloud

Aktifkan PITR selama pembuatan database dengan perintah gcloud firestore databases create sebagai berikut:

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

Ganti nilai sebagai berikut:

  • LOCATION - lokasi tempat Anda ingin membuat database.
  • DATABASE_ID - ditetapkan ke ID database atau (default).
  • TYPE - ditetapkan ke mode datastore.

Anda dapat menonaktifkan PITR menggunakan perintah gcloud firestore databases update sebagai berikut:

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

Ganti nilai sebagai berikut:

  • DATABASE_ID - ditetapkan ke ID database atau (default).

Mendapatkan periode retensi data dan waktu versi paling awal

Konsol

  1. Di konsol Google Cloud, buka halaman Databases.

    Buka Databases

  2. Pilih database yang diperlukan dari daftar database.

  3. Di menu navigasi, klik Disaster Recovery.

  4. Di bagian Settings, perhatikan Retention period dan Earliest version time.

    • Retention period: periode ketika mode Datastore menyimpan semua versi data untuk database. Nilainya adalah satu jam saat PITR dinonaktifkan dan tujuh hari saat PITR diaktifkan.
    • Waktu versi paling awal: stempel waktu paling awal saat data versi sebelumnya dapat dibaca di periode PITR. Nilai ini terus diperbarui oleh mode Datastore dan menjadi tidak berlaku saat dikueri. Jika Anda menggunakan nilai ini untuk memulihkan data, pastikan untuk memperhitungkan waktu sejak saat nilai dikueri hingga saat Anda memulai pemulihan.
    • Pemulihan point-in-time: menampilkan Enabled, jika PITR diaktifkan. Jika PITR dinonaktifkan, Anda akan melihat Disabled.

gcloud

Jalankan perintah gcloud firestore databases describe sebagai berikut:

gcloud firestore databases describe --database=DATABASE_ID

Ganti DATABASE_ID dengan ID database atau default.

Berikut output-nya:

    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

dalam hal ini,

  • earliestVersionTime - stempel waktu data PITR paling awal yang disimpan.
  • pointInTimeRecoveryEnablement: menampilkan POINT_IN_TIME_RECOVERY_ENABLED, jika PITR diaktifkan. Jika PITR dinonaktifkan, Anda akan melihat POINT_IN_TIME_RECOVERY_DISABLED atau kolom pointInTimeRecoveryEnablement mungkin tidak ditampilkan.
  • versionRetentionPeriod - jangka waktu data PITR dipertahankan dalam milidetik. Nilainya dapat berupa satu jam saat PITR dinonaktifkan atau tujuh hari jika PITR diaktifkan.

Membaca data PITR

Anda dapat membaca data PITR menggunakan library klien, metode REST API, atau konektor FirestoreIO Apache Beam.

Library klien

Java

Anda harus menggunakan metode readTime di class ReadOption untuk membaca data PITR. Anda tidak dapat menggunakan transaksi ReadOnly untuk melakukan operasi baca. Lihat kode contoh ReadOption untuk mengetahui informasi selengkapnya.

  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");

Untuk mengetahui daftar lengkap contoh readTime, lihat repositori GitHub.

Python

Gunakan pembacaan PITR dalam mode Datastore Python SDK menggunakan metode readTime atau gunakan transaksi ReadOnly dengan readTime untuk melakukan pembacaan.

  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()

Untuk mengetahui daftar lengkap contoh readTime, lihat repositori GitHub.

REST API

Pembacaan PITR didukung dalam metode baca V1 mode Datastore, yaitu lookup, runQuery, dan runAggregationQuery.

Untuk melakukan pembacaan menggunakan metode REST, coba salah satu opsi berikut:

  1. Dalam permintaan metode baca Anda, teruskan nilai readTime sebagai stempel waktu PITR yang didukung dalam metode readOptions. Stempel waktu PITR dapat berupa stempel waktu presisi mikrodetik dalam satu jam terakhir, atau stempel waktu satu menit setelah satu jam terakhir, tetapi tidak lebih awal dari earliestVersionTime.

  2. Gunakan parameter readTime bersama dengan metode BeginTransaction sebagai bagian dari transaksi ReadOnly untuk beberapa pembacaan PITR.

Apache Beam

Gunakan konektor IO Apache Beam mode Datastore untuk membaca atau menulis entity dalam database mode Datastore dalam skala besar dengan Dataflow.

Tentukan metode withReadTime(Instant readTime) pada objek DatastoreV1.Read. Semua pembacaan berikutnya menggunakan objek DatastoreV1.Read yang dibaca dari readTime yang sama.

Java

Kode berikut menunjukkan cara menggunakan metode withReadTime untuk pembacaan PITR.

  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);
    ...

Untuk mengetahui daftar lengkap contoh withReadTime, lihat repositori GitHub.

Mengekspor dan mengimpor dari data PITR

Anda dapat mengekspor database ke Cloud Storage dari data PITR menggunakan perintah gcloud firestore export. Anda dapat mengekspor data PITR dengan stempel waktu satu menit dalam tujuh hari terakhir, tetapi tidak lebih awal dari earliestVersionTime. Jika data tidak lagi ada di stempel waktu yang ditentukan, operasi ekspor akan gagal.

Operasi ekspor PITR mendukung semua filter, termasuk ekspor semua entity dan ekspor jenis atau namespace tertentu.

  1. Ekspor database, dengan menentukan parameter snapshot-time ke stempel waktu pemulihan yang diperlukan.

    gcloud

    Jalankan perintah berikut untuk mengekspor database ke bucket Anda.

    gcloud firestore export gs://[BUCKET_NAME_PATH] \
    --snapshot-time=[PITR_TIMESTAMP] \
    --collection-ids=[COLLECTION_IDS] \
    --namespace-ids=[NAMESPACE_IDS]

    Dengan,

    • BUCKET_NAME_PATH - bucket Cloud Storage yang valid dengan awalan jalur opsional tempat file ekspor disimpan.
    • PITR_TIMESTAMP - stempel waktu PITR pada tingkat perincian menit, misalnya, 2023-05-26T10:20:00.00Z atau 2023-10-19T10:30:00.00-07:00.
    • COLLECTION_IDS - daftar ID koleksi atau ID kelompok koleksi, misalnya-'specific collection group1','specific collection group2'.
    • NAMESPACE_IDS - daftar ID namespace, misalnya-'customer','orders'.

    Mengekspor subkumpulan jenis dan/atau namespace tertentu dengan filter entity juga didukung.

    Perhatikan hal-hal berikut sebelum mengekspor data PITR:

    • Tentukan stempel waktu dalam format RFC 3339. Misalnya 2023-05-26T10:20:00.00Z atau 2023-10-19T10:30:00.00-07:00.
    • Pastikan stempel waktu yang Anda tentukan adalah stempel waktu keseluruhan satu menit dalam tujuh hari terakhir, tetapi tidak lebih awal dari earliestVersionTime. Jika data tidak lagi ada pada stempel waktu yang ditentukan, Anda akan menerima pesan error. Stempel waktu harus satu menit penuh, meskipun waktu yang ditentukan berada dalam satu jam terakhir.
    • Anda tidak akan ditagih untuk ekspor PITR yang gagal.

  2. Mengimpor ke database.

    Gunakan langkah-langkah di bagian Mengimpor semua entitas untuk mengimpor database yang telah diekspor. Jika ada entity yang sudah ada dalam database Anda, entity tersebut akan ditimpa. Mengimpor subset jenis dan/atau namespace tertentu dengan filter entity juga didukung.