Mengekspor file CSV

Untuk mengekstrak data tabel atau kueri untuk digunakan di alat dan lingkungan eksternal, Anda dapat mengekspor data dari cluster AlloyDB untuk PostgreSQL ke bucket Cloud Storage dalam format CSV.

Untuk mengetahui informasi tentang cara memigrasikan seluruh database dari server database yang didukung ke instance AlloyDB baru, lihat Memigrasikan database ke AlloyDB menggunakan Database Migration Service. Jika Anda mengekspor karena ingin membuat instance baru dari file yang diekspor, pertimbangkan untuk memulihkan cluster dari cadangan yang disimpan.

Anda dapat membatalkan ekspor data dari cluster AlloyDB untuk PostgreSQL. Untuk mengetahui informasi selengkapnya, lihat Membatalkan operasi ekspor.

Sebelum memulai

• Sebelum Anda memulai operasi ekspor, perlu diingat bahwa operasi ekspor menggunakan resource database, tetapi tidak mengganggu operasi database standar kecuali jika penyediaan instance kurang lengkap.
• SELECT_QUERY dapat berisi komentar atau spasi kosong di awal dan akhir. Komentar akan diabaikan dan spasi kosong akan dipangkas sebelum menjalankan kueri ekspor.
• Biaya transfer data antar-region berlaku jika bucket target berada di region yang berbeda dengan cluster sumber. Untuk mengetahui informasi selengkapnya, lihat Harga AlloyDB untuk PostgreSQL.
• Beberapa operasi ekspor dapat berjalan secara paralel.
• Kompresi diaktifkan jika nama objek diakhiri dengan ekstensi .gz. Objek kemudian diekspor dalam format .gz ke Cloud Storage.
• Hanya karakter ASCII dalam kode hex (dengan atau tanpa awalan 0x) yang diizinkan untuk nilai karakter dalam opsi CSV seperti field_delimiter, quote_character, dan escape_character.

Peran dan izin yang diperlukan untuk mengekspor dari AlloyDB

Untuk mengekspor data dari AlloyDB ke Cloud Storage, pengguna yang memulai ekspor harus memiliki salah satu peran Identity and Access Management (IAM) berikut:

• Peran AlloyDB Admin (roles/alloydb.admin)
• Peran khusus, yang mencakup izin berikut:
  • alloydb.clusters.get
  • alloydb.clusters.export

Selain itu, akun layanan untuk cluster AlloyDB harus memiliki salah satu peran berikut:

• Peran IAM storage.objectAdmin
• Peran khusus, termasuk izin berikut:
  • storage.objects.create

Untuk mendapatkan bantuan terkait peran IAM, lihat Identity and Access Management.

Mengekspor data ke file CSV

Selama ekspor CSV berlangsung, Anda dapat menentukan skema yang akan diekspor. Semua skema di tingkat database memenuhi syarat untuk diekspor.

Catatan: AlloyDB menggunakan tanda kutip ganda (nilai hex 22) sebagai karakter escape default. Hal ini dapat menjadi masalah bagi database saat nilai untuk NULL dimasukkan sebagai literal string.

Anda dapat menggunakan gcloud CLI atau REST API untuk menyesuaikan format file CSV.

gcloud

1. Buat bucket Cloud Storage.

2. Gunakan gcloud storage buckets add-iam-policy-binding untuk memberikan peran IAM storage.objectAdmin ke akun layanan AlloyDB untuk bucket. Format untuk akun layanan adalah sebagai berikut:

   [e-mail]

   Untuk mendapatkan bantuan terkait penetapan izin IAM, lihat Menggunakan izin IAM.

   Catatan: Jika objek yang ada memiliki nama yang sama dengan objek yang diekspor ke bucket Cloud Storage, pemberian peran objectAdmin ke akun layanan akan menyebabkan objek yang lebih lama diganti. Untuk menghindari hal ini, Anda dapat memberikan izin dengan hak istimewa yang lebih rendah, yaitu storage.objectCreator, kepada akun layanan, yang tidak dapat menggantikan objek yang ada.

3. Ekspor database ke bucket Cloud Storage Anda.

   Jalankan perintah ekspor CSV: gcloud alloydb clusters export.

   Daftar berikut menjelaskan opsi untuk mengekspor data dalam format CSV:

   • --select-query (Wajib): Kueri select yang digunakan untuk mengekstrak data.
   Catatan: Saat sedang transit, kueri mungkin diproses di lokasi perantara selain lokasi instance target.
   • --async (Opsional): segera menampilkan, tanpa menunggu operasi yang sedang berlangsung selesai.
   • --field-delimiter (Opsional): menentukan karakter yang memisahkan kolom di setiap baris file. Defaultnya adalah koma. Nilai argumen ini harus berupa karakter dalam kode ASCII hex.
   • --quote-character (Opsional): Menentukan karakter tanda petik yang akan digunakan saat nilai data dikutip. Defaultnya adalah tanda petik ganda. Nilai argumen ini harus berupa karakter dalam kode ASCII hex.
   • --escape-character (Opsional): Menentukan karakter yang harus muncul sebelum karakter data yang perlu di-escape. Defaultnya sama dengan --quote-character. Nilai argumen ini harus berupa karakter dalam kode ASCII hex.

   Untuk menggunakan fitur ini, sertakan opsi ini dalam perintah gcloud CLI.

   Jika tidak, hapus parameter ini dari perintah berikut:

   gcloud alloydb clusters export CLUSTER_NAME \
     --region=REGION \
     --database=DATABASE_NAME \
     --gcs-uri="gs://BUCKET_NAME/OBJECT_NAME" \
     --select-query=SELECT_QUERY \
     --field-delimiter=FIELD_DELIMITER \
     --quote-character=QUOTE_CHARACTER \
     --escape-character=ESCAPE_CHARACTER \
     --csv

4. Jika Anda tidak perlu mempertahankan peran IAM yang telah Anda tetapkan sebelumnya, cabut peran tersebut.

REST v1

1. Buat bucket untuk ekspor:

   gcloud storage buckets create gs://BUCKET_NAME --location=LOCATION_NAME --project=PROJECT_NAME

2. Gunakan gcloud storage buckets add-iam-policy-binding untuk memberikan peran IAM storage.objectAdmin ke akun layanan AlloyDB untuk bucket. Format untuk akun layanan adalah sebagai berikut:

   [e-mail]

   Untuk mendapatkan bantuan terkait penetapan izin IAM, lihat Menggunakan izin IAM.

   Catatan: Jika sudah ada objek dengan nama yang sama dengan yang diekspor di bucket Cloud Storage, pemberian peran objectAdmin ke akun layanan akan menyebabkan objek yang lebih lama diganti. Untuk menghindari hal ini, Anda dapat memberikan izin dengan hak istimewa yang lebih rendah, storage.objectCreator, ke akun layanan, yang tidak dapat mengganti objek yang sudah ada.

3. Ekspor database Anda.
   

   Gunakan metode HTTP dan URL berikut:

   POST https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:export

   Sebelum menggunakan data permintaan apa pun, lakukan penggantian berikut:

   • PROJECT_ID: project ID.
   • REGION: region tempat cluster AlloyDB di-deploy.
   • CLUSTER_ID: ID cluster.
   • BUCKET_NAME: nama bucket Cloud Storage.
   • PATH_TO_CSV_FILE: jalur ke file CSV.
   • DATABASE_NAME: nama database di dalam cluster AlloyDB.

   • SELECT_QUERY: kueri SQL untuk ekspor.

     Catatan: Saat sedang transit, kueri mungkin diproses di lokasi perantara selain lokasi instance target.

   • ESCAPE_CHARACTER (Opsional): karakter yang harus muncul sebelum karakter data yang perlu di-escape. Nilai argumen ini harus berupa karakter dalam Kode ASCII Hex. Misalnya, 22 mewakili tanda kutip ganda.

   • QUOTE_CHARACTER (Opsional): karakter yang mengapit nilai dari kolom yang memiliki jenis data string. Nilai argumen ini harus berupa karakter dalam Kode ASCII Hex. Misalnya, 22 mewakili tanda kutip ganda.

   • FIELD_DELIMITER (Opsional): karakter yang memisahkan nilai kolom. Nilai argumen ini harus berupa karakter dalam Kode ASCII Hex. Misalnya, 2C mewakili koma.

   Meminta isi JSON:

   {
     "gcs_destination": {
       "uri": "gs://BUCKET_NAME/PATH_TO_CSV_FILE"
     },
     "database": "DATABASE_NAME",
     "csv_export_options": {
       "select_query": "SELECT_QUERY",
       "escape_character": "ESCAPE_CHARACTER",
       "quote_character": "QUOTE_CHARACTER",
       "field_delimiter": "FIELD_DELIMITER"
     }
   }
   

   Untuk mengirim permintaan Anda, gunakan salah satu opsi berikut:

curl (Linux, macOS, atau Cloud Shell)

Perintah berikut mengasumsikan bahwa Anda login ke Google Cloud CLI dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI. Anda dapat memeriksa akun yang aktif dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

       curl -X POST \
             -H "Authorization: Bearer $(gcloud auth print-access-token)" \
             -H "Content-Type: application/json; charset=utf-8" \
             -d @request.json \
             "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:export"
  

PowerShell (Windows)

Perintah berikut mengasumsikan bahwa Anda login ke Google Cloud CLI dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI. Anda dapat memeriksa akun yang aktif dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
      -Method POST `
      -Headers $headers `
      -ContentType: "application/json; charset=utf-8" `
      -InFile request.json `
      -Uri "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:export"| Select-Object -Expand Content
  

Anda akan menerima respons JSON yang mirip dengan yang berikut ini:

Respons

    {
     "name": "projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID",
     "metadata": {
      "@type": "type.googleapis.com/google.cloud.alloydb.v1.OperationMetadata",
      "createTime": "2024-09-17T06:05:31.244428646Z",
      "target": "projects/PROJECT_ID/locations/REGION/clusters/TARGET_CLUSTER",
      "verb": "export",
      "requestedCancellation": false,
      "apiVersion": "v1"
     },
     "done": false
    }
  

Jika Anda tidak perlu mempertahankan izin IAM yang telah Anda tetapkan sebelumnya, hapus izin tersebut.

Untuk mengetahui daftar lengkap parameter permintaan, lihat clusters.export.

Menyesuaikan format dari file ekspor CSV

Anda dapat menggunakan gcloud CLI atau REST API untuk menyesuaikan format file CSV. Saat melakukan ekspor, Anda dapat menentukan opsi pemformatan berikut:

Opsi CSV	Nilai default	flag gcloud	Properti REST API	Deskripsi
Escape	Nilai defaultnya sama dengan nilai QUOTE.	--escape-character	escape_character	Karakter yang muncul sebelum karakter data yang perlu di-escape.
Kutip	"22" Kode hex ASCII untuk tanda petik ganda.	--quote-character	quote_character	Menentukan karakter tanda petik yang akan digunakan saat nilai data dikutip.
Field delimiter	"2C" Kode hex ASCII untuk koma.	--field-delimiter	field_delimiter	Karakter yang memisahkan nilai kolom.

Gunakan contoh gcloud CLI dan REST API berikut untuk menyesuaikan format file ekspor CSV Anda:

gcloud

gcloud alloydb clusters export CLUSTER_NAME \
  --region=REGION \
  --database=DATABASE_NAME \
  --gcs-uri='gs://BUCKET_NAME/PATH_TO_CSV_FILE' \
  --select-query=SELECT_QUERY \
  --field-delimiter='2C' \
  --quote-character='22' \
  --escape-character='5C' \
  --csv

REST v1

Isi permintaan REST API yang setara terlihat mirip dengan yang berikut ini:

{
  "gcs_destination": {
    "uri": "gs://BUCKET_NAME/PATH_TO_CSV_FILE"
  },
  "database": "DATABASE_NAME",
  "csv_export_options": {
    "select_query": "SELECT_QUERY",
    "escape_character": "5C",
    "quote_character": "22",
    "field_delimiter": "2C"
  }
}

Secara default, ekspor CSV membuat output CSV standar. Jika memerlukan lebih banyak opsi daripada yang disediakan oleh AlloyDB, Anda dapat menggunakan pernyataan berikut di klien psql:

\copy TABLE_NAME TO 'CSV_FILE_NAME.csv' WITH
  (FORMAT csv, ESCAPE 'ESCAPE_CHARACTER', QUOTE 'QUOTE_CHARACTER',
  DELIMITER 'DELIMITER_CHARACTER', ENCODING 'UTF8', NULL 'NULL_MARKER_STRING');

Langkah berikutnya

• Pelajari cara mengekspor file dump SQL.
• Membatalkan operasi ekspor.