Mengekspor database dari Spanner ke Avro

Halaman ini menjelaskan cara mengekspor database Spanner dengan Konsol Google Cloud. Untuk mengekspor database Spanner menggunakan REST API atau alat command line gcloud spanner, selesaikan langkah-langkah di bagian Sebelum memulai di halaman ini, lalu lihat petunjuk mendetail di Spanner ke Cloud Storage Avro dalam dokumentasi Dataflow. Proses ekspor menggunakan Dataflow dan menulis data ke folder di bucket Cloud Storage. Folder yang dihasilkan berisi kumpulan file Avro dan file manifes JSON.

Sebelum memulai

Untuk mengekspor database Spanner, Anda harus mengaktifkan Spanner, Cloud Storage, Compute Engine, dan Dataflow API terlebih dahulu:

Mengaktifkan API

Anda juga memerlukan kuota yang cukup dan izin IAM yang diperlukan.

Persyaratan kuota

Persyaratan kuota untuk tugas ekspor adalah sebagai berikut:

• Spanner: Tidak diperlukan kapasitas komputasi tambahan untuk mengekspor database, meskipun Anda mungkin perlu menambahkan lebih banyak kapasitas komputasi agar tugas Anda selesai dalam jangka waktu yang wajar. Lihat Mengoptimalkan tugas untuk mengetahui detail selengkapnya.
• Cloud Storage: Untuk mengekspor, Anda harus membuat bucket untuk file yang diekspor jika belum memilikinya. Anda dapat melakukannya di konsol Google Cloud, baik melalui halaman Cloud Storage maupun saat membuat ekspor melalui halaman Spanner. Anda tidak perlu menetapkan ukuran bucket.
• Dataflow: Tugas ekspor memiliki CPU, penggunaan disk, dan alamat IP kuota Compute Engine yang sama dengan tugas Dataflow lainnya.

• Compute Engine: Sebelum menjalankan tugas ekspor, Anda harus menyiapkan kuota awal untuk Compute Engine, yang digunakan Dataflow. Kuota ini menunjukkan jumlah maksimum resource yang Anda izinkan untuk digunakan Dataflow untuk tugas Anda. Nilai awal yang direkomendasikan adalah:

  • CPU: 200
  • Alamat IP yang sedang digunakan: 200
  • Persistent disk standar: 50 TB

  Umumnya, Anda tidak perlu melakukan penyesuaian lainnya. Dataflow menyediakan penskalaan otomatis sehingga Anda hanya membayar resource sebenarnya yang digunakan selama ekspor. Jika tugas Anda dapat menggunakan lebih banyak resource, UI Dataflow akan menampilkan ikon peringatan. Tugas akan selesai meskipun ada ikon peringatan.

Persyaratan IAM

Untuk mengekspor database, Anda juga harus memiliki peran IAM dengan izin yang memadai untuk menggunakan semua layanan yang terlibat dalam tugas ekspor. Untuk mengetahui informasi tentang cara memberikan peran dan izin, lihat Menerapkan peran IAM.

Untuk mengekspor database, Anda memerlukan peran berikut:

• Di level project Google Cloud:
  • Viewer Spanner (roles/spanner.viewer)
  • Admin Dataflow (roles/dataflow.admin)
  • Storage Admin (roles/storage.admin)
• Di level instance atau database Spanner, atau di level project Google Cloud:
  • Pembaca Database Spanner (roles/spanner.databaseReader)
  • Admin Database Spanner (roles/spanner.databaseAdmin)

Catatan: Peran Admin Database Spanner hanya diperlukan untuk tugas impor.

Untuk menggunakan resource komputasi independen Spanner Data Boost selama ekspor, Anda juga memerlukan izin IAM spanner.databases.useDataBoost. Untuk mengetahui informasi selengkapnya, lihat ringkasan Data Boost.

Mengekspor database

Setelah memenuhi persyaratan kuota dan IAM yang dijelaskan sebelumnya, Anda dapat mengekspor database Spanner yang ada.

Catatan: Anda dapat mengekspor database yang sedang digunakan dengan aman. Namun, setiap perubahan yang Anda lakukan setelah Dataflow membuat transaksi Spanner tidak akan direkam oleh ekspor karena semua data yang diekspor berasal dari snapshot database yang sama.

Untuk mengekspor database Spanner ke bucket Cloud Storage, ikuti langkah-langkah berikut.

1. Buka halaman Instance Spanner.

   Buka halaman instance

2. Klik nama instance yang berisi database Anda.

3. Klik item menu Import/Export di panel kiri, lalu klik tombol Export.

4. Di bagian Pilih tempat untuk menyimpan ekspor, klik Cari.

5. Jika belum memiliki bucket Cloud Storage untuk ekspor Anda:

   1. Klik New bucket .
   2. Masukkan nama untuk bucket Anda. Nama bucket harus unik di seluruh Cloud Storage.
   3. Pilih kelas penyimpanan dan lokasi default, lalu klik Buat.
   4. Klik bucket Anda untuk memilihnya.

   Jika sudah memiliki bucket, pilih bucket dari daftar awal atau klik Search untuk memfilter daftar, lalu klik bucket Anda untuk memilihnya.

6. Klik Pilih.

7. Pilih database yang ingin diekspor di menu drop-down Choose a database to export.

8. Opsional: Untuk mengekspor database dari waktu sebelumnya, centang kotak, lalu masukkan stempel waktu.

9. Pilih region di menu drop-down Choose a region for the export job.

   Catatan: Untuk menghindari biaya transfer data, pilih region yang tumpang-tindih dengan konfigurasi instance Anda. Untuk mengetahui informasi selengkapnya, lihat bagian Memilih wilayah.

10. Opsional: Untuk mengenkripsi status pipeline Dataflow dengan kunci enkripsi yang dikelola pelanggan:

    1. Klik Tampilkan opsi enkripsi.
    2. Pilih Gunakan kunci enkripsi yang dikelola pelanggan (CMEK).
    3. Pilih kunci dari menu drop-down.

    Opsi ini tidak memengaruhi enkripsi tingkat bucket Cloud Storage tujuan. Guna mengaktifkan CMEK untuk bucket Cloud Storage, lihat Menggunakan CMEK dengan Cloud Storage.

11. Opsional: Untuk mengekspor menggunakan Spanner Data Boost, centang kotak Use Spanner Data Boost. Untuk mengetahui informasi selengkapnya, lihat ringkasan Data Boost.

12. Pilih kotak centang di bagian Konfirmasi tagihan untuk mengonfirmasi bahwa ada tagihan selain yang dikenakan oleh instance Spanner yang ada.

13. Klik Ekspor.

    Konsol Google Cloud menampilkan halaman Database Import/Export, yang kini menampilkan item baris untuk tugas ekspor Anda di daftar tugas impor/ekspor, termasuk waktu berlalu tugas tersebut:

    

Setelah tugas selesai atau dihentikan, status akan diperbarui di daftar impor/ekspor. Jika tugas berhasil, status Succeeded akan ditampilkan:

Jika tugas gagal, status Gagal akan ditampilkan:

Untuk melihat detail operasi Dataflow untuk tugas Anda, klik nama tugas di kolom Dataflow job name.

Jika tugas Anda gagal, periksa log Dataflow tugas untuk mengetahui detail error.

Guna menghindari biaya Cloud Storage untuk file yang telah dibuat oleh tugas ekspor yang gagal, hapus folder tersebut dan file-filenya. Baca bagian Melihat ekspor untuk mengetahui informasi tentang cara menemukan folder.

Catatan tentang mengekspor kolom dan aliran perubahan yang dibuat

Nilai dalam kolom yang dihasilkan yang disimpan tidak akan diekspor. Definisi kolom diekspor ke skema Avro sebagai kolom kumpulan data berjenis null, dengan definisi kolom sebagai properti kustom kolom. Sampai operasi pengisian ulang kolom yang baru ditambahkan yang dihasilkan selesai, kolom yang dihasilkan akan diabaikan seolah-olah tidak ada dalam skema.

Aliran data perubahan yang diekspor sebagai file Avro hanya berisi skema aliran perubahan, bukan kumpulan data perubahan data.

Catatan tentang pengeksporan urutan

Urutan (GoogleSQL, PostgreSQL) adalah objek skema yang Anda gunakan untuk membuat nilai bilangan bulat yang unik. Spanner mengekspor setiap objek skema ke skema Avro sebagai kolom kumpulan data, beserta jenis urutannya, rentang yang dilewati, dan penghitung sebagai properti kolom tersebut. Perhatikan bahwa untuk mencegah urutan direset dan menghasilkan nilai duplikat setelah impor, selama ekspor skema, fungsi GET_INTERNAL_SEQUENCE_STATE() (GoogleSQL, PostgreSQL) menangkap penghitung urutan. Spanner menambahkan buffer 1.000 ke penghitung, dan menulis nilai penghitung baru ke kolom kumpulan data. Pendekatan ini menghindari error nilai duplikat yang mungkin terjadi setelah impor. Jika ada lebih banyak penulisan ke database sumber selama ekspor data, Anda harus menyesuaikan penghitung urutan yang sebenarnya dengan menggunakan pernyataan ALTER SEQUENCE (GoogleSQL, PostgreSQL).

Saat mengimpor, urutan dimulai dari penghitung baru ini, bukan penghitung yang ditemukan dalam skema. Atau, Anda dapat menggunakan pernyataan ALTER SEQUENCE (GoogleSQL, PostgreSQL) untuk memperbarui urutan dengan penghitung baru.

Melihat ekspor Anda di Cloud Storage

Untuk melihat folder yang berisi database yang diekspor di Konsol Google Cloud, buka browser Cloud Storage dan pilih bucket yang Anda pilih sebelumnya:

Buka browser Cloud Storage

Bucket ini kini berisi folder dengan database yang diekspor di dalamnya. Nama folder diawali dengan ID instance, nama database, dan stempel waktu tugas ekspor Anda. Folder tersebut berisi:

• File spanner-export.json
• File TableName-manifest.json untuk setiap tabel dalam database yang Anda ekspor.

• Satu atau beberapa file TableName.avro-#####-of-#####. Angka pertama dalam ekstensi .avro-#####-of-##### mewakili indeks file Avro, yang dimulai dari nol, dan angka kedua menunjukkan jumlah file Avro yang dihasilkan untuk setiap tabel.

  Misalnya, Songs.avro-00001-of-00002 adalah file kedua dari dua file yang berisi data untuk tabel Songs.

• File ChangeStreamName-manifest.json untuk setiap aliran perubahan dalam database yang Anda ekspor.

• File ChangeStreamName.avro-00000-of-00001 untuk setiap aliran perubahan. File ini berisi data kosong yang hanya berisi skema Avro dari aliran data perubahan.

Pilih region untuk tugas impor Anda

Sebaiknya pilih region yang berbeda berdasarkan lokasi bucket Cloud Storage. Untuk menghindari biaya transfer data keluar, pilih region yang cocok dengan lokasi bucket Cloud Storage Anda.

• Jika lokasi bucket Cloud Storage adalah region, Anda dapat memanfaatkan penggunaan jaringan gratis dengan memilih region yang sama untuk tugas impor, dengan asumsi bahwa region tersebut tersedia.

• Jika lokasi bucket Cloud Storage Anda adalah dual-region, Anda dapat memanfaatkan penggunaan jaringan gratis dengan memilih salah satu dari dua region yang membentuk region ganda untuk tugas impor, dengan asumsi salah satu region tersedia.

• Jika region yang ditempatkan bersama tidak tersedia untuk tugas impor Anda, atau jika lokasi bucket Cloud Storage Anda adalah multi-region, biaya transfer data keluar akan berlaku. Lihat harga transfer data Cloud Storage untuk memilih region yang dikenai biaya transfer data terendah.

Mengekspor subset tabel

Jika Anda hanya ingin mengekspor data dari tabel tertentu, bukan seluruh database, Anda dapat menentukan tabel tersebut selama ekspor. Dalam hal ini, Spanner mengekspor seluruh skema database, termasuk data tabel yang Anda tentukan, dan membiarkan semua tabel lainnya ada, tetapi kosong di file yang diekspor.

Anda dapat menentukan subset tabel yang akan diekspor menggunakan halaman Dataflow di Konsol Google Cloud atau command line. (Halaman Spanner tidak menyediakan tindakan ini.)

Jika Anda mengekspor data tabel yang merupakan turunan tabel lain, Anda juga harus mengekspor data tabel parent-nya. Jika induk tidak diekspor, tugas ekspor akan gagal.

Untuk mengekspor subset tabel, mulailah ekspor menggunakan template Spanner ke Cloud Storage Avro Dataflow, lalu tentukan tabel menggunakan halaman Dataflow di Konsol Google Cloud atau Google Cloud CLI, seperti yang dijelaskan di bawah ini:

Konsol Google Cloud

Jika Anda menggunakan halaman Dataflow di Konsol Google Cloud, parameter Cloud Spanner Table name(s) terletak di bagian Optional parameter pada halaman Create job from template. Beberapa tabel dapat ditentukan dengan format yang dipisahkan koma.

gcloud CLI

Jika Anda menggunakan Google Cloud CLI, gunakan argumen tableNames untuk menentukan tabel. Contoh:

gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='instanceId=test-instance,databaseId=example-db,tableNames=table1,outputDir=gs://my-gcs-bucket' \
--max-workers=10

Menentukan beberapa tabel di gcloud memerlukan escape argumen jenis kamus. Contoh berikut menggunakan '|' sebagai karakter escape:

 gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='^|^instanceId=test-instance|databaseId=example-db|tableNames=table1,table2|outputDir=gs://my-gcs-bucket' \
--max-workers=10

Parameter shouldExportRelatedTables adalah opsi yang mudah untuk mengekspor semua tabel induk dari tabel yang diinginkan secara otomatis. Misalnya, dalam hierarki skema ini dengan tabel Singers, Albums, dan Songs, kita hanya perlu menentukan Songs. Opsi shouldExportRelatedTables juga akan mengekspor Singers dan Albums karena Songs adalah turunan dari keduanya.

gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='instanceId=test-instance,databaseId=example-db,tableNames=Songs,shouldExportRelatedTables=true,outputDir=gs://my-gcs-bucket' \
--max-workers=10

Melihat atau memecahkan masalah tugas di UI Dataflow

Setelah memulai tugas ekspor, Anda dapat melihat detail tugas tersebut, termasuk log, di bagian Dataflow pada Konsol Google Cloud.

Melihat detail tugas Dataflow

Untuk melihat detail tugas impor/ekspor yang Anda jalankan dalam seminggu terakhir, termasuk tugas yang sedang berjalan:

1. Buka halaman Database overview untuk database tersebut.
2. Klik item menu panel kiri Import/Export. Halaman Import/Export database menampilkan daftar tugas terbaru.

3. Di halaman Import/Export database, klik nama tugas di kolom Dataflow job name:

   

   Konsol Google Cloud menampilkan detail tugas Dataflow.

Untuk melihat tugas yang Anda jalankan lebih dari satu minggu yang lalu:

1. Buka halaman tugas Dataflow di konsol Google Cloud.

   Buka halaman lowongan

2. Temukan pekerjaan Anda di daftar, lalu klik namanya.

   Konsol Google Cloud menampilkan detail tugas Dataflow.

Catatan: Tugas dengan jenis yang sama untuk database yang sama memiliki nama yang sama. Anda dapat membedakan tugas berdasarkan nilainya di kolom Start time atau End time.

Melihat log Dataflow untuk tugas Anda

Untuk melihat log tugas Dataflow, buka halaman detail tugas seperti yang dijelaskan di atas, lalu klik Logs di sebelah kanan nama tugas.

Jika tugas gagal, cari error di log. Jika ada error, jumlah error akan ditampilkan di samping Logs:

Untuk melihat error tugas:

1. Klik jumlah error di sebelah Logs.

   Konsol Google Cloud menampilkan log tugas. Anda mungkin perlu men-scroll untuk melihat error.

2. Temukan entri dengan ikon error .

3. Klik entri log individual untuk meluaskan kontennya.

Untuk mengetahui informasi selengkapnya tentang memecahkan masalah tugas Dataflow, lihat Memecahkan masalah pipeline Anda.

Memecahkan masalah tugas ekspor yang gagal

Jika Anda melihat error berikut di log tugas:

com.google.cloud.spanner.SpannerException: NOT_FOUND: Session not found

--or--

com.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDED: Deadline expired before operation could complete.

Periksa 99% Latensi baca di tab Monitoring dalam database Spanner Anda di Google Cloud Console. Jika instance menampilkan nilai tinggi (beberapa detik), artinya instance kelebihan beban, yang menyebabkan waktu tunggu habis dan gagal dilakukan.

Salah satu penyebab latensi tinggi adalah tugas Dataflow yang berjalan menggunakan terlalu banyak pekerja, sehingga menempatkan terlalu banyak beban pada instance Spanner.

Untuk menentukan batas jumlah pekerja Dataflow, daripada menggunakan tab Import/Export di halaman detail instance database Spanner di Google Cloud Console, Anda harus memulai ekspor menggunakan Dataflow template Cloud Spanner ke Cloud Storage Avro dan menentukan jumlah maksimum worker seperti yang dijelaskan di bawah:

• Jika Anda menggunakan konsol Dataflow, parameter Max worker terletak di bagian Parameter opsional di halaman Create job from template.

• Jika Anda menggunakan gcloud, tentukan argumen max-workers. Contoh:

  gcloud dataflow jobs run my-export-job \
  --gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
  --region=us-central1 \
  --parameters='instanceId=test-instance,databaseId=example-db,outputDir=gs://my-gcs-bucket' \
  --max-workers=10
  

Mengoptimalkan tugas ekspor yang berjalan lambat

Jika telah mengikuti saran di setelan awal, biasanya Anda tidak perlu melakukan penyesuaian lainnya. Jika tugas Anda berjalan lambat, ada beberapa pengoptimalan lain yang dapat Anda coba:

• Mengoptimalkan tugas dan lokasi data: Jalankan tugas Dataflow di region yang sama tempat instance Spanner dan bucket Cloud Storage berada.

• Pastikan resource Dataflow yang memadai: Jika kuota Compute Engine yang relevan membatasi resource tugas Dataflow Anda, halaman Dataflow tugas di Konsol Google Cloud akan menampilkan ikon peringatan dan pesan log:

  

  Dalam situasi ini, meningkatkan kuota CPU, alamat IP yang sedang digunakan, dan persistent disk standar dapat mempersingkat waktu proses tugas, tetapi Anda mungkin dikenai lebih banyak biaya Compute Engine.

• Periksa pemakaian CPU Spanner: Jika pemakaian CPU untuk instance melebihi 65%, Anda dapat meningkatkan kapasitas komputasi dalam instance tersebut. Kapasitas tersebut menambahkan lebih banyak resource Spanner dan tugas akan dipercepat, tetapi biaya Spanner Anda akan lebih besar.

Faktor yang memengaruhi performa tugas ekspor

Beberapa faktor memengaruhi waktu yang diperlukan untuk menyelesaikan tugas ekspor.

• Ukuran database Spanner: Pemrosesan data yang lebih banyak memerlukan lebih banyak waktu dan resource.

• Skema database Spanner, termasuk:

  • Jumlah tabel
  • Ukuran baris
  • Jumlah indeks sekunder
  • Jumlah {i>foreign key<i}
  • Jumlah aliran perubahan

• Lokasi data: Data ditransfer antara Spanner dan Cloud Storage menggunakan Dataflow. Idealnya, ketiga komponen tersebut berada di region yang sama. Jika komponen tidak berada di region yang sama, memindahkan data lintas region akan memperlambat tugas.

• Jumlah pekerja Dataflow: Pekerja Dataflow yang optimal diperlukan untuk mendapatkan performa yang baik. Dengan menggunakan penskalaan otomatis, Dataflow akan memilih jumlah pekerja untuk tugas, bergantung pada jumlah pekerjaan yang perlu dilakukan. Namun, jumlah pekerja akan dibatasi oleh kuota CPU, alamat IP yang sedang digunakan, dan persistent disk standar. UI Dataflow menampilkan ikon peringatan jika mengalami batas kuota. Dalam situasi ini, progresnya lebih lambat, tetapi tugas seharusnya tetap dapat diselesaikan.

• Pemuatan yang ada di Spanner: Tugas ekspor biasanya menambahkan beban ringan pada instance Spanner. Jika instance sudah memiliki beban yang cukup substansial, tugas akan berjalan lebih lambat.

• Jumlah kapasitas komputasi Spanner: Jika penggunaan CPU untuk instance lebih dari 65%, tugas akan berjalan lebih lambat.