Halaman ini diterjemahkan oleh Cloud Translation API.

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. Dalam kasus operasi failover atau pengalihan replika, endpoint tulis ini akan mengalihkan koneksi masuk ke instance utama baru secara otomatis. 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 pengalihan replika untuk pemulihan dari gangguan wilayah 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 penulisan selalu diakhiri dengan akhiran .global.sql-psa.goog.. Anda tidak dapat mengubah nama atau format endpoint tulis yang dikelola oleh Cloud SQL ini.

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 pengalihan replika untuk mempromosikan instance replika menjadi instance utama baru.

Buat endpoint tulis

Jika Anda membuat instance Cloud SQL baru, Cloud SQL akan membuat endpoint tulis secara otomatis jika 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, maka pembuatan zona DNS peering akan gagal dan nama DNS tidak dapat digunakan.

Setelah zona DNS peering berhasil dibuat, penting untuk tidak memodifikasinya dengan cara apa pun. Setiap modifikasi, termasuk penghapusan, akan membuat DNS tidak dapat digunakan untuk koneksi database.
Instance Cloud SQL harus berupa 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. Dalam sebagian besar kasus, instance baru dibuat dengan arsitektur baru. Untuk memverifikasi hal ini, 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, maka buat replika yang diaktifkan untuk pemulihan dari bencana 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., mirip dengan 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. Contoh, verify-full.
SSL_ROOT_SERVER: nama server root SSL. Contoh, server-ca.pem.
SSL_CERT: nama sertifikat SSL yang digunakan oleh klien. Contoh, client-cert.pem.
SSL_KEY: nama kunci SSL yang digunakan oleh klien. Contoh, client-key.pem.
WRITE_ENDPOINT: nama DNS atau endpoint tulis. Nilai alfanumerik ini selalu diakhiri dengan akhiran .global.sql-psa.goog.. Contoh, 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog..
PORT: nomor port yang digunakan. Contoh, 5432.
USERNAME: nama pengguna. Contoh, 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 pengalihan atau failover secara berkala. Saat konektor Cloud SQL mendeteksi bahwa nama DNS endpoint tulis merujuk ke instance yang berbeda, konektor akan menutup semua koneksi terbuka ke instance lama. Upaya koneksi berikutnya akan diarahkan ke instance baru.

Misalnya, anggaplah 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 pengalihan 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 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. Tindakan 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 perubahan 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 Cloud SQL Auth Proxy dapat menggunakan endpoint tulis. Anda hanya perlu menjalankan tugas update ini satu kali untuk setiap instance. Jalankan perintah berikut:

gcloud CLI

  # Update the primary instance DNS settings
  gcloud \
      alpha 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, pertama-tama mulai proxy 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.. Contoh, 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog..
PORT: nomor port yang digunakan. Contoh, 5432.
USERNAME: nama pengguna. Contoh, postgres.
DATABASE_NAME: nama database. Misalnya, postgres.

Menghubungkan menggunakan Cloud SQL Language Connectors

Untuk terhubung menggunakan salah satu Cloud SQL Language Connectors, konfigurasikan aplikasi Anda dengan mengikuti petunjuk di 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. Contoh, my-database.
USERNAME: Nama pengguna. Contoh, 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. Contoh, my-database.
USERNAME: Nama pengguna. Contoh, 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. Contoh, my-database.
USERNAME: Nama pengguna. Contoh, 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. Contoh, my-database.
USERNAME: Nama pengguna. Contoh, 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 khusus IP publik atau instance khusus 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 Cloud SQL layanan
Membuat zona DNS peering di jaringan VPC pelanggan
Membuat data DNS di zona DNS pribadi di jaringan produsen layanan

Diagram berikut menggambarkan cara kerja proses ini:

Diagram yang menunjukkan cara peering VPC mendukung peering zona DNS antar-project. — **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:

Pastikan semua prasyarat terpenuhi.
Pastikan klien tempat resolusi diharapkan berada di jaringan yang sama dengan tempat instance Cloud SQL terhubung. Untuk memeriksa hal ini, 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.
Pastikan zona peering ada. Untuk melakukannya, gunakan perintah gcloud dns managed-zones list:
```
gcloud dns managed-zones list \
    --project=PROJECT_NAME
```
Ganti PROJECT_NAME dengan nama project tempat jaringan konsumen DNS berada.
Jika zona peering tidak ada, Anda dapat memperbaiki masalah ini 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.

Instance baru tidak memiliki endpoint tulis

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

Pastikan semua prasyarat telah diselesaikan.
Pastikan tidak ada zona DNS peering yang tersisa 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 ID project peer dari zona DNS peering.

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

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

Untuk memeriksa zona DNS peering yang tersisa, gunakan perintah gcloud dns managed-zones list:
```
gcloud dns managed-zones list \
   --project=PROJECT_NAME
```
Ganti PROJECT_NAME dengan nama project tempat jaringan konsumen DNS berada.

Jika ada zona DNS dengan akhiran sql-psa.goog., hapus zona DNS tersebut setelah memeriksa ulang bahwa zona DNS peering adalah zona DNS yang tidak terpakai.

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.
Anda dapat memperbaiki endpoint tulis yang tidak ada 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.

Menghubungkan ke instance menggunakan endpoint tulis Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Ringkasan

Buat endpoint tulis

Melihat endpoint tulis

gcloud

Menghubungkan ke instance Cloud SQL menggunakan endpoint tulis

psql

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

psql

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

Memperbarui konfigurasi jaringan instance

gcloud CLI

Menghubungkan klien database ke instance menggunakan Proxy Auth Cloud SQL

psql

Menghubungkan menggunakan Cloud SQL Language Connectors

Java

Go

Python

Node.js

Batasan

Pemecahan masalah

Arsitektur endpoint tulis

Masalah resolusi DNS

Instance baru tidak memiliki endpoint tulis

Langkah berikutnya

Menghubungkan ke instance menggunakan endpoint tulis