Halaman ini menjelaskan cara menyiapkan file Avro yang Anda ekspor dari database non-Spanner, lalu mengimpor file tersebut ke Spanner. Prosedur ini mencakup informasi untuk database dialek GoogleSQL dan database dialek PostgreSQL. Jika Anda ingin mengimpor database Spanner yang sebelumnya diekspor, lihat Mengimpor file Avro Spanner.
Proses ini menggunakan Dataflow; proses ini mengimpor data dari bucket Cloud Storage yang berisi serangkaian file Avro dan file manifes JSON yang menentukan tabel tujuan dan file Avro yang mengisi setiap tabel.
Sebelum memulai
Untuk mengimpor database Spanner, Anda harus mengaktifkan Spanner, Cloud Storage, Compute Engine, dan Dataflow API terlebih dahulu:
Anda juga memerlukan kuota yang cukup dan izin IAM yang diperlukan.
Persyaratan kuota
Persyaratan kuota untuk tugas impor adalah sebagai berikut:
- Spanner: Anda harus memiliki kapasitas komputasi yang cukup untuk mendukung jumlah data yang Anda impor. Tidak ada kapasitas komputasi tambahan yang diperlukan untuk mengimpor 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 mengimpor, Anda harus memiliki bucket yang berisi file yang sebelumnya diekspor. Anda tidak perlu menetapkan ukuran untuk bucket.
- Dataflow: Tugas impor tunduk pada CPU, penggunaan disk, dan kuota Compute Engine alamat IP yang sama dengan tugas Dataflow lainnya.
Compute Engine: Sebelum menjalankan tugas impor, Anda harus menyiapkan kuota awal untuk Compute Engine, yang digunakan Dataflow. Kuota ini mewakili jumlah maksimum resource yang Anda izinkan Dataflow untuk digunakan bagi 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 lain. Dataflow menyediakan penskalaan otomatis sehingga Anda hanya membayar resource aktual yang digunakan selama impor. 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 pada akun layanan worker Dataflow:
-
Cloud Spanner Viewer (
roles/spanner.viewer
) -
Dataflow Worker (
roles/dataflow.worker
) -
Storage Admin (
roles/storage.admin
) -
Pembaca Database Spanner (
roles/spanner.databaseReader
) -
Database Admin (
roles/spanner.databaseAdmin
)
Mengekspor data dari database non-Spanner ke file Avro
Proses impor akan memasukkan data dari file Avro yang berada di bucket Cloud Storage. Anda dapat mengekspor data dalam format Avro dari sumber mana pun dan dapat menggunakan metode yang tersedia untuk melakukannya.
Untuk mengekspor data dari database non-Spanner ke file Avro, ikuti langkah-langkah berikut:
Perhatikan hal-hal berikut saat mengekspor data Anda:
- Anda dapat mengekspor menggunakan salah satu jenis primitif Avro serta jenis kompleks array.
Setiap kolom dalam file Avro harus menggunakan salah satu jenis kolom berikut:
ARRAY
BOOL
BYTES
*DOUBLE
FLOAT
INT
LONG
†STRING
‡
* Kolom jenis
BYTES
digunakan untuk mengimporNUMERIC
Spanner; lihat bagian pemetaan yang direkomendasikan berikut untuk mengetahui detailnya.†,‡ Anda dapat mengimpor
LONG
yang menyimpan stempel waktu atauSTRING
yang menyimpan stempel waktu sebagaiTIMESTAMP
Spanner; lihat bagian pemetaan yang direkomendasikan berikut untuk mengetahui detailnya.Anda tidak perlu menyertakan atau membuat metadata apa pun saat mengekspor file Avro.
Anda tidak harus mengikuti konvensi penamaan tertentu untuk file Anda.
Jika Anda tidak mengekspor file secara langsung ke Cloud Storage, Anda harus mengupload file Avro ke bucket Cloud Storage. Untuk mengetahui petunjuk mendetail, lihat Mengupload objek ke Cloud Storage Anda.
Mengimpor file Avro dari database non-Spanner ke Spanner
Untuk mengimpor file Avro dari database non-Spanner ke Spanner, ikuti langkah-langkah berikut:
- Buat tabel target dan tentukan skema untuk database Spanner Anda.
- Buat file
spanner-export.json
di bucket Cloud Storage Anda. - Jalankan tugas impor Dataflow menggunakan gcloud CLI.
Langkah 1: Buat skema untuk database Spanner Anda
Sebelum menjalankan impor, Anda harus membuat tabel target di Spanner dan menentukan skemanya.
Anda harus membuat skema yang menggunakan jenis kolom yang sesuai untuk setiap kolom dalam file Avro.
Pemetaan yang direkomendasikan
GoogleSQL
Jenis kolom Avro | Jenis kolom Spanner |
---|---|
ARRAY |
ARRAY |
BOOL |
BOOL |
BYTES |
|
DOUBLE |
FLOAT64 |
FLOAT |
FLOAT64 |
INT |
INT64 |
LONG |
|
STRING |
|
PostgreSQL
Jenis kolom Avro | Jenis kolom Spanner |
---|---|
ARRAY |
ARRAY |
BOOL |
BOOLEAN |
BYTES |
|
DOUBLE |
DOUBLE PRECISION |
FLOAT |
DOUBLE PRECISION |
INT |
BIGINT |
LONG |
|
STRING |
|
Langkah 2: Buat file spanner-export.json
Anda juga harus membuat file bernama spanner-export.json
di bucket Cloud Storage. File ini menentukan dialek database dan
berisi array tables
yang mencantumkan
nama dan lokasi file data untuk setiap tabel.
Isi file memiliki format berikut:
{ "tables": [ { "name": "TABLE1", "dataFiles": [ "RELATIVE/PATH/TO/TABLE1_FILE1", "RELATIVE/PATH/TO/TABLE1_FILE2" ] }, { "name": "TABLE2", "dataFiles": ["RELATIVE/PATH/TO/TABLE2_FILE1"] } ], "dialect":"DATABASE_DIALECT" }
Dengan DATABASE_DIALECT = {GOOGLE_STANDARD_SQL
| POSTGRESQL
}
Jika elemen dialek tidak disertakan, dialek akan ditetapkan secara default ke
GOOGLE_STANDARD_SQL
.
Langkah 3: Jalankan tugas impor Dataflow menggunakan gcloud CLI
Untuk memulai tugas impor, ikuti petunjuk penggunaan Google Cloud CLI untuk menjalankan tugas dengan template Avro ke Spanner.
Setelah memulai tugas impor, Anda dapat melihat detail tentang tugas tersebut di konsol Google Cloud .
Setelah tugas impor selesai, tambahkan indeks sekunder dan kunci asing yang diperlukan.
Pilih region untuk tugas impor Anda
Anda mungkin ingin memilih region lain berdasarkan lokasi bucket Cloud Storage Anda. Untuk menghindari biaya transfer data keluar, pilih region yang cocok dengan lokasi bucket Cloud Storage Anda.
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 Anda, 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 menimbulkan biaya transfer data terendah.
Melihat atau memecahkan masalah tugas di UI Dataflow
Setelah memulai tugas impor, Anda dapat melihat detail tugas, termasuk log, di bagian Dataflow pada konsol Google Cloud .
Melihat detail tugas Dataflow
Untuk melihat detail tugas impor atau ekspor yang Anda jalankan dalam seminggu terakhir, termasuk tugas yang sedang berjalan:
- Buka halaman Ringkasan database untuk database.
- Klik item menu panel kiri Impor/Ekspor. Halaman Import/Export database menampilkan daftar tugas terbaru.
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:
Buka halaman tugas Dataflow di konsol Google Cloud .
Temukan tugas Anda dalam daftar, lalu klik namanya.
Konsol Google Cloud menampilkan detail tugas Dataflow.
Melihat log Dataflow untuk tugas Anda
Untuk melihat log tugas Dataflow, buka halaman detail tugas, lalu klik Log di sebelah kanan nama tugas.
Jika tugas gagal, cari error di log. Jika ada error, jumlah error akan ditampilkan di samping Log:
Untuk melihat error tugas:
Klik jumlah error di samping Log.
Konsol Google Cloud menampilkan log tugas. Anda mungkin perlu men-scroll untuk melihat error.
Temukan entri dengan ikon error
.
Klik setiap entri log untuk meluaskan isinya.
Untuk mengetahui informasi selengkapnya tentang cara memecahkan masalah tugas Dataflow, lihat Memecahkan masalah pipeline.
Memecahkan masalah tugas impor 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 Latensi penulisan 99% di tab Monitoring pada database Spanner Anda di konsol Google Cloud . Jika menunjukkan nilai yang tinggi (beberapa detik), berarti instance kelebihan beban, sehingga penulisan akan mengalami waktu tunggu habis dan gagal.
Salah satu penyebab latensi tinggi adalah tugas Dataflow berjalan menggunakan terlalu banyak pekerja, sehingga memberikan terlalu banyak beban pada instance Spanner.
Untuk menentukan batas jumlah pekerja Dataflow, alih-alih menggunakan tab Impor/Ekspor di halaman detail instance database Spanner Anda di konsol Google Cloud , Anda harus memulai impor menggunakan template Cloud Storage Avro ke Spanner Dataflow dan menentukan jumlah maksimum pekerja seperti yang dijelaskan:Konsol
Jika Anda menggunakan konsol Dataflow, parameter Pekerja maks berada di bagian Parameter opsional pada halaman Buat tugas dari template.
gcloud
Jalankan perintah gcloud dataflow jobs run
dan tentukan argumen max-workers
. Contoh:
gcloud dataflow jobs run my-import-job \
--gcs-location='gs://dataflow-templates/latest/GCS_Avro_to_Cloud_Spanner' \
--region=us-central1 \
--parameters='instanceId=test-instance,databaseId=example-db,inputDir=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 bermaksud menggunakan
jaringan VPC mode otomatis bernama default
dalam project yang sama dengan
job 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 impor yang berjalan lambat
Jika telah mengikuti saran di setelan awal, Anda umumnya tidak perlu melakukan penyesuaian lain. 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.
Pastikan resource Dataflow mencukupi: 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 sedang digunakan, dan persistent disk standar dapat memperpendek waktu proses tugas, tetapi Anda mungkin dikenai lebih banyak biaya Compute Engine.
Periksa pemakaian CPU Spanner: Jika Anda melihat bahwa pemakaian CPU untuk instance melebihi 65%, Anda dapat meningkatkan kapasitas komputasi di instance tersebut. Kapasitas akan menambahkan lebih banyak resource Spanner dan tugas akan berjalan lebih cepat, tetapi Anda akan dikenai lebih banyak biaya Spanner.
Faktor yang memengaruhi performa tugas impor
Beberapa faktor memengaruhi waktu yang diperlukan untuk menyelesaikan tugas impor.
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 data 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, pemindahan 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 pekerja untuk tugas bergantung pada jumlah pekerjaan yang perlu dilakukan. Namun, jumlah pekerja akan dibatasi oleh kuota untuk CPU, alamat IP yang sedang 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. Penskalaan otomatis dapat membebani Spanner secara berlebihan sehingga menyebabkan error saat ada banyak data yang akan diimpor.
Beban yang ada di Spanner: Tugas impor menambahkan beban CPU yang signifikan pada instance Spanner. Jika instance sudah memiliki beban yang cukup besar, tugas akan berjalan lebih lambat.
Jumlah kapasitas komputasi Spanner: Jika penggunaan CPU untuk instance lebih dari 65%, maka tugas akan berjalan lebih lambat.
Menyesuaikan pekerja untuk performa impor yang baik
Saat memulai tugas impor Spanner, pekerja Dataflow harus ditetapkan ke nilai yang optimal untuk performa yang baik. Terlalu banyak pekerja akan membebani Spanner dan terlalu sedikit pekerja akan menghasilkan performa impor yang kurang memuaskan.
Jumlah maksimum pekerja sangat bergantung pada ukuran data, tetapi idealnya, total pemakaian CPU Spanner harus antara 70% hingga 90%. Hal ini memberikan keseimbangan yang baik antara efisiensi Spanner dan penyelesaian tugas tanpa error.
Untuk mencapai target pemanfaatan tersebut di sebagian besar skema dan skenario, sebaiknya jumlah vCPU pekerja maksimum antara 4-6x jumlah node Spanner.
Misalnya, untuk instance Spanner 10 node, menggunakan pekerja n1-standard-2, Anda akan menetapkan pekerja maks ke 25, sehingga memberikan 50 vCPU.