Mengekspor database dari Spanner ke Avro

Halaman ini menjelaskan cara mengekspor database Spanner dengan Google Cloud konsol.

Untuk mengekspor database Spanner menggunakan REST API atau Google Cloud CLI, 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:

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

Aktifkan API

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

Persyaratan kuota

Persyaratan kuota untuk tugas ekspor adalah sebagai berikut:

• Spanner: Tidak ada kapasitas komputasi tambahan yang diperlukan untuk mengekspor database, meskipun Anda mungkin perlu menambahkan kapasitas komputasi agar tugas Anda selesai dalam 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 Google Cloud konsol, baik melalui halaman Cloud Storage atau saat membuat ekspor melalui halaman Spanner. Anda tidak perlu menetapkan ukuran untuk bucket.
• Dataflow: Tugas ekspor tunduk pada kuota Compute Engine yang sama untuk CPU, penggunaan disk, dan alamat IP seperti tugas Dataflow lainnya.

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

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

  Umumnya, Anda tidak perlu melakukan penyesuaian lainnya. Dataflow menyediakan penskalaan otomatis sehingga Anda hanya membayar resource aktual 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.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk mengekspor database, minta administrator untuk memberi Anda peran IAM berikut di akun layanan worker Dataflow Anda:

• Cloud Spanner Viewer (roles/spanner.viewer)
• Dataflow Worker (roles/dataflow.worker)
• Storage Admin (roles/storage.admin)
• Spanner Database Reader (roles/spanner.databaseReader)
• Database Admin (roles/spanner.databaseAdmin)

Catatan: Peran Spanner Database Admin 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. Namun, perubahan apa pun yang Anda buat setelah Dataflow membuat transaksi Spanner tidak akan dicatat 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 Instances Spanner.

   Buka 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 Choose where to store your export, klik Browse.

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

   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 Create.
   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 Select.

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

8. Opsional: Untuk mengekspor database Anda dari waktu sebelumnya, centang kotak dan 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 Memilih region.

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

    1. Klik Show encryption options.
    2. Pilih Use a customer-managed encryption key (CMEK).
    3. Pilih kunci Anda dari menu drop-down.

    Opsi ini tidak memengaruhi enkripsi tingkat bucket Cloud Storage tujuan. Untuk 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. Centang kotak di bagian Confirm charges untuk mengonfirmasi bahwa ada biaya selain yang ditagih oleh instance Spanner Anda yang ada.

13. Klik Export.

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

    

Saat tugas selesai atau dihentikan, status akan diperbarui dalam daftar Import/Export. Jika tugas berhasil, status Succeeded akan ditampilkan:

Jika tugas gagal, status Failed 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.

Untuk menghindari biaya Cloud Storage untuk file yang dibuat oleh tugas ekspor yang gagal, hapus folder dan filenya. Lihat Melihat ekspor Anda untuk mengetahui informasi tentang cara menemukan folder.

Catatan tentang mengekspor kolom yang dibuat dan aliran perubahan

Nilai dalam kolom yang dibuat tersimpan tidak diekspor. Definisi kolom diekspor ke skema Avro sebagai kolom data jenis null, dengan definisi kolom sebagai properti kustom kolom. Hingga operasi backfill kolom yang dibuat yang baru ditambahkan selesai, kolom yang dibuat akan diabaikan seolah-olah tidak ada dalam skema.

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

Catatan tentang mengekspor urutan

Urutan (GoogleSQL, PostgreSQL) adalah objek skema yang Anda gunakan untuk membuat nilai bilangan bulat unik. Spanner mengekspor setiap objek skema ke skema Avro sebagai kolom data, dengan jenis urutan, rentang yang dilewati, dan penghitung sebagai properti kolom. Perhatikan bahwa untuk mencegah urutan direset dan membuat nilai duplikat setelah impor, selama ekspor skema, fungsi GET_INTERNAL_SEQUENCE_STATE() (GoogleSQL, PostgreSQL) akan mengambil penghitung urutan. Spanner menambahkan buffer 1000 ke penghitung, dan menulis nilai penghitung baru ke kolom 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 sebenarnya menggunakan pernyataan ALTER SEQUENCE (GoogleSQL, PostgreSQL) .

Saat impor, 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 Google Cloud konsol, buka browser Cloud Storage dan pilih bucket yang Anda pilih sebelumnya:

Buka browser Cloud Storage

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

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

• Satu atau beberapa TableName.avro-#####-of-##### file. Angka pertama dalam ekstensi .avro-#####-of-##### mewakili indeks file Avro, dimulai dari nol, dan angka kedua mewakili jumlah file Avro yang dibuat 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 di database yang Anda ekspor.

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

Memilih region untuk tugas impor

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

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

• Jika lokasi bucket Cloud Storage Anda adalah region ganda, 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 sama 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 data transfer untuk memilih region yang dikenai biaya transfer data terendah.

Mengekspor subset tabel

Jika hanya ingin mengekspor data dari tabel tertentu, dan 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 dalam file yang diekspor.

Anda dapat menentukan subset tabel untuk diekspor menggunakan halaman Dataflow di Google Cloud konsol atau gcloud CLI. (Halaman Spanner tidak menyediakan tindakan ini.)

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

Untuk mengekspor subset tabel, mulai ekspor menggunakan template Spanner ke Cloud Storage Avro Dataflow, dan tentukan tabel menggunakan halaman Dataflow di konsol Google Cloud atau menggunakan gcloud CLI, seperti yang dijelaskan:

Konsol

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

Buka Dataflow

gcloud

Jalankan perintah gcloud dataflow jobs run, dan tentukan argumen tableNames. 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 \
--network=network-123

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 \
--network=network-123

Parameter shouldExportRelatedTables adalah opsi praktis untuk mengekspor semua tabel induk dari tabel yang dipilih secara otomatis. Misalnya, dalam hierarki skema ini dengan tabel Singers, Albums dan Songs, Anda 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 \
--network=network-123

Melihat atau memecahkan masalah tugas di UI Dataflow

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

Melihat detail tugas Dataflow

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

1. Buka halaman Database overview untuk database.
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 menampilkan detail tugas Dataflow . Google Cloud

Untuk melihat tugas yang Anda jalankan lebih dari seminggu yang lalu:

1. Buka halaman tugas Dataflow di Google Cloud konsol.

   Buka Tugas

2. Temukan tugas Anda dalam daftar, lalu klik namanya.

   Konsol menampilkan detail tugas Dataflow . Google Cloud

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

Melihat log Dataflow untuk tugas Anda

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

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

Untuk melihat error tugas:

1. Klik jumlah error di samping Logs.

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

2. Temukan entri dengan ikon error .

3. Klik setiap entri log untuk meluaskan kontennya.

Untuk mengetahui informasi selengkapnya tentang cara 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% Read latency di tabMonitoring database Spanner Anda di Google Cloud konsol. Jika menampilkan nilai tinggi (beberapa detik), maka ini menunjukkan bahwa instance kelebihan beban, menyebabkan pembacaan mengalami error dan gagal.

Salah satu penyebab latensi tinggi adalah tugas Dataflow berjalan menggunakan terlalu banyak worker, sehingga memberikan terlalu banyak beban pada instance Spanner.

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

Konsol

Jika Anda menggunakan konsol Dataflow, parameter Max workers terletak di bagian Optional parameters halaman Create job from template.

Buka Dataflow

gcloud

Jalankan perintah gcloud dataflow jobs run, dan 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 \
    --network=network-123

Memecahkan masalah error jaringan

Error berikut mungkin terjadi saat Anda mengekspor database Spanner:

Workflow failed. Causes: Error: Message: Invalid value for field
'resource.properties.networkInterfaces[0].subnetwork': ''. Network interface
must specify a subnet if the network resource is in custom subnet mode.
HTTP Code: 400

Error ini terjadi karena Spanner mengasumsikan bahwa Anda ingin menggunakan jaringan VPC mode otomatis bernama default di project yang sama dengan tugas Dataflow. Jika Anda tidak memiliki jaringan VPC default di project, atau jika jaringan VPC Anda berada di jaringan VPC mode kustom, Anda harus membuat tugas Dataflow dan menentukan jaringan atau subnetwork alternatif.

Mengoptimalkan tugas ekspor yang berjalan lambat

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

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

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

  

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

• Memeriksa pemakaian CPU Spanner: Jika Anda melihat bahwa pemakaian CPU untuk instance lebih dari 65%, Anda dapat meningkatkan kapasitas komputasi di instance tersebut. Kapasitas ini akan menambahkan lebih banyak resource Spanner dan tugas akan dipercepat, tetapi Anda akan dikenai lebih banyak biaya Spanner.

Faktor yang memengaruhi performa tugas ekspor

Beberapa faktor memengaruhi waktu yang diperlukan untuk menyelesaikan tugas ekspor.

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

• Skema database Spanner, termasuk:

  • Jumlah tabel
  • Ukuran baris
  • Jumlah indeks sekunder
  • Jumlah kunci asing
  • Jumlah aliran perubahan

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

• Jumlah worker Dataflow: Worker Dataflow yang optimal diperlukan untuk performa yang baik. Dengan menggunakan penskalaan otomatis, Dataflow memilih jumlah worker untuk tugas, bergantung pada jumlah pekerjaan yang perlu dilakukan. Namun, jumlah worker akan dibatasi oleh kuota untuk CPU, alamat IP yang digunakan, dan persistent disk standar. UI Dataflow menampilkan ikon peringatan jika menemukan batas kuota. Dalam situasi ini, progres lebih lambat, tetapi tugas akan tetap selesai.

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

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