Memuat data PostgreSQL ke BigQuery

Untuk menjadwalkan transfer data berulang dari PostgreSQL ke BigQuery, Anda dapat membuat konfigurasi transfer untuk menentukan objek data yang akan ditransfer, dan seberapa sering menjadwalkan transfer data. Setelah Anda menyiapkan konfigurasi transfer, BigQuery Data Transfer Service akan mentransfer data terbaru ke tabel BigQuery sesuai jadwal yang ditentukan.

Untuk mengetahui informasi umum tentang transfer PostgreSQL, termasuk opsi konfigurasi, lihat Pengantar transfer data PostgreSQL.

Batasan

Transfer data PostgreSQL tunduk pada batasan berikut:

  • Jumlah maksimum transfer yang berjalan secara bersamaan ke satu database PostgreSQL ditentukan oleh jumlah maksimum koneksi serentak yang didukung oleh database PostgreSQL. Jumlah tugas transfer serentak harus dibatasi hingga nilai yang lebih kecil dari jumlah maksimum koneksi serentak yang didukung oleh database PostgreSQL.

  • Satu konfigurasi transfer hanya dapat mendukung satu kali menjalankan transfer data dalam waktu tertentu. Jika transfer data kedua dijadwalkan untuk berjalan sebelum transfer pertama selesai, maka hanya transfer data pertama yang selesai, sementara transfer data lain yang tumpang-tindih dengan transfer pertama akan dilewati.

    Untuk menghindari transfer yang dilewati dalam satu konfigurasi transfer, sebaiknya Anda meningkatkan durasi waktu antara transfer data besar dengan mengonfigurasi frekuensi pengulangan.

  • Selama transfer data, konektor PostgreSQL mengidentifikasi kolom kunci yang diindeks dan dipartisi untuk mentransfer data Anda dalam batch paralel. Oleh karena itu, sebaiknya tentukan kolom kunci utama atau gunakan kolom yang diindeks dalam tabel untuk meningkatkan performa dan mengurangi tingkat error dalam transfer data. Pertimbangkan hal berikut:

    • Jika Anda memiliki batasan indeks atau kunci utama, hanya jenis kolom berikut yang didukung untuk membuat batch paralel:
      • INTEGER
      • TINYINT
      • SMALLINT
      • FLOAT
      • REAL
      • DOUBLE
      • NUMERIC
      • BIGINT
      • DECIMAL
      • DATE
    • Transfer data PostgreSQL yang tidak menggunakan kunci utama atau kolom berindeks tidak dapat mendukung lebih dari 2.000.000 record per tabel.

Batasan transfer inkremental

Transfer PostgreSQL inkremental tunduk pada batasan berikut:

  • Anda hanya dapat memilih TIMESTAMP kolom sebagai kolom tanda air.
  • Penyerapan inkremental hanya didukung untuk aset dengan kolom watermark yang valid.
  • Nilai dalam kolom tanda air harus meningkat secara monoton.
  • Transfer inkremental tidak dapat menyinkronkan operasi penghapusan di tabel sumber.
  • Konfigurasi transfer tunggal hanya dapat mendukung penyerapan inkremental atau penuh.
  • Anda tidak dapat memperbarui objek dalam daftar asset setelah menjalankan penyerapan inkremental pertama.
  • Anda tidak dapat mengubah mode penulisan dalam konfigurasi transfer setelah menjalankan penyerapan inkremental pertama.
  • Anda tidak dapat mengubah kolom tanda air atau kunci utama setelah menjalankan penyerapan inkremental pertama.
  • Tabel BigQuery tujuan dikelompokkan menggunakan kunci utama yang diberikan dan tunduk pada batasan tabel berklaster.

  • Saat Anda memperbarui konfigurasi transfer yang ada ke mode penyerapan inkremental untuk pertama kalinya, transfer data pertama setelah pembaruan tersebut akan mentransfer semua data yang tersedia dari sumber data Anda. Setiap transfer data inkremental berikutnya hanya akan mentransfer baris baru dan yang diperbarui dari sumber data Anda.

  • Sebaiknya buat indeks pada kolom tanda air. Konektor ini menggunakan kolom tanda air untuk filter dalam transfer inkremental, sehingga pengindeksan kolom ini dapat meningkatkan performa.

  • Saat melakukan transfer inkremental, Anda harus menggunakan pemetaan jenis data yang diperbarui.

Sebelum memulai

Peran yang diperlukan

Jika ingin menyiapkan notifikasi operasi transfer untuk Pub/Sub, pastikan Anda memiliki izin Identity and Access Management (IAM) pubsub.topics.setIamPolicy. Izin Pub/Sub tidak diperlukan jika Anda hanya menyiapkan notifikasi email. Untuk informasi selengkapnya, lihat Notifikasi operasi BigQuery Data Transfer Service.

Untuk mendapatkan izin yang diperlukan guna membuat transfer data BigQuery Data Transfer Service, minta administrator untuk memberi Anda peran IAM BigQuery Admin (roles/bigquery.admin) di project Anda. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin yang diperlukan untuk membuat transfer data BigQuery Data Transfer Service. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk membuat transfer data BigQuery Data Transfer Service:

  • Izin BigQuery Data Transfer Service:
    • bigquery.transfers.update
    • bigquery.transfers.get
  • Izin BigQuery:
    • bigquery.datasets.get
    • bigquery.datasets.getIamPolicy
    • bigquery.datasets.update
    • bigquery.datasets.setIamPolicy
    • bigquery.jobs.create

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

Untuk mengetahui informasi selengkapnya, lihat Memberikan akses bigquery.admin.

Koneksi jaringan

Jika alamat IP publik tidak tersedia untuk koneksi database PostgreSQL, Anda harus menyiapkan lampiran jaringan.

Untuk petunjuk mendetail tentang penyiapan jaringan yang diperlukan, lihat dokumen berikut:

Menyiapkan transfer data PostgreSQL

Tambahkan data PostgreSQL ke BigQuery dengan menyiapkan konfigurasi transfer menggunakan salah satu opsi berikut:

Konsol

  1. Buka halaman Data transfers.

    Buka Data transfers

  2. Klik Create transfer.

  3. Di bagian Source type, untuk Source, pilih PostgreSQL.

  4. Di bagian Detail sumber data, lakukan hal berikut:

    • Untuk Network attachment, pilih network attachment yang ada atau klik Create Network Attachment. Untuk mengetahui informasi selengkapnya, lihat bagian Koneksi jaringan dalam dokumen ini.
    • Untuk Host, masukkan nama host atau alamat IP server database PostgreSQL.
    • Untuk Nomor port, masukkan nomor port untuk server database PostgreSQL.
    • Untuk Nama database, masukkan nama database PostgreSQL.
    • Untuk Nama Pengguna, masukkan nama pengguna PostgreSQL yang memulai koneksi database PostgreSQL.
    • Untuk Sandi, masukkan sandi pengguna PostgreSQL yang memulai koneksi database PostgreSQL.
    • Untuk TLS Mode, pilih opsi dari menu. Untuk mengetahui informasi selengkapnya tentang mode TLS, lihat Konfigurasi TLS.
    • Untuk Trusted PEM Certificate, masukkan sertifikat publik certificate authority (CA) yang menerbitkan sertifikat TLS server database. Untuk mengetahui informasi selengkapnya, lihat Sertifikat Server Tepercaya (PEM).
    • Untuk Aktifkan pemetaan lama, pilih benar (default) untuk menggunakan pemetaan jenis data lama. Pilih false untuk menggunakan pemetaan jenis data yang diperbarui. Jika Anda melakukan transfer inkremental, nilai ini harus false. Untuk mengetahui informasi selengkapnya tentang pembaruan pemetaan jenis data, lihat 16 Maret 2027. server database.
    • Untuk Ingestion type, pilih Full atau Incremental.
      • Jika Anda memilih Incremental (Pratinjau), untuk Write mode, pilih Append atau Upsert. Untuk mengetahui informasi selengkapnya tentang berbagai mode penulisan, lihat Transfer penuh atau inkremental.

    • Untuk Objek PostgreSQL yang akan ditransfer, klik Jelajahi.

      Pilih objek yang akan ditransfer ke set data tujuan BigQuery. Anda juga dapat memasukkan objek secara manual untuk disertakan dalam transfer data di kolom ini.

      • Jika Anda telah memilih Tambahkan sebagai mode penulisan inkremental, Anda harus memilih kolom sebagai kolom tanda air.
      • Jika Anda telah memilih Upsert sebagai mode penulisan inkremental, Anda harus memilih kolom sebagai kolom tanda air, lalu memilih satu atau beberapa kolom sebagai kunci utama.

  5. Di bagian Transfer config name, untuk Display name, masukkan nama untuk transfer. Nama transfer dapat berupa nilai apa pun yang memungkinkan Anda mengidentifikasi transfer jika perlu mengubahnya nanti.

  6. Di bagian Opsi jadwal, lakukan tindakan berikut:

    • Pilih frekuensi pengulangan. Jika memilih opsi Jam, Hari (default), Minggu, atau Bulan, Anda juga harus menentukan frekuensi. Anda juga dapat memilih opsi Kustom untuk membuat frekuensi pengulangan yang lebih spesifik. Jika Anda memilih opsi On-demand, transfer data ini hanya akan berjalan saat Anda memicu transfer secara manual.
    • Jika berlaku, pilih opsi Start now atau Start at a set time dan masukkan tanggal mulai dan waktu proses.

  7. Di bagian Destination settings, untuk Dataset, pilih set data yang Anda buat untuk menyimpan data Anda, atau klik Create new dataset dan buat set data untuk digunakan sebagai set data tujuan.

  8. Opsional: Di bagian Opsi notifikasi, lakukan hal berikut:

    • Untuk mengaktifkan notifikasi email, klik tombol Notifikasi email ke posisi aktif. Saat Anda mengaktifkan opsi ini, administrator transfer akan menerima notifikasi email saat proses transfer gagal.
    • Untuk mengonfigurasi notifikasi operasi Pub/Sub untuk transfer Anda, klik tombol Notifikasi Pub/Sub ke posisi aktif. Anda dapat memilih nama topik atau mengklik Buat topik untuk membuatnya.

  9. Klik Simpan.

bq

Masukkan perintah bq mk dan berikan flag pembuatan transfer --transfer_config:

bq mk
    --transfer_config
    --project_id=PROJECT_ID
    --data_source=DATA_SOURCE
    --display_name=DISPLAY_NAME
    --target_dataset=DATASET
    --params='PARAMETERS'

Ganti kode berikut:

  • PROJECT_ID (opsional): project ID Google Cloud Anda. Jika tanda --project_id tidak diberikan untuk menentukan project tertentu, project default akan digunakan.
  • DATA_SOURCE: sumber data, yaitu postgresql.
  • DISPLAY_NAME: nama tampilan untuk konfigurasi transfer data. Nama transfer dapat berupa nilai apa pun yang memungkinkan Anda mengidentifikasi transfer jika perlu mengubahnya nanti.
  • DATASET: set data target untuk konfigurasi transfer data.

  • PARAMETERS: parameter untuk konfigurasi transfer yang dibuat dalam format JSON. Contoh: --params='{"param":"param_value"}'. Berikut adalah parameter untuk transfer PostgreSQL:

    • connector.networkAttachment (opsional): nama lampiran jaringan untuk terhubung ke database PostgreSQL.
    • connector.database: nama database PostgreSQL.
    • connector.endpoint.host: nama host atau alamat IP database.
    • connector.endpoint.port: nomor port database.
    • connector.authentication.username: nama pengguna pengguna database.
    • connector.authentication.password: sandi pengguna database.
    • connector.tls.mode: tentukan konfigurasi TLS yang akan digunakan dengan transfer ini:
      • ENCRYPT_VERIFY_CA_AND_HOST untuk mengenkripsi data, dan memverifikasi CA dan nama host
      • ENCRYPT_VERIFY_CA untuk mengenkripsi data, dan hanya memverifikasi CA
      • ENCRYPT_VERIFY_NONE hanya untuk enkripsi data
      • DISABLE untuk tidak ada enkripsi atau verifikasi
    • connector.tls.trustedServerCertificate: (opsional) berikan satu atau beberapa sertifikat berenkode PEM. Hanya diperlukan jika connector.tls.mode adalah ENCRYPT_VERIFY_CA_AND_HOST atau ENCRYPT_VERIFY_CA.
    • ingestionType: tentukan full atau incremental. Transfer inkremental didukung dalam Pratinjau. Untuk mengetahui informasi selengkapnya, lihat Transfer penuh atau inkremental.
    • writeMode: tentukan WRITE_MODE_APPEND atau WRITE_MODE_UPSERT.
    • watermarkColumns: menentukan kolom dalam tabel Anda sebagai kolom watermark. Kolom ini wajib diisi untuk transfer inkremental.
    • primaryKeys: menentukan kolom dalam tabel Anda sebagai kunci utama. Kolom ini wajib diisi untuk transfer inkremental.
    • connector.legacyMapping: ditetapkan ke true (default) untuk menggunakan pemetaan jenis data lama. Tetapkan ke false untuk menggunakan pemetaan jenis data yang diperbarui. Jika Anda melakukan transfer inkremental, nilai ini harus false. Untuk mengetahui informasi selengkapnya tentang pembaruan pemetaan jenis data, lihat 16 Maret 2027.
    • assets: daftar nama tabel PostgreSQL yang akan ditransfer dari database PostgreSQL sebagai bagian dari transfer.

Misalnya, perintah berikut membuat transfer PostgreSQL bernama My Transfer:

bq mk
    --transfer_config
    --target_dataset=mydataset
    --data_source=postgresql
    --display_name='My Transfer'
    --params='{"assets":["DB1/PUBLIC/DEPARTMENT","DB1/PUBLIC/EMPLOYEES"],
        "connector.authentication.username": "User1",
        "connector.authentication.password":"ABC12345",
        "connector.database":"DB1",
        "connector.endpoint.host":"192.168.0.1",
        "connector.endpoint.port":5432,
        "ingestionType":"incremental",
        "writeMode":"WRITE_MODE_APPEND",
        "watermarkColumns":["createdAt","createdAt"],
        "primaryKeys":[['dep_id'], ['report_by','report_title']],
        "connector.tls.mode": "ENCRYPT_VERIFY_CA_AND_HOST",
        "connector.tls.trustedServerCertificate": "PEM-encoded certificate"}'

Saat Anda menentukan beberapa aset selama transfer inkremental, nilai kolom watermarkColumns dan primaryKeys sesuai dengan posisi nilai di kolom assets. Dalam contoh berikut, dep_id sesuai dengan tabel DB1/USER1/DEPARTMENT, sedangkan report_by dan report_title sesuai dengan tabel DB1/USER1/EMPLOYEES.

      "primaryKeys":[['dep_id'], ['report_by','report_title']],
      "assets":["DB1/USER1/DEPARTMENT","DB1/USER1/EMPLOYEES"],

API

Gunakan metode projects.locations.transferConfigs.create dan berikan instance resource TransferConfig.

Saat Anda menyimpan konfigurasi transfer, konektor PostgreSQL akan otomatis memicu eksekusi transfer sesuai dengan opsi jadwal Anda. Dengan setiap proses transfer, konektor PostgreSQL mentransfer semua data yang tersedia dari PostgreSQL ke BigQuery.

Untuk menjalankan transfer data secara manual di luar jadwal reguler, Anda dapat memulai operasi pengisian ulang.

Memecahkan masalah

Jika Anda mengalami masalah saat menyiapkan transfer data, lihat Masalah transfer PostgreSQL.

Transfer metadata

Anda juga dapat menggunakan konektor PostgreSQL untuk mentransfer metadata ke Knowledge Catalog. Untuk mengetahui informasi selengkapnya, lihat Memuat metadata PostgreSQL ke dalam Knowledge Catalog.

Langkah berikutnya