Menghubungkan ke instance menggunakan endpoint tulis

MySQL   |  PostgreSQL   |  SQL Server

Ringkasan

Halaman ini menunjukkan cara menggunakan endpoint tulis untuk terhubung dari klien di jaringan Virtual Private Cloud (VPC) ke instance Cloud SQL menggunakan akses layanan pribadi (PSA).

Endpoint tulis adalah nama layanan nama domain (DNS) global yang otomatis di-resolve ke alamat IP instance utama saat ini. Jika terjadi operasi failover atau switchover replika, endpoint tulis ini akan otomatis mengalihkan koneksi masuk ke instance utama baru. Anda dapat menggunakan endpoint tulis dalam string koneksi SQL ke instance Cloud SQL, bukan menggunakan alamat IP. Dengan menggunakan endpoint tulis, Anda tidak perlu melakukan perubahan koneksi aplikasi saat melakukan operasi failover atau switchover replika untuk pemulihan gangguan regional atau latihan pemulihan dari bencana.

Setiap instance Cloud SQL yang memenuhi syarat memiliki satu endpoint tulis bawaan yang nama, pembuatan, dan pembaruannya dikelola oleh Cloud SQL. Contoh berikut mengilustrasikan formatnya:

  103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog.
  

Endpoint tulis selalu diakhiri dengan akhiran .global.sql-psa.goog.. Anda tidak dapat mengubah nama atau format endpoint tulis ini yang dikelola oleh Cloud SQL.

Anda dapat menggunakan endpoint tulis untuk semua operasi tulis pada instance utama, termasuk penyisipan, pembaruan, penghapusan, dan perubahan DDL. Anda juga dapat menggunakan endpoint tulis untuk operasi baca, seperti kueri. Alamat IP pribadi yang ditunjukkan oleh endpoint tulis akan otomatis diubah oleh Cloud SQL saat Anda melakukan operasi failover atau switchover replika untuk mempromosikan instance replika menjadi instance utama baru.

Membuat endpoint tulis

Jika Anda membuat instance Cloud SQL baru, Cloud SQL akan otomatis membuat endpoint tulis saat prasyarat berikut terpenuhi:

• API berikut harus diaktifkan di Google Cloud project tempat instance Cloud SQL Anda berada:
  • Compute Engine API
  • Cloud DNS API

  Jika Cloud DNS API tidak diaktifkan di project, zona DNS peering tidak akan dibuat sehingga nama DNS tidak dapat digunakan.

  Setelah zona DNS peering berhasil dibuat, penting untuk tidak mengubahnya dengan cara apa pun. Setiap perubahan, termasuk penghapusan, akan membuat DNS tidak dapat digunakan untuk koneksi database.

• Instance Cloud SQL harus merupakan edisi Cloud SQL Enterprise Plus.
• Instance Cloud SQL harus dikonfigurasi untuk menggunakan IP pribadi dengan akses layanan pribadi (PSA) diaktifkan.
• Fitur ini memerlukan instance pada arsitektur jaringan baru. Pada umumnya, instance baru dibuat dengan arsitektur baru. Untuk memverifikasinya, periksa arsitektur jaringan instance Anda.

Saat Anda mengupgrade instance edisi Cloud SQL Enterprise yang ada ke instance edisi Cloud SQL Enterprise Plus, Cloud SQL akan otomatis membuat endpoint tulis jika prasyarat yang tercantum sebelumnya terpenuhi. Jika instance yang ada berada dalam arsitektur jaringan lama, Anda harus mengupgrade instance ke arsitektur jaringan baru terlebih dahulu untuk mendapatkan endpoint tulis.

Jika Anda sudah memiliki instance edisi Cloud SQL Enterprise Plus tanpa endpoint tulis dan Anda ingin Cloud SQL membuat endpoint tulis secara otomatis, lalu buat replika yang diaktifkan untuk disaster recovery tingkat lanjut.

Melihat endpoint tulis

gcloud

Untuk menemukan endpoint tulis, gunakan perintah gcloud CLI berikut:

      gcloud sql instances describe INSTANCE_NAME \
      | grep psaWriteEndpoint
    

Lakukan penggantian berikut:

INSTANCE_NAME: nama instance Cloud SQL.

Endpoint tulis selalu diakhiri dengan akhiran .global.sql-psa.goog., seperti contoh berikut:

  103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog.
  

Jika Anda tidak melihat endpoint tulis untuk instance yang memenuhi syarat, lihat Pemecahan masalah.

Menghubungkan ke instance Cloud SQL menggunakan endpoint tulis

psql

Untuk menghubungkan klien psql ke instance Cloud SQL menggunakan endpoint tulis, jalankan perintah berikut:

    psql -U DATABASE_NAME -h WRITE_ENDPOINT
  

Lakukan penggantian berikut:

• DATABASE_NAME: nama database. Misalnya, postgres.
• WRITE_ENDPOINT: nama DNS atau endpoint tulis. Nilai alfanumerik ini selalu diakhiri dengan akhiran .global.sql-psa.goog.. Misalnya, 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog..

Menghubungkan klien database dengan instance database menggunakan endpoint tulis melalui koneksi SSL/TLS

psql

Untuk menghubungkan klien database ke instance menggunakan endpoint tulis melalui koneksi SSL/TLS, jalankan perintah berikut:

  psql "sslmode=SSL_MODE \
    sslrootcert=SSL_ROOT_SERVER \
    sslcert=SSL_CERT \
    sslkey=SSL_KEY \
    host=WRITE_ENDPOINT \
    port=PORT user=USERNAME \
    dbname=DATABASE_NAME"
  

Lakukan penggantian berikut:

• SSL_MODE: mode SSL yang digunakan. Misalnya, verify-full.
• SSL_ROOT_SERVER: nama server root SSL. Misalnya, server-ca.pem.
• SSL_CERT: nama sertifikat SSL yang digunakan oleh klien. Misalnya, client-cert.pem.
• SSL_KEY: nama kunci SSL yang digunakan oleh klien. Misalnya, client-key.pem.
• WRITE_ENDPOINT: nama DNS atau endpoint tulis. Nilai alfanumerik ini selalu diakhiri dengan akhiran .global.sql-psa.goog.. Misalnya, 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog..
• PORT: nomor port yang digunakan. Misalnya, 5432.
• USERNAME: nama pengguna. Misalnya, postgres.
• DATABASE_NAME: nama database. Misalnya, postgres.

Menghubungkan klien database ke instance menggunakan Proxy Auth Cloud SQL atau Cloud SQL Language Connectors

Saat Anda mengonfigurasi Proxy Auth Cloud SQL atau salah satu Cloud SQL Language Connectors menggunakan nama DNS endpoint tulis, konektor Cloud SQL akan memeriksa operasi switchover atau failover secara berkala. Saat konektor Cloud SQL mendeteksi bahwa nama DNS endpoint tulis merujuk ke instance lain, konektor tersebut akan menutup semua koneksi terbuka ke instance lama. Upaya koneksi berikutnya akan diarahkan ke instance baru.

Perhatian: Pastikan untuk memberi tahu pemilik aplikasi sebelum memulai operasi switchover atau failover. Selama switchover dan failover, konektor atau Proxy Auth akan menghentikan semua koneksi database terbuka secara paksa.

Misalnya, aplikasi dikonfigurasi untuk terhubung menggunakan nama DNS endpoint tulis 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog. Awalnya, zona DNS dikonfigurasi dengan data yang mengarah ke instance utama, my-project:region:instance-a. Aplikasi membuat koneksi ke instance Cloud SQL my-project:region:instance-a.

Saat failover atau switchover terjadi, Cloud SQL akan memperbarui data DNS dari my-project:region:instance-a ke instance replika DR yang ditetapkan: my-project:other-region:instance-b.

Konektor Cloud SQL yang digunakan oleh aplikasi mendeteksi perubahan pada data DNS ini. Saat aplikasi terhubung ke databasenya menggunakan nama DNS endpoint tulis 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog, aplikasi tersebut akan terhubung ke instance Cloud SQL my-project:other-region:instance-b.

Konektor atau Proxy Auth akan otomatis menutup semua koneksi yang ada ke my-project:region:instance-a. Hal ini akan memaksa semua kumpulan koneksi yang digunakan oleh aplikasi untuk membuat koneksi baru. Hal ini juga dapat menyebabkan kueri database yang sedang berlangsung gagal.

Proxy Auth Cloud SQL melakukan polling untuk mengetahui perubahan pada nama DNS setiap 30 detik.

Memperbarui konfigurasi jaringan instance

Jika instance Anda dibuat sebelum 8 Agustus 2025, Anda mungkin perlu memperbarui konfigurasi jaringan instance agar Cloud SQL Language Connectors atau Proxy Auth Cloud SQL dapat menggunakan endpoint tulis. Anda hanya perlu menjalankan tugas pembaruan ini satu kali untuk setiap instance. Jalankan perintah berikut:

gcloud CLI

  # Update the primary instance DNS settings
  gcloud sql instances patch "PRIMARY_NAME" \
      --reconcile-psa-networking
  

Lakukan penggantian berikut:

• PRIMARY_NAME: nama instance. Misalnya, my-instance

Menghubungkan klien database ke instance menggunakan Proxy Auth Cloud SQL

Untuk terhubung ke instance Cloud SQL berdasarkan endpoint tulisnya dan menggunakan Proxy Auth Cloud SQL, mulai proxy terlebih dahulu menggunakan endpoint tulis, bukan nama koneksi instance.

psql

  $ cloud-sql-proxy --port PORT WRITE_ENDPOINT
  

Kemudian, konfigurasi klien database untuk terhubung ke Proxy Auth Cloud SQL:

  psql
    host=127.0.0.1 \
    port=PORT user=USERNAME \
    dbname=DATABASE_NAME
  

Lakukan penggantian berikut:

• WRITE_ENDPOINT: nama DNS atau endpoint tulis. Nilai alfanumerik ini selalu diakhiri dengan akhiran .global.sql-psa.goog.. Misalnya, 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog..
• PORT: nomor port yang digunakan. Misalnya, 5432.
• USERNAME: nama pengguna. Misalnya, postgres.
• DATABASE_NAME: nama database. Misalnya, postgres.

Menghubungkan menggunakan Cloud SQL Language Connectors

Untuk terhubung menggunakan salah satu Cloud SQL Language Connectors, konfigurasi aplikasi Anda dengan mengikuti petunjuk dalam dokumentasi Menghubungkan menggunakan Cloud SQL Language Connectors. Kemudian, ubah koneksi database Anda untuk menggunakan endpoint tulis, bukan nama DNS instance.

Java

  String jdbcUrl = "jdbc:postgresql://WRITE_ENDPOINT/DATABASE_NAME?"
    +   "&socketFactory=com.google.cloud.sql.postgres.SocketFactory"
    +   "&user=USERNAME"
    +   "&password=PASSWORD";
  

Lakukan penggantian berikut:

• WRITE_ENDPOINT: nama DNS atau endpoint tulis. Nilai alfanumerik ini selalu diakhiri dengan akhiran .global.sql-psa.goog..
• DATABASE_NAME: nama database. Misalnya, my-database.
• USERNAME: nama pengguna. Misalnya, postgres.
• PASSWORD: sandi database.

Untuk mengetahui informasi selengkapnya, lihat dokumentasi konektor Java di GitHub.

Go

    db, err := sql.Open(
        "cloudsql-postgres",
        "host=WRITE_ENDPOINT user=USERNAME password=PASSWORD dbname=DATABASE_NAME sslmode=disable",
    )
  

Lakukan penggantian berikut:

• WRITE_ENDPOINT: nama DNS atau endpoint tulis. Nilai alfanumerik ini selalu diakhiri dengan akhiran .global.sql-psa.goog..
• DATABASE_NAME: nama database. Misalnya, my-database.
• USERNAME: nama pengguna. Misalnya, postgres.
• PASSWORD: sandi database.

Untuk mengetahui informasi selengkapnya, lihat dokumentasi konektor Go di GitHub.

Python

  engine = sqlalchemy.create_engine(
      "postgresql+pg8000://",
      creator=lambda: connector.connect(
          "WRITE_ENDPOINT",  # using DNS name
          "pg8000",
          user="USERNAME",
          password="PASSWORD",
          db="DATABASE_NAME"
      ),
  )
  

Lakukan penggantian berikut:

• WRITE_ENDPOINT: nama DNS atau endpoint tulis. Nilai alfanumerik ini selalu diakhiri dengan akhiran .global.sql-psa.goog..
• DATABASE_NAME: nama database. Misalnya, my-database.
• USERNAME: nama pengguna. Misalnya, postgres.
• PASSWORD: sandi database.

Untuk mengetahui informasi selengkapnya, lihat dokumentasi konektor Python di GitHub.

Node.js

  import pg from 'pg';
  import {Connector} from '@google-cloud/cloud-sql-connector';
  const {Pool} = pg;

  const connector = new Connector();
  const clientOpts = await connector.getOptions({
    domainName: 'WRITE_ENDPOINT',
    ipType: 'PUBLIC',
  });
  const pool = new Pool({
    ...clientOpts,
    user: 'USERNAME',
    password: 'PASSWORD',
    database: 'DATABASE_NAME',
    max: 5,
  });
  

Lakukan penggantian berikut:

• WRITE_ENDPOINT: nama DNS atau endpoint tulis. Nilai alfanumerik ini selalu diakhiri dengan akhiran .global.sql-psa.goog..
• DATABASE_NAME: nama database. Misalnya, my-database.
• USERNAME: nama pengguna. Misalnya, postgres.
• PASSWORD: sandi database.

Untuk mengetahui informasi selengkapnya, lihat dokumentasi konektor Node.js di GitHub.

Batasan

• Endpoint tulis tidak tersedia untuk pembuatan instance edisi Cloud SQL Enterprise.
• Endpoint tulis tidak tersedia untuk instance yang hanya menggunakan IP publik atau instance yang hanya menggunakan Private Service Connect.

Pemecahan masalah

Bagian berikut menjelaskan arsitektur endpoint tulis dan membahas masalah pemecahan masalah umum.

Arsitektur endpoint tulis

Saat Anda membuat instance yang memenuhi syarat, endpoint tulis akan dibuat secara default.

Untuk membuat endpoint tulis, Cloud SQL melakukan penyiapan berikut:

• Membuat zona DNS pribadi di jaringan VPC produsen layanan Cloud SQL
• Membuat zona DNS peering di jaringan VPC pelanggan
• Membuat data DNS di zona DNS pribadi di jaringan produsen layanan

Diagram berikut mengilustrasikan cara kerja proses ini:

Gambar 1. Diagram yang menunjukkan cara peering VPC mendukung peering zona DNS antara jaringan produsen layanan dan jaringan pelanggan.

Masalah resolusi DNS

Jika resolusi DNS tidak berfungsi, periksa setiap item berikut:

1. Pastikan semua prasyarat terpenuhi.
2. Pastikan klien tempat resolusi diharapkan berada di jaringan yang sama dengan tempat instance Cloud SQL terlampir. Untuk memeriksanya, gunakan perintah gcloud compute instances list:

   gcloud compute instances list \
      --format="table( name, zone.basename(), networkInterfaces[].network )" \
      --project=PROJECT_NAME

   Ganti PROJECT_NAME dengan nama project tempat jaringan konsumen DNS berada.

3. Pastikan zona peering ada. Untuk melakukannya, gunakan gcloud dns managed-zones list perintah:

   gcloud dns managed-zones list \
       --project=PROJECT_NAME

   Ganti PROJECT_NAME dengan nama project tempat jaringan konsumen DNS berada.

4. Jika zona peering tidak ada, Anda dapat memperbaiki masalah ini menggunakan gcloud sql instances patch perintah:

   gcloud sql instances patch INSTANCE_NAME --reconcile-psa-networking

   Ganti INSTANCE_NAME dengan nama instance Cloud SQL Anda.

Instance baru tidak memiliki endpoint tulis

Jika instance yang baru dibuat tidak berisi endpoint tulis, periksa setiap item berikut:

1. Pastikan semua prasyarat telah diselesaikan.
2. Pastikan tidak ada zona DNS peering sisa dengan nama DNS sql-psa.goog..

   Zona DNS peering adalah zona DNS sisa jika jaringan yang terkait dengan zona DNS tidak memiliki peering VPC dengan project ID peer zona DNS peering.

   Jika ada zona DNS peering sisa dengan akhiran sql-psa.goog., hapus zona tersebut.

   Perhatian: Berhati-hatilah saat menghapus zona DNS peering. Jika Anda menghapus zona DNS yang salah, Anda dapat menyebabkan hilangnya konektivitas untuk semua instance yang terlampir ke jaringan.

   Untuk memeriksa zona DNS peering sisa, gunakan gcloud dns managed-zones list perintah:

   gcloud dns managed-zones list \
      --project=PROJECT_NAME

   Ganti PROJECT_NAME dengan nama project tempat jaringan konsumen DNS berada.

   Jika zona DNS ada dengan akhiran sql-psa.goog., hapus zona DNS setelah memeriksa kembali bahwa zona DNS peering adalah zona DNS sisa.

   Untuk menghapus zona DNS, gunakan perintah gcloud dns managed-zones delete:

   gcloud dns managed-zones delete ZONE_NAME

   Ganti ZONE_NAME dengan nama zona DNS yang terkait dengan endpoint tulis. Nilai bersifat alfanumerik dan menggunakan format berikut: cloud-sql-psa-dns-1234567890.

3. Anda dapat memperbaiki endpoint tulis yang hilang untuk instance yang memenuhi syarat menggunakan perintah gcloud beta sql instances patch:

   gcloud beta sql instances patch INSTANCE_NAME --reconcile-psa-networking

   Ganti INSTANCE_NAME dengan nama instance Cloud SQL Anda.

Langkah berikutnya

• Pelajari lebih lanjut pemecahan masalah Cloud SQL.