Terhubung menggunakan Proxy Auth Cloud SQL

MySQL   |  PostgreSQL   |  Server SQL

Halaman ini menjelaskan cara terhubung ke instance Cloud SQL menggunakan Cloud SQL Auth Proxy.

Untuk mengetahui informasi selengkapnya tentang cara kerja Cloud SQL Auth Proxy, lihat Tentang Cloud SQL Auth Proxy.

Ringkasan

Menggunakan Cloud SQL Auth Proxy adalah metode yang direkomendasikan untuk menghubungkan ke instance Cloud SQL. Cloud SQL Auth Proxy:

• Berfungsi dengan endpoint IP pribadi dan publik
• Memvalidasi koneksi menggunakan kredensial untuk akun pengguna atau layanan.
• Menggabungkan koneksi dalam lapisan SSL/TLS yang diberi otorisasi untuk instance Cloud SQL.

Beberapa layanan dan aplikasi Google Cloud menggunakan Cloud SQL Auth Proxy untuk menyediakan koneksi bagi jalur IP publik dengan enkripsi dan otorisasi, termasuk:

• Lingkungan standar App Engine
• Lingkungan fleksibel App Engine
• Cloud Run

Aplikasi yang berjalan di Google Kubernetes Engine dapat terhubung menggunakan Cloud SQL Auth Proxy.

Catatan: Untuk menghubungkan dari Google Kubernetes Engine, sebaiknya jalankan Cloud SQL Auth Proxy dalam pola sidecar, sebagai container tambahan yang berbagi pod dengan aplikasi. Lihat juga panduan memulai terkait.

Lihat Panduan memulai untuk menggunakan Cloud SQL Auth Proxy sebagai pengantar penggunaan dasar.

Anda juga dapat terhubung, dengan atau tanpa Cloud SQL Auth Proxy, menggunakan klien psql dari mesin lokal atau Compute Engine.

Sebelum memulai

Sebelum Anda dapat terhubung ke instance Cloud SQL, lakukan hal berikut:

1. • Untuk akun pengguna atau layanan, pastikan akun tersebut memiliki peran Klien Cloud SQL. Peran ini berisi cloudsql.instances.connect izin, yang memberi otorisasi kepada akun utama untuk terhubung ke semua instance Cloud SQL dalam project.

     Buka halaman IAM

   • Anda dapat menyertakan kondisi IAM secara opsional dalam binding kebijakan IAM yang memberikan izin akun untuk terhubung hanya ke satu instance Cloud SQL tertentu.

2. Aktifkan Cloud SQL Admin API, jika belum diaktifkan.

   Peran yang diperlukan untuk mengaktifkan API

   Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

   Mengaktifkan API

3. Menginstal dan melakukan inisialisasi gcloud CLI.
4. Opsional. Instal klien Docker Cloud SQL Auth Proxy.

Mendownload Cloud SQL Auth Proxy

Sebelum memulai, Anda harus menentukan arsitektur mesin Anda.

Jika berjalan di Linux atau Mac, Anda dapat menemukannya dengan menjalankan perintah berikut:

  uname -a
  

Linux 64 bit

1. Download Cloud SQL Auth Proxy:

   curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.26.2/cloud-sql-proxy.linux.amd64

2. Buat Cloud SQL Auth Proxy agar dapat dieksekusi:

   chmod +x cloud-sql-proxy

Linux 32 bit

1. Download Cloud SQL Auth Proxy:

   curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.26.2/cloud-sql-proxy.linux.386

2. Jika perintah curl tidak ditemukan, jalankan sudo apt install curl dan ulangi perintah download.
3. Buat Cloud SQL Auth Proxy agar dapat dieksekusi:

   chmod +x cloud-sql-proxy

macOS 64-bit

1. Download Cloud SQL Auth Proxy:

   curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.26.2/cloud-sql-proxy.darwin.amd64

2. Buat Cloud SQL Auth Proxy agar dapat dieksekusi:

   chmod +x cloud-sql-proxy

Mac M1

1. Download Cloud SQL Auth Proxy:

     curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.26.2/cloud-sql-proxy.darwin.arm64
     

2. Buat Cloud SQL Auth Proxy agar dapat dieksekusi:

     chmod +x cloud-sql-proxy
     

Windows 64 bit

Klik kanan https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.26.2/cloud-sql-proxy.x64.exe dan pilih Save Link As untuk mendownload Cloud SQL Auth Proxy. Ganti nama file menjadi cloud-sql-proxy.exe.

Windows 32 bit

Klik kanan https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.26.2/cloud-sql-proxy.x86.exe dan pilih Save Link As untuk mendownload Cloud SQL Auth Proxy. Ganti nama file menjadi cloud-sql-proxy.exe.

Image Docker Cloud SQL Auth Proxy

Cloud SQL Auth Proxy memiliki image container yang berbeda, seperti distroless, alpine, dan buster. Image container Cloud SQL Auth Proxy default menggunakan distroless, yang tidak berisi shell. Jika Anda memerlukan shell atau alat terkait, download image berdasarkan alpine atau buster. Untuk mengetahui informasi selengkapnya, lihat Image Container Cloud SQL Auth Proxy.

Anda dapat menarik image terbaru ke mesin lokal menggunakan Docker dengan perintah berikut:

docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.26.2

Catatan: Cloud SQL Auth Proxy menggunakan repositori yang mendukung domain gcr.io, tetapi menyajikan image dari Artifact Registry. Untuk mengetahui informasi selengkapnya, lihat Transisi dari Container Registry.

OS Lainnya

Untuk sistem operasi lain yang tidak disertakan di sini, Anda dapat mengompilasi Cloud SQL Auth Proxy dari sumber.

Memulai Proxy Auth Cloud SQL

Anda dapat memulai Cloud SQL Auth Proxy menggunakan soket TCP, soket Unix, atau image Docker Cloud SQL Auth Proxy, tergantung pada bahasa dan lingkungan. Biner Cloud SQL Auth Proxy terhubung ke salah satu atau beberapa instance Cloud SQL yang ditentukan pada command line dan membuka koneksi lokal sebagai soket TCP atau Unix. Aplikasi atau layanan lain seperti kode aplikasi atau alat pengelolaan database klien dapat terhubung ke instance Cloud SQL melalui koneksi soket TCP atau Unix tersebut.

Peringatan: Berhati-hatilah saat binding Cloud SQL Auth Proxy ke antarmuka eksternal. Siapa pun yang memiliki akses ke antarmuka/port tersebut akan diizinkan untuk terhubung ke instance.

Soket TCP

Cloud SQL Auth Proxy memproses localhost(127.0.0.1) secara default untuk koneksi TCP. Oleh karena itu, saat Anda menentukan --port PORT_NUMBER untuk instance, koneksi lokal berada di 127.0.0.1:PORT_NUMBER.

Anda dapat menentukan alamat yang berbeda untuk koneksi lokal sebagai alternatif lain. Sebagai contoh, berikut ini cara membuat Cloud SQL Auth Proxy memproses 0.0.0.0:1234 untuk koneksi lokal:

./cloud-sql-proxy --address 0.0.0.0 --port 1234 INSTANCE_CONNECTION_NAME

1. Salin INSTANCE_CONNECTION_NAME. Opsi ini dapat ditemukan di halaman Ringkasan untuk instance Anda di konsolGoogle Cloud atau dengan menjalankan perintah berikut:

       gcloud sql instances describe INSTANCE_NAME --format='value(connectionName)'

   Misalnya: myproject:myregion:myinstance.

2. Apabila instance memiliki IP publik dan pribadi yang sudah dikonfigurasi, dan Anda ingin Cloud SQL Auth Proxy menggunakan alamat IP pribadi, Anda harus menyediakan opsi berikut saat memulai Cloud SQL Auth Proxy:

   --private-ip

3. Apabila menggunakan akun layanan untuk mengautentikasi Proxy Auth Cloud SQL, perhatikan lokasi file kunci pribadi yang dibuat saat Anda mengelola akun layanan tersebut di komputer klien.
4. Mulai Cloud SQL Auth Proxy.

   Beberapa string pemanggilan Cloud SQL Auth Proxy yang mungkin:

   • Menggunakan autentikasi Cloud SDK:

     ./cloud-sql-proxy --port 5432 INSTANCE_CONNECTION_NAME

     Port yang ditentukan tidak boleh berupa port yang sedang digunakan, contohnya, oleh server database lokal.
   • Menggunakan akun layanan dan menyertakan nama koneksi instance secara eksplisit (disarankan untuk lingkungan produksi):

     ./cloud-sql-proxy \
     --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &

   Untuk mengetahui informasi selengkapnya tentang opsi Cloud SQL Auth Proxy, lihat Opsi untuk mengautentikasi Cloud SQL Auth Proxy.

Soket Unix

Catatan: Proxy Auth Cloud SQL saat ini tidak mendukung soket Unix di Windows, sehingga opsi ini hanya tersedia untuk platform Linux dan macOS.

Proxy Auth Cloud SQL dapat memproses soket Unix karena merupakan mekanisme standar Posix untuk menggunakan folder saat mengelola komunikasi antara dua proses berjalan pada host yang sama. Manfaat dari menggunakan soket Unix adalah peningkatan keamanan dan latensi yang rendah, namun Anda tidak dapat mengakses soket Unix dari mesin eksternal.

Catatan: Standar PostgreSQL membutuhkan akhiran `.s.PGSQL.5432` pada jalur soket. Beberapa library menerapkan akhiran ini secara otomatis, tapi library lain perlu menentukan jalur soket sebagai berikut:

  /cloudsql/INSTANCE_CONNECTION_NAME/.s.PGSQL.5432
  

Untuk membuat dan menggunakan soket Unix, direktori target harus ada dan aplikasi serta Cloud SQL Auth Proxy harus memiliki akses baca dan tulis ke direktori tersebut.

1. Salin INSTANCE_CONNECTION_NAME. Opsi ini dapat ditemukan di halaman Ringkasan untuk instance Anda di konsolGoogle Cloud atau dengan menjalankan perintah berikut:

       gcloud sql instances describe INSTANCE_NAME --format='value(connectionName)'

   Misalnya: myproject:myregion:myinstance.

2. Buat direktori tempat soket Cloud SQL Auth Proxy akan diaktifkan:

   sudo mkdir /cloudsql; sudo chmod 777 /cloudsql

3. Apabila menggunakan akun layanan untuk mengautentikasi Proxy Auth Cloud SQL, perhatikan lokasi file kunci pribadi yang dibuat saat Anda mengelola akun layanan tersebut di komputer klien.
4. Buka jendela terminal Cloud Shell baru dan mulai Cloud SQL Auth Proxy.

   Beberapa kemungkinan string pemanggilan Cloud SQL Auth Proxy:

   • Menggunakan autentikasi Google Cloud SDK:

     ./cloud-sql-proxy --unix-socket /cloudsql INSTANCE_CONNECTION_NAME &

   • Menggunakan akun layanan:

       ./cloud-sql-proxy --unix-socket /cloudsql
       --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &

   Mulai Cloud SQL Auth Proxy di terminal Cloud Shell-nya sendiri sehingga Anda dapat memantau output tersebut tanpa bercampur dengan output program lain.

   Untuk mengetahui informasi selengkapnya tentang opsi Cloud SQL Auth Proxy, lihat Opsi untuk mengautentikasi Cloud SQL Auth Proxy.

   CATATAN: Saat menggunakan soket unix untuk terhubung ke Cloud SQL menggunakan Cloud SQL Auth Proxy, pastikan panjang nama file soket tersebut tidak melebihi batas sistem. Panjang nama file tersebut tergantung pada sistem, berkisar antara 91-108 karakter. Di Linux, panjang nama file tersebut ditetapkan sebagai 108, dan Anda dapat memeriksanya menggunakan perintah berikut:

   cat /usr/include/linux/un.h | grep "define UNIX_PATH_MAX"

Docker

Untuk menjalankan Cloud SQL Auth Proxy pada container Docker, gunakan image Docker Cloud SQL Auth Proxy yang tersedia dari Google Container Registry.

Anda dapat memulai Cloud SQL Auth Proxy menggunakan soket TCP atau soket Unix, dengan perintah yang ditampilkan di bawah ini. Opsi tersebut menggunakan INSTANCE_CONNECTION_NAME sebagai string koneksi untuk mengidentifikasi instance Cloud SQL. Anda dapat menemukan INSTANCE_CONNECTION_NAME di halaman Ringkasan untuk instance Anda di Google Cloud console atau dengan menjalankan perintah berikut:

gcloud sql instances describe INSTANCE_NAME

Misalnya: myproject:myregion:myinstance.

Catatan: Cloud SQL Auth Proxy tidak mendukung pemrosesan pada soket domain Unix di Windows.

Anda dapat memulai Cloud SQL Auth Proxy menggunakan soket TCP atau soket Unix, tergantung pada bahasa dan lingkungan Anda. Soket Unix tidak didukung untuk aplikasi yang ditulis dalam bahasa pemrograman Java atau untuk lingkungan Windows.

Menggunakan soket TCP

docker run -d \
  -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \
  -p 127.0.0.1:5432:5432 \
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.26.2 \
  --address 0.0.0.0 --port 5432 \
  --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME

Jika Anda menggunakan kredensial yang disediakan oleh instance Compute Engine, jangan sertakan parameter --credentials-file dan baris -v PATH_TO_KEY_FILE:/path/to/service-account-key.json.

Selalu tentukan awalan 127.0.0.1 di -p agar Cloud SQL Auth Proxy tidak terekspos di luar host lokal. Flag --address 0.0.0.0 diperlukan agar port dapat diakses dari luar container Docker.

Menggunakan soket Unix

docker run -d -v /cloudsql:/cloudsql \
  -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.26.2 \
  --unix-socket /cloudsql \
  --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME

Jika Anda menggunakan kredensial yang disediakan oleh instance Compute Engine, jangan sertakan parameter --credentials-file dan baris -v PATH_TO_KEY_FILE:/path/to/service-account-key.json.

Jika Anda menggunakan image yang dioptimalkan untuk container, gunakan direktori yang dapat ditulis sebagai pengganti /cloudsql, misalnya:

-v /mnt/stateful_partition/cloudsql:/cloudsql

Anda dapat menentukan lebih dari satu instance yang dipisahkan dengan spasi. Anda juga dapat menggunakan metadata Compute Engine untuk menentukan instance yang akan dihubungkan secara dinamis. Pelajari lebih lanjut parameter Cloud SQL Auth Proxy.

Terhubung dengan klien psql

Debian/Ubuntu

Instal klien psql dari pengelola paket:

sudo apt-get update
sudo apt-get install postgresql-client

CentOS/RHEL

Instal klien psql dari pengelola paket:

sudo yum install postgresql

openSUSE

Instal klien psql dari pengelola paket:

sudo zypper install postgresql

Platform lainnya

1. Download PostgreSQL Core Distribution untuk platform dari halaman Download PostgreSQL.
   Core Distribution sudah termasuk klien psql.
2. Instal database PostgreSQL dengan mengikuti petunjuk di halaman download.

String koneksi yang Anda gunakan bergantung pada apakah Anda memulai Cloud SQL Auth Proxy menggunakan soket TCP, soket UNIX, atau Docker.

Soket TCP

1. Mulai klien psql:

   psql "host=127.0.0.1 sslmode=disable dbname=DB_NAME user=USERNAME"

   Meskipun parameter sslmode disetel ke disable, Proxy Auth Cloud SQL menyediakan koneksi terenkripsi.

   Saat Anda terhubung menggunakan soket TCP, Proxy Auth Cloud SQL diakses melalui 127.0.0.1.

2. Masukkan sandi apabila diminta.
3. Prompt psql akan muncul.

Menggunakan soket Unix

1. Mulai klien psql:

   psql "sslmode=disable host=/cloudsql/INSTANCE_CONNECTION_NAME dbname=DB_NAME user=USERNAME"

   Meskipun parameter sslmode disetel ke disable, Proxy Auth Cloud SQL menyediakan koneksi terenkripsi.

2. Masukkan sandi.
3. Prompt psql akan muncul.

Butuh bantuan? Untuk menemukan bantuan pemecahan masalah proxy, lihat Memecahkan masalah koneksi Cloud SQL Auth Proxy, atau lihat halaman Dukungan Cloud SQL.

Menghubungkan dengan aplikasi

Anda dapat terhubung ke Cloud SQL Auth Proxy dari bahasa apa pun yang memungkinkan Anda terhubung ke soket Unix atau TCP. Di bawah ini terdapat beberapa cuplikan kode dari contoh lengkap di GitHub untuk membantu memahami cara kerja dalam aplikasi.

Menghubungkan dengan TCP

Pernyataan pemanggilan Cloud SQL Auth Proxy:

./cloud-sql-proxy INSTANCE_CONNECTION_NAME &

Python

Untuk melihat cuplikan ini dalam konteks aplikasi web, lihat README di GitHub.

import os
import ssl

import sqlalchemy


def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    """Initializes a TCP connection pool for a Cloud SQL instance of Postgres."""
    # Note: Saving credentials in environment variables is convenient, but not
    # secure - consider a more secure solution such as
    # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
    # keep secrets safe.
    db_host = os.environ[
        "INSTANCE_HOST"
    ]  # e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
    db_user = os.environ["DB_USER"]  # e.g. 'my-db-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-db-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'
    db_port = os.environ["DB_PORT"]  # e.g. 5432

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # postgresql+pg8000://<db_user>:<db_pass>@<db_host>:<db_port>/<db_name>
        sqlalchemy.engine.url.URL.create(
            drivername="postgresql+pg8000",
            username=db_user,
            password=db_pass,
            host=db_host,
            port=db_port,
            database=db_name,
        ),
        # ...
    )
    return pool

Java

Untuk menemukan cuplikan ini dalam konteks aplikasi web, lihat README pada GitHub.

Catatan:

• CLOUD-SQL-CONNECTION-NAME harus ditampilkan sebagai <MY-PROJECT>:<INSTANCE-REGION><INSTANCE-NAME>
• Menggunakan argumen ipTypes=PRIVATE akan memaksa SocketFactory untuk terhubung dengan IP pribadi yang terkait dengan instance.
• Lihat persyaratan versi factory soket JDBC untuk file pom.xml.

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class TcpConnectionPoolFactory extends ConnectionPoolFactory {

  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  private static final String DB_USER = System.getenv("DB_USER");
  private static final String DB_PASS = System.getenv("DB_PASS");
  private static final String DB_NAME = System.getenv("DB_NAME");

  private static final String INSTANCE_HOST = System.getenv("INSTANCE_HOST");
  private static final String DB_PORT = System.getenv("DB_PORT");


  public static DataSource createConnectionPool() {
    // The configuration object specifies behaviors for the connection pool.
    HikariConfig config = new HikariConfig();

    // The following URL is equivalent to setting the config options below:
    // jdbc:postgresql://<INSTANCE_HOST>:<DB_PORT>/<DB_NAME>?user=<DB_USER>&password=<DB_PASS>
    // See the link below for more info on building a JDBC URL for the Cloud SQL JDBC Socket Factory
    // https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory#creating-the-jdbc-url

    // Configure which instance and what database user to connect with.
    config.setJdbcUrl(String.format("jdbc:postgresql://%s:%s/%s", INSTANCE_HOST, DB_PORT, DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "postgres"
    config.setPassword(DB_PASS); // e.g. "my-password"


    // ... Specify additional connection properties here.
    // ...

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

Node.js

Untuk melihat cuplikan ini dalam konteks aplikasi web, lihat README di GitHub.

const Knex = require('knex');
const fs = require('fs');

// createTcpPool initializes a TCP connection pool for a Cloud SQL
// instance of Postgres.
const createTcpPool = async config => {
  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  const dbConfig = {
    client: 'pg',
    connection: {
      host: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
      port: process.env.DB_PORT, // e.g. '5432'
      user: process.env.DB_USER, // e.g. 'my-user'
      password: process.env.DB_PASS, // e.g. 'my-user-password'
      database: process.env.DB_NAME, // e.g. 'my-database'
    },
    // ... Specify additional properties here.
    ...config,
  };
  // Establish a connection to the database.
  return Knex(dbConfig);
};

Go

Untuk melihat cuplikan ini dalam konteks aplikasi web, lihat README di GitHub.

package cloudsql

import (
	"database/sql"
	"fmt"
	"log"
	"os"

	// Note: If connecting using the App Engine Flex Go runtime, use
	// "github.com/jackc/pgx/stdlib" instead, since v5 requires
	// Go modules which are not supported by App Engine Flex.
	_ "github.com/jackc/pgx/v5/stdlib"
)

// connectTCPSocket initializes a TCP connection pool for a Cloud SQL
// instance of Postgres.
func connectTCPSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Fatal Error in connect_tcp.go: %s environment variable not set.", k)
		}
		return v
	}
	// Note: Saving credentials in environment variables is convenient, but not
	// secure - consider a more secure solution such as
	// Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
	// keep secrets safe.
	var (
		dbUser    = mustGetenv("DB_USER")       // e.g. 'my-db-user'
		dbPwd     = mustGetenv("DB_PASS")       // e.g. 'my-db-password'
		dbTCPHost = mustGetenv("INSTANCE_HOST") // e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
		dbPort    = mustGetenv("DB_PORT")       // e.g. '5432'
		dbName    = mustGetenv("DB_NAME")       // e.g. 'my-database'
	)

	dbURI := fmt.Sprintf("host=%s user=%s password=%s port=%s database=%s",
		dbTCPHost, dbUser, dbPwd, dbPort, dbName)


	// dbPool is the pool of database connections.
	dbPool, err := sql.Open("pgx", dbURI)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %w", err)
	}

	// ...

	return dbPool, nil
}

C#

Untuk melihat cuplikan ini dalam konteks aplikasi web, lihat README di GitHub.

using Npgsql;
using System;

namespace CloudSql
{
    public class PostgreSqlTcp
    {
        public static NpgsqlConnectionStringBuilder NewPostgreSqlTCPConnectionString()
        {
            // Equivalent connection string:
            // "Uid=<DB_USER>;Pwd=<DB_PASS>;Host=<INSTANCE_HOST>;Database=<DB_NAME>;"
            var connectionString = new NpgsqlConnectionStringBuilder()
            {
                // Note: Saving credentials in environment variables is convenient, but not
                // secure - consider a more secure solution such as
                // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
                // keep secrets safe.
                Host = Environment.GetEnvironmentVariable("INSTANCE_HOST"),     // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                Username = Environment.GetEnvironmentVariable("DB_USER"), // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'

                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = SslMode.Disable,
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

Ruby

Untuk melihat cuplikan ini dalam konteks aplikasi web, lihat README di GitHub.

tcp: &tcp
  adapter: postgresql
  # Configure additional properties here.
  # Note: Saving credentials in environment variables is convenient, but not
  # secure - consider a more secure solution such as
  # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  # keep secrets safe.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  host: <%= ENV.fetch("INSTANCE_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT") { 5432 }%>

PHP

Untuk melihat cuplikan ini dalam konteks aplikasi web, lihat README di GitHub.

namespace Google\Cloud\Samples\CloudSQL\Postgres;

use PDO;
use PDOException;
use RuntimeException;
use TypeError;

class DatabaseTcp
{
    public static function initTcpDatabaseConnection(): PDO
    {
        try {
            // Note: Saving credentials in environment variables is convenient, but not
            // secure - consider a more secure solution such as
            // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
            // keep secrets safe.
            $username = getenv('DB_USER'); // e.g. 'your_db_user'
            $password = getenv('DB_PASS'); // e.g. 'your_db_password'
            $dbName = getenv('DB_NAME'); // e.g. 'your_db_name'
            $instanceHost = getenv('INSTANCE_HOST'); // e.g. '127.0.0.1' ('172.17.0.1' for GAE Flex)

            // Connect using TCP
            $dsn = sprintf('pgsql:dbname=%s;host=%s', $dbName, $instanceHost);

            // Connect to the database
            $conn = new PDO(
                $dsn,
                $username,
                $password,
                # ...
            );
        } catch (TypeError $e) {
            throw new RuntimeException(
                sprintf(
                    'Invalid or missing configuration! Make sure you have set ' .
                        '$username, $password, $dbName, and $instanceHost (for TCP mode). ' .
                        'The PHP error was %s',
                    $e->getMessage()
                ),
                $e->getCode(),
                $e
            );
        } catch (PDOException $e) {
            throw new RuntimeException(
                sprintf(
                    'Could not connect to the Cloud SQL Database. Check that ' .
                        'your username and password are correct, that the Cloud SQL ' .
                        'proxy is running, and that the database exists and is ready ' .
                        'for use. For more assistance, refer to %s. The PDO error was %s',
                    'https://cloud.google.com/sql/docs/postgres/connect-external-app',
                    $e->getMessage()
                ),
                $e->getCode(),
                $e
            );
        }

        return $conn;
    }
}

Menghubungkan dengan soket Unix

Pernyataan pemanggilan Cloud SQL Auth Proxy:

./cloud-sql-proxy --unix-socket /cloudsql INSTANCE_CONNECTION_NAME &

Python

Untuk melihat cuplikan ini dalam konteks aplikasi web, lihat README di GitHub.

import os

import sqlalchemy


def connect_unix_socket() -> sqlalchemy.engine.base.Engine:
    """Initializes a Unix socket connection pool for a Cloud SQL instance of Postgres."""
    # Note: Saving credentials in environment variables is convenient, but not
    # secure - consider a more secure solution such as
    # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
    # keep secrets safe.
    db_user = os.environ["DB_USER"]  # e.g. 'my-database-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-database-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'
    unix_socket_path = os.environ[
        "INSTANCE_UNIX_SOCKET"
    ]  # e.g. '/cloudsql/project:region:instance'

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # postgresql+pg8000://<db_user>:<db_pass>@/<db_name>
        #                         ?unix_sock=<INSTANCE_UNIX_SOCKET>/.s.PGSQL.5432
        # Note: Some drivers require the `unix_sock` query parameter to use a different key.
        # For example, 'psycopg2' uses the path set to `host` in order to connect successfully.
        sqlalchemy.engine.url.URL.create(
            drivername="postgresql+pg8000",
            username=db_user,
            password=db_pass,
            database=db_name,
            query={"unix_sock": f"{unix_socket_path}/.s.PGSQL.5432"},
        ),
        # ...
    )
    return pool

Java

Untuk melihat cuplikan ini dalam konteks aplikasi web, lihat README di GitHub.

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class ConnectorConnectionPoolFactory extends ConnectionPoolFactory {

  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  private static final String INSTANCE_CONNECTION_NAME =
      System.getenv("INSTANCE_CONNECTION_NAME");
  private static final String INSTANCE_UNIX_SOCKET = System.getenv("INSTANCE_UNIX_SOCKET");
  private static final String DB_USER = System.getenv("DB_USER");
  private static final String DB_PASS = System.getenv("DB_PASS");
  private static final String DB_NAME = System.getenv("DB_NAME");

  public static DataSource createConnectionPool() {
    // The configuration object specifies behaviors for the connection pool.
    HikariConfig config = new HikariConfig();

    // The following URL is equivalent to setting the config options below:
    // jdbc:postgresql:///<DB_NAME>?cloudSqlInstance=<INSTANCE_CONNECTION_NAME>&
    // socketFactory=com.google.cloud.sql.postgres.SocketFactory&user=<DB_USER>&password=<DB_PASS>
    // See the link below for more info on building a JDBC URL for the Cloud SQL JDBC Socket Factory
    // https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory#creating-the-jdbc-url

    // Configure which instance and what database user to connect with.
    config.setJdbcUrl(String.format("jdbc:postgresql:///%s", DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", _postgres"
    config.setPassword(DB_PASS); // e.g. "my-password"

    config.addDataSourceProperty("socketFactory", "com.google.cloud.sql.postgres.SocketFactory");
    config.addDataSourceProperty("cloudSqlInstance", INSTANCE_CONNECTION_NAME);

    // Unix sockets are not natively supported in Java, so it is necessary to use the Cloud SQL
    // Java Connector to connect. When setting INSTANCE_UNIX_SOCKET, the connector will 
    // call an external package that will enable Unix socket connections.
    // Note: For Java users, the Cloud SQL Java Connector can provide authenticated connections
    // which is usually preferable to using the Cloud SQL Proxy with Unix sockets.
    // See https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory for details.
    if (INSTANCE_UNIX_SOCKET != null) {
      config.addDataSourceProperty("unixSocketPath", INSTANCE_UNIX_SOCKET);
    }


    // cloudSqlRefreshStrategy set to "lazy" is used to perform a
    // refresh when needed, rather than on a scheduled interval.
    // This is recommended for serverless environments to
    // avoid background refreshes from throttling CPU.
    config.addDataSourceProperty("cloudSqlRefreshStrategy", "lazy");

    // ... Specify additional connection properties here.
    // ...

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

Node.js

Untuk melihat cuplikan ini dalam konteks aplikasi web, lihat README di GitHub.

const Knex = require('knex');

// createUnixSocketPool initializes a Unix socket connection pool for
// a Cloud SQL instance of Postgres.
const createUnixSocketPool = async config => {
  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  return Knex({
    client: 'pg',
    connection: {
      user: process.env.DB_USER, // e.g. 'my-user'
      password: process.env.DB_PASS, // e.g. 'my-user-password'
      database: process.env.DB_NAME, // e.g. 'my-database'
      host: process.env.INSTANCE_UNIX_SOCKET, // e.g. '/cloudsql/project:region:instance'
    },
    // ... Specify additional properties here.
    ...config,
  });
};

C#

Untuk melihat cuplikan ini dalam konteks aplikasi web, lihat README di GitHub.

using Npgsql;
using System;

namespace CloudSql
{
    public class PostgreSqlUnix
    {
        public static NpgsqlConnectionStringBuilder NewPostgreSqlUnixSocketConnectionString()
        {
            // Equivalent connection string:
            // "Server=<INSTANCE_UNIX_SOCKET>;Uid=<DB_USER>;Pwd=<DB_PASS>;Database=<DB_NAME>"
            var connectionString = new NpgsqlConnectionStringBuilder()
            {
                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = SslMode.Disable,

                // Note: Saving credentials in environment variables is convenient, but not
                // secure - consider a more secure solution such as
                // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
                // keep secrets safe.
                Host = Environment.GetEnvironmentVariable("INSTANCE_UNIX_SOCKET"), // e.g. '/cloudsql/project:region:instance'
                Username = Environment.GetEnvironmentVariable("DB_USER"), // e.g. 'my-db-user
                Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

Go

Untuk melihat cuplikan ini dalam konteks aplikasi web, lihat README di GitHub.

package cloudsql

import (
	"database/sql"
	"fmt"
	"log"
	"os"

	// Note: If connecting using the App Engine Flex Go runtime, use
	// "github.com/jackc/pgx/stdlib" instead, since v5 requires
	// Go modules which are not supported by App Engine Flex.
	_ "github.com/jackc/pgx/v5/stdlib"
)

// connectUnixSocket initializes a Unix socket connection pool for
// a Cloud SQL instance of Postgres.
func connectUnixSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Fatal Error in connect_unix.go: %s environment variable not set.\n", k)
		}
		return v
	}
	// Note: Saving credentials in environment variables is convenient, but not
	// secure - consider a more secure solution such as
	// Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
	// keep secrets safe.
	var (
		dbUser         = mustGetenv("DB_USER")              // e.g. 'my-db-user'
		dbPwd          = mustGetenv("DB_PASS")              // e.g. 'my-db-password'
		unixSocketPath = mustGetenv("INSTANCE_UNIX_SOCKET") // e.g. '/cloudsql/project:region:instance'
		dbName         = mustGetenv("DB_NAME")              // e.g. 'my-database'
	)

	dbURI := fmt.Sprintf("user=%s password=%s database=%s host=%s",
		dbUser, dbPwd, dbName, unixSocketPath)

	// dbPool is the pool of database connections.
	dbPool, err := sql.Open("pgx", dbURI)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %w", err)
	}

	// ...

	return dbPool, nil
}

Ruby

Untuk melihat cuplikan ini dalam konteks aplikasi web, lihat README di GitHub.

unix: &unix
  adapter: postgresql
  # Configure additional properties here.
  # Note: Saving credentials in environment variables is convenient, but not
  # secure - consider a more secure solution such as
  # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  # keep secrets safe.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  # Specify the Unix socket path as host
  host: "<%= ENV["INSTANCE_UNIX_SOCKET"] %>"

PHP

Untuk melihat cuplikan ini dalam konteks aplikasi web, lihat README di GitHub.

namespace Google\Cloud\Samples\CloudSQL\Postgres;

use PDO;
use PDOException;
use RuntimeException;
use TypeError;

class DatabaseUnix
{
    public static function initUnixDatabaseConnection(): PDO
    {
        try {
            // Note: Saving credentials in environment variables is convenient, but not
            // secure - consider a more secure solution such as
            // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
            // keep secrets safe.
            $username = getenv('DB_USER'); // e.g. 'your_db_user'
            $password = getenv('DB_PASS'); // e.g. 'your_db_password'
            $dbName = getenv('DB_NAME'); // e.g. 'your_db_name'
            $instanceUnixSocket = getenv('INSTANCE_UNIX_SOCKET'); // e.g. '/cloudsql/project:region:instance'

            // Connect using UNIX sockets
            $dsn = sprintf(
                'pgsql:dbname=%s;host=%s',
                $dbName,
                $instanceUnixSocket
            );

            // Connect to the database.
            $conn = new PDO(
                $dsn,
                $username,
                $password,
                # ...
            );
        } catch (TypeError $e) {
            throw new RuntimeException(
                sprintf(
                    'Invalid or missing configuration! Make sure you have set ' .
                        '$username, $password, $dbName, ' .
                        'and $instanceUnixSocket (for UNIX socket mode). ' .
                        'The PHP error was %s',
                    $e->getMessage()
                ),
                (int) $e->getCode(),
                $e
            );
        } catch (PDOException $e) {
            throw new RuntimeException(
                sprintf(
                    'Could not connect to the Cloud SQL Database. Check that ' .
                        'your username and password are correct, that the Cloud SQL ' .
                        'proxy is running, and that the database exists and is ready ' .
                        'for use. For more assistance, refer to %s. The PDO error was %s',
                    'https://cloud.google.com/sql/docs/postgres/connect-external-app',
                    $e->getMessage()
                ),
                (int) $e->getCode(),
                $e
            );
        }

        return $conn;
    }
}

Topik tambahan

Argumen command line Cloud SQL Auth Proxy

Contoh di atas mencakup kasus penggunaan paling umum, tetapi Cloud SQL Auth Proxy juga memiliki opsi konfigurasi lain yang dapat disetel dengan argumen command line. Untuk mendapatkan bantuan terkait argumen command line, gunakan flag --help untuk melihat dokumentasi terbaru:

./cloud-sql-proxy --help

Lihat README di repositori GitHub Cloud SQL Auth Proxy untuk menemukan contoh tambahan terkait cara menggunakan opsi command line Cloud SQL Auth Proxy.

Opsi untuk mengautentikasi Cloud SQL Auth Proxy

Saat mengautentikasi Cloud SQL Auth Proxy, Anda mengaktifkannya untuk mengakses Google Cloud atas nama aplikasi Anda, menggunakan serangkaian kredensial Google. Tindakan ini terpisah dari autentikasi pengguna database. Autentikasi database pengguna IAM terintegrasi dengan Cloud SQL Auth Proxy.

Semua opsi ini menggunakan INSTANCE_CONNECTION_NAME sebagai string koneksi untuk mengidentifikasi instance Cloud SQL. Anda dapat menemukan INSTANCE_CONNECTION_NAME pada halaman Ringkasan untuk instance dalam konsolGoogle Cloud . atau dengan menjalankan perintah berikut:

gcloud sql instances describe --project PROJECT_ID INSTANCE_CONNECTION_NAME.

Sebagai contoh: gcloud sql instances describe --project myproject myinstance .

Beberapa opsi ini menggunakan file kredensial JSON yang mencakup kunci pribadi RSA untuk akun tersebut. Untuk menemukan petunjuk terkait cara membuat file kredensial JSON untuk akun layanan, lihat Membuat akun layanan.

Proxy Auth Cloud SQL menyediakan beberapa alternatif untuk autentikasi tergantung pada lingkungan. Cloud SQL Auth Proxy memeriksa setiap item berikut, sesuai urutan berikut, menggunakan item pertama yang ditemukan untuk mencoba melakukan autentikasi:

1. Kredensial yang disediakan oleh flag file kredensial.

   Gunakan akun layanan untuk membuat dan mendownload file JSON terkait, serta tetapkan flag --credentials-file ke jalur file saat Anda memulai Cloud SQL Auth Proxy. Akun layanan harus memiliki izin yang diperlukan untuk instance Cloud SQL.

   Untuk menggunakan opsi ini pada command line, panggil perintah cloud-sql-proxy dengan flag --credentials-file yang ditetapkan ke nama file dan jalur file kredensial JSON. Jalur tersebut dapat bersifat absolut atau relatif sesuai direktori kerja saat ini. Contoh:

   ./cloud-sql-proxy --credentials-file PATH_TO_KEY_FILE \
   INSTANCE_CONNECTION_NAME
     

   Untuk informasi lebih lanjut terkait cara menambahkan peran IAM ke akun layanan, lihat Memberikan peran ke Akun Layanan.

   Untuk informasi lebih lanjut terkait peran yang didukung Cloud SQL, lihat Peran IAM untuk Cloud SQL.

2. Kredensial yang disediakan oleh token akses.

   Buat token akses dan panggil perintah cloud-sql-proxy dengan flag --token yang ditetapkan ke token akses OAuth 2.0. Contoh:

   ./cloud-sql-proxy --token ACCESS_TOKEN \
   INSTANCE_CONNECTION_NAME
     

3. Kredensial yang disediakan oleh variabel lingkungan.

   Opsi ini mirip dengan menggunakan flag --credentials-file, kecuali Anda menentukan file kredensial JSON yang ditetapkan dalam GOOGLE_APPLICATION_CREDENTIALS variabel lingkungan daripada menggunakan argumen command line --credentials-file.

4. Kredensial dari klien gcloud CLI yang diautentikasi.

   Apabila Anda telah menginstal gcloud CLI dan melakukan autentikasi dengan akun pribadi, Proxy Auth Cloud SQL dapat menggunakan kredensial akun yang sama. Metode ini sangat membantu untuk mendapatkan lingkungan pengembangan dan menjalankannya.

   Untuk mengaktifkan Cloud SQL Auth Proxy agar dapat menggunakan kredensial gcloud CLI Anda, gunakan perintah berikut untuk mengautentikasi gcloud CLI:

   gcloud auth application-default login

5. Kredensial yang terkait dengan instance Compute Engine.

   Jika terhubung ke Cloud SQL dari instance Compute Engine, Cloud SQL Auth Proxy dapat menggunakan akun layanan yang terkait dengan instance Compute Engine. Jika akun layanan memiliki izin yang diperlukan untuk instance Cloud SQL, Cloud SQL Auth Proxy akan berhasil melakukan autentikasi.

   Jika instance Compute Engine berada dalam project yang sama dengan instance Cloud SQL, akun layanan default untuk instance Compute Engine memiliki izin yang diperlukan untuk mengautentikasi Cloud SQL Auth Proxy. Apabila kedua instance berada di project berbeda, Anda harus menambahkan akun layanan instance Compute Engine ke project yang berisi instance Cloud SQL.

6. Akun layanan default lingkungan

   Jika Cloud SQL Auth Proxy tidak dapat menemukan kredensial di tempat mana pun yang telah dibahas sebelumnya, proxy tersebut mengikuti logika yang didokumentasikan dalam Menyiapkan Autentikasi untuk Aplikasi Produksi Server ke Server. Beberapa lingkungan (seperti Compute Engine, App Engine, dan lainnya) menyediakan akun layanan default yang dapat digunakan oleh aplikasi untuk melakukan autentikasi secara default. Apabila menggunakan akun layanan, akun tersebut harus memiliki izin yang diuraikan dalam peran dan izin Untuk informasi lebih lanjut terkait pendekatan autentikasi Google Cloud, lihat Ringkasan autentikasi.

Membuat akun layanan

Apabila menghubungkan dari Compute Engine, pastikan VM memiliki scope yang tepat agar terhubung menggunakan Cloud SQL Admin API.

Konfigurasi akun layanan untuk memiliki salah satu dari cakupan akses berikut:

• https://www.googleapis.com/auth/sqlservice.admin
• https://www.googleapis.com/auth/cloud-platform

1. Di konsol Google Cloud , buka halaman Service accounts.

   Buka halaman Service accounts

2. Pilih project yang berisi instance Cloud SQL.
3. Klik Create service account.
4. Pada kolom Nama akun layanan, masukkan nama deskriptif untuk akun tersebut.
5. Ubah ID akun layanan menjadi nilai yang unik dan dapat dikenali, kemudian klik Buat dan lanjutkan.
6. Klik kolom Pilih peran dan pilih salah satu dari peran berikut:
   • Cloud SQL > Klien Cloud SQL
   • Cloud SQL > Editor Cloud SQL
   • Cloud SQL > Admin Cloud SQL
   Catatan: Untuk membuat akun layanan dengan izin yang diperlukan, Anda harus memiliki resourcemanager.projects.setIamPolicy izin. Izin ini termasuk dalam Project Owner, Admin Project IAM, dan peran Organization Administrator.
   Anda juga harus mengaktifkan Cloud SQL Admin API. Apabila menggunakan peran project lama (Viewer, Editor, Owner), setidaknya akun layanan harus memiliki peran Editor.
7. Klik Selesai untuk menyelesaikan pembuatan akun layanan.
8. Klik menu tindakan untuk akun layanan baru kemudian pilih Mengelola kunci.
9. Klik menu drop-down Tambahkan kunci kemudian klik Buat kunci baru.
10. Lakukan konfirmasi bahwa jenis kunci tersebut adalah JSON kemudian klik Buat.

    File kunci pribadi telah didownload ke mesin. Anda dapat memindahkan file tersebut ke lokasi lain. Jaga agar file kunci tetap aman.

Menggunakan Cloud SQL Auth Proxy dengan IP pribadi

Untuk terhubung ke instance Cloud SQL menggunakan IP pribadi, Cloud SQL Auth Proxy harus berada di resource yang memiliki akses ke Jaringan VPC yang sama dengan instance.

Proxy Auth Cloud SQL menggunakan IP untuk membangun koneksi dengan instance Cloud SQL. Secara default, Cloud SQL Auth Proxy mencoba untuk terhubung menggunakan alamat IPv4 publik.

Jika instance Cloud SQL Anda hanya memiliki IP pribadi atau instance memiliki IP publik dan pribadi yang dikonfigurasi, dan Anda ingin Cloud SQL Auth Proxy menggunakan alamat IP pribadi, Anda harus memberikan opsi berikut saat memulai Cloud SQL Auth Proxy:

--private-ip

Menggunakan Cloud SQL Auth Proxy untuk terhubung ke endpoint tulis

Anda dapat menggunakan Cloud SQL Auth Proxy untuk terhubung ke instance utama Cloud SQL yang dikonfigurasi dengan endpoint tulis. Endpoint tulis adalah nama layanan Domain Name System (DNS) global yang dapat Anda gunakan untuk koneksi, bukan alamat IP untuk pemulihan dari bencana (DR) tingkat lanjut seperti melakukan failover replika atau operasi pengalihan. Jika operasi failover atau pengalihan replika terjadi untuk instance utama, Cloud SQL Auth Proxy akan otomatis mendeteksi perubahan pada data DNS.

Untuk mengetahui informasi selengkapnya tentang cara menggunakan Cloud SQL Auth Proxy untuk terhubung ke endpoint tulis, lihat Menghubungkan klien database ke instance menggunakan Cloud SQL Auth Proxy atau Cloud SQL Language Connectors.

Menggunakan Cloud SQL Auth Proxy dengan instance yang mengaktifkan Private Service Connect

Anda dapat menggunakan Cloud SQL Auth Proxy untuk terhubung ke instance Cloud SQL dengan Private Service Connect yang diaktifkan.

Cloud SQL Auth Proxy adalah konektor yang memberikan akses aman ke instance ini tanpa memerlukan jaringan resmi atau untuk mengonfigurasi SSL.

Untuk mengizinkan koneksi klien Cloud SQL Auth Proxy, Anda harus menyiapkan data DNS yang cocok dengan nama DNS yang direkomendasikan, yang disediakan untuk instance. Pencatatan DNS adalah pemetaan antara sumber daya DNS dan nama domain.

Untuk mengetahui informasi selengkapnya tentang cara menggunakan Cloud SQL Auth Proxy untuk terhubung ke instance dengan Private Service Connect yang diaktifkan, lihat Terhubung menggunakan Cloud SQL Auth Proxy.

Menjalankan Cloud SQL Auth Proxy dalam proses terpisah

Menjalankan Cloud SQL Auth Proxy dalam proses terminal Cloud Shell terpisah berguna untuk menghindari percampuran output konsol tersebut dengan output program lainnya. Gunakan sintaksis yang ditampilkan di bawah ini untuk memanggil Cloud SQL Auth Proxy dalam proses terpisah.

Linux

Pada Linux atau macOS, gunakan tanda penghubung & pada command line untuk meluncurkan Cloud SQL Auth Proxy dalam proses terpisah:

./cloud-sql-proxy INSTANCE_CONNECTION_NAME
  --credentials-file PATH_TO_KEY_FILE &

Windows

Pada Windows PowerShell, gunakan perintah Start-Process untuk meluncurkan Cloud SQL Auth Proxy dalam proses terpisah:

Start-Process --filepath "cloud-sql-proxy.exe"
  --ArgumentList "
  --credentials-file PATH_TO_KEY_FILEINSTANCE_CONNECTION_NAME"

Menjalankan Cloud SQL Auth Proxy di container Docker

Untuk menjalankan Cloud SQL Auth Proxy pada container Docker, gunakan image Docker Cloud SQL Auth Proxy yang tersedia dari Google Container Registry. Anda dapat menginstal image Docker Cloud SQL Auth Proxy menggunakan perintah berikut:

docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.26.2

Anda dapat memulai Cloud SQL Auth Proxy menggunakan soket TCP atau soket Unix, dengan perintah yang ditampilkan di bawah ini.

Catatan: Soket Unix tidak didukung untuk aplikasi yang ditulis dengan bahasa pemrograman Java atau untuk lingkungan Windows.

Soket TCP

docker run -d \
  -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \
  -p 127.0.0.1:5432:5432 \
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.26.2 \
  --address 0.0.0.0 --port 5432 \
  --credentials-file /path/to/service-account-key.json \
  INSTANCE_CONNECTION_NAME

Selalu tentukan awalan 127.0.0.1 di -p agar Cloud SQL Auth Proxy tidak terekspos di luar host lokal. Flag --address 0.0.0.0 diperlukan agar port dapat diakses dari luar container Docker.

Soket Unix

docker run -d \
  -v /cloudsql:/cloudsql \
  -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.26.2 \
  --unix-socket /cloudsql \
  --credentials-file /path/to/service-account-key.json \
  INSTANCE_CONNECTION_NAME

Jika Anda menggunakan image yang dioptimalkan untuk container, gunakan direktori yang dapat ditulis sebagai pengganti /cloudsql, misalnya:

-v /mnt/stateful_partition/cloudsql:/cloudsql

Jika Anda menggunakan kredensial yang disediakan oleh instance Compute Engine, jangan sertakan parameter --credentials-file dan baris -v PATH_TO_KEY_FILE:/path/to/service-account-key.json.

Menjalankan Cloud SQL Auth Proxy sebagai layanan

Menjalankan Cloud SQL Auth Proxy sebagai layanan latar belakang adalah opsi untuk pengembangan lokal dan beban kerja produksi. Ketika perlu mengakses instance Cloud SQL dalam pengembangan, Anda dapat memulai layanan di latar belakang dan menghentikannya setelah selesai.

Proxy Auth Cloud SQL saat ini tidak menyediakan dukungan bawaan untuk dijalankan sebagai layanan Windows, namun pengelola layanan pihak ketiga dapat digunakan untuk menjalankan proxy sebagai layanan untuk beban kerja produksi. Misalnya, Anda dapat menggunakan NSSM untuk mengonfigurasi Cloud SQL Auth Proxy sebagai layanan Windows, dan NSSM akan memantau Cloud SQL Auth Proxy dan memulai ulang secara otomatis jika berhenti merespons. Lihat Dokumentasi NSSM untuk informasi lebih lanjut.

Catatan: Apabila menjalankan Cloud SQL Auth Proxy sebagai layanan, perhatikan bahwa layanan tersebut menggunakan koneksi yang aman untuk berkomunikasi dengan instance Cloud SQL, tetapi koneksi dari aplikasi ke Cloud SQL Auth Proxy tidak dienkripsi. Oleh karena itu, pastikan bahwa hanya pengguna tepercaya yang dapat mengakses alamat dan port yang dipantau oleh Cloud SQL Auth Proxy.

Menerapkan penggunaan Proxy Auth Cloud SQL

Aktifkan penggunaan Cloud SQL Auth Proxy di Cloud SQL menggunakan ConnectorEnforcement.

Jika Anda menggunakan instance yang mendukung Private Service Connect, ada batasan. Jika instance mengaktifkan penerapan konektor, Anda tidak dapat membuat replika baca untuk instance tersebut. Demikian pula, jika instance memiliki replika baca, Anda tidak dapat mengaktifkan penerapan konektor untuk instance tersebut.

gcloud

Perintah berikut menerapkan penggunaan konektor Cloud SQL.

    gcloud sql instances patch INSTANCE_NAME \
    --connector-enforcement REQUIRED
  

Untuk menonaktifkan penerapan tersebut, gunakan baris kode berikut: --connector-enforcement NOT_REQUIRED Pembaruan tidak akan memicu mulai ulang.

REST v1

Perintah berikut menerapkan konektor Cloud SQL

Sebelum menggunakan data permintaan apa pun, lakukan penggantian sebagai berikut:

• project-id: Project ID.
• instance-id: ID instance.

Metode HTTP dan URL:

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

Meminta isi JSON:

{
  "settings": {                     
    "connectorEnforcement": "REQUIRED"    
  }                                             
}   

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan 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 saat ini aktif dengan menjalankan gcloud auth list.

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

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id"

PowerShell (Windows)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang saat ini 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 PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id" | Select-Object -Expand Content

Anda akan menerima respons JSON serupa dengan yang berikut ini:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

Untuk menonaktifkan penerapan, gunakan "connectorEnforcement": "NOT_REQUIRED" sebagai gantinya. Pembaruan tersebut tidak memicu mulai ulang.

REST v1beta4

Perintah berikut menerapkan penggunaan konektor Cloud SQL.

Sebelum menggunakan data permintaan apa pun, lakukan penggantian sebagai berikut:

• project-id: Project ID.
• instance-id: ID instance.

Metode HTTP dan URL:

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

Meminta isi JSON:

{
  "settings": {
    "connectorEnforcement": "REQUIRED"
  }
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan 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 saat ini aktif dengan menjalankan gcloud auth list.

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

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id"

PowerShell (Windows)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang saat ini 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 PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id" | Select-Object -Expand Content

Anda akan menerima respons JSON serupa dengan yang berikut ini:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

Untuk menonaktifkan penerapan, gunakan "connectorEnforcement": "NOT_REQUIRED" sebagai gantinya. Pembaruan tersebut tidak memicu mulai ulang.

Tips saat menggunakan Cloud SQL Auth Proxy

Memanggil Cloud SQL Auth Proxy

Semua contoh pemanggilan proxy memulai Cloud SQL Auth Proxy di latar belakang, sehingga prompt akan ditampilkan. Cadangkan terminal Cloud Shell untuk Proxy Auth Cloud SQL agar terhindar dari percampuran output tersebut dengan output program lain. Selain itu, output dari Cloud SQL Auth Proxy dapat membantu mendiagnosis masalah koneksi sehingga akan membantu merekam file log. Jika Anda tidak memulai Cloud SQL Auth Proxy di latar belakang, output akan masuk ke stdout kecuali jika dialihkan.

Anda tidak perlu menggunakan /cloudsql sebagai direktori untuk soket Cloud SQL Auth Proxy. (Nama direktori tersebut dipilih untuk meminimalisir perbedaan dengan string koneksi App Engine.) Tetap perhatikan panjang keseluruhan minimum apabila ingin mengubah nama direktori; nama tersebut dimasukkan dalam string lebih panjang dengan batas panjang yang diberlakukan oleh sistem operasi. Batas panjang tersebut tergantung pada sistem, biasanya di antara 91-108 karakter. Di Linux, panjang tersebut ditetapkan sebagai 108 dan Anda dapat memeriksanya menggunakan perintah berikut:

cat /usr/include/linux/un.h | grep "define UNIX_PATH_MAX"

Menggunakan Cloud SQL Auth Proxy untuk terhubung ke beberapa instance

Anda dapat menggunakan satu klien Cloud SQL Auth Proxy lokal untuk terhubung dengan beberapa instance Cloud SQL. Cara melakukannya tergantung pada pilihan untuk menggunakan soket Unix atau TCP.

Soket Unix

Untuk menghubungkan Cloud SQL Auth Proxy ke beberapa instance, Anda perlu menyediakan setiap nama koneksi instance sebagai argumen bagi Cloud SQL Auth Proxy dalam daftar yang dipisahkan spasi. Proxy Auth Cloud SQL terhubung ke setiap instance ketika dimulai.

Anda terhubung ke setiap instance menggunakan soket proxy tersebut di direktori yang telah ditentukan.

Contoh:

      ./cloud-sql-proxy --unix-socket /cloudsql \
      myProject:us-central1:myInstance myProject:us-central1:myInstance2 &
      psql -U myUser -h /cloudsql/myProject:us-central1:myInstance2
  

Soket TCP

Ketika terhubung menggunakan TCP, Anda menentukan port pada mesin untuk Cloud SQL Auth Proxy yang akan dipantau untuk setiap instance Cloud SQL. Ketika menghubungkan ke berbagai instance Cloud SQL, setiap port yang telah ditentukan harus unik dan tersedia untuk digunakan pada mesin.

Contoh:

    # Start the Cloud SQL Auth Proxy to connect to two different Cloud SQL instances
    # Give the Cloud SQL Auth Proxy a unique port on your machine to use for each Cloud SQL instance.

    ./cloud-sql-proxy "myProject:us-central1:myInstance?port=5432" \
    "myProject:us-central1:myInstance2?port=1234"

    # Connect to "myInstance" using port 5432 on your machine:
    psql -U myUser -h 127.0.0.1  --port 5432

    # Connect to "myInstance2" using port 1234 on your machine:
    psql -U myUser -h 127.0.0.1  --port 1234
  

Memecahkan masalah koneksi Cloud SQL Auth Proxy

Image Docker Cloud SQL Auth Proxy didasarkan pada versi tertentu dari Cloud SQL Auth Proxy. Ketika versi baru Cloud SQL Auth Proxy tersedia, tarik image Docker Cloud SQL Auth Proxy versi baru untuk menjaga lingkungan Anda tetap yang terbaru. Anda dapat melihat versi terbaru Cloud SQL Auth Proxy dengan memeriksa halaman rilis GitHub Cloud SQL Auth Proxy.

Jika mendapat masalah saat menghubungkan ke instance Cloud SQL menggunakan Proxy Auth Cloud SQL, the Cloud SQL Auth Proxy, berikut adalah beberapa hal yang dapat dilakukan untuk menemukan penyebab masalah tersebut.

• Periksa output Cloud SQL Auth Proxy.

  Output Cloud SQL Auth Proxy sering kali dapat membantu menentukan sumber masalah dan bagaimana menyelesaikan masalah tersebut. Masukkan output ke file atau perhatikan terminal Cloud Shell tempat Anda memulai Cloud SQL Auth Proxy.

• Jika Anda menemukan error 403 notAuthorized dan sedang menggunakan akun layanan untuk mengautentikasi Cloud SQL Auth Proxy, pastikan akun layanan tersebut memiliki izin yang tepat.

  Anda dapat mengecek akun layanan dengan menelusuri ID akun tersebut pada Halaman IAM. Akun tersebut harus memiliki izin cloudsql.instances.connect. Peran yang telah ditetapkan Cloud SQL Admin, Client dan Editor memiliki izin ini.

• Jika terhubung dari App Engine dan menemukan 403 notAuthorized error, periksa nilai app.yaml cloud_sql_instances untuk mencari nama koneksi instance yang tidak tepat atau salah eja. Nama koneksi instance biasanya sesuai dengan format PROJECT:REGION:INSTANCE.

  Selain itu, periksa apakah akun layanan App Engine (misalnya, $[e-mail]) memiliki peran IAM Klien Cloud SQL.

  Apabila layanan App Engine berada dalam salah satu project (project A) dan database berada di project lainnya (project B), error ini berarti akun layanan App Engine belum diberi peran IAM Klien Cloud SQL dalam project yang berisi database (project B).

• Pastikan untuk mengaktifkan Cloud SQL Admin API.

  Jika tidak, Anda akan melihat output seperti Error 403: Access Not Configured dalam log Cloud SQL Auth Proxy.

• Apabila menyertakan beberapa instance dalam daftar, pastikan untuk menggunakan koma sebagai pembatas tanpa spasi. Apabila menggunakan TCP, pastikan untuk menentukan port yang berbeda bagi setiap instance.

• Apabila terhubung menggunakan soket Unix, lakukan konfirmasi bahwa soket tersebut telah dibuat dengan mencantumkan direktori yang disediakan saat memulai Proxy Auth Cloud SQL.

• Apabila terdapat kebijakan firewall keluar, pastikan kebijakan tersebut mengizinkan koneksi ke port 3307 pada instance Cloud SQL target.

  Catatan: Proxy Auth Cloud SQL menggunakan 3307 untuk terhubung ke server Proxy Auth Cloud SQL. Port 5432 adalah port default untuk protokol PostgreSQL melalui koneksi TCP langsung (tanpa menggunakan Cloud SQL Auth Proxy).

• Anda dapat memastikan bahwa Cloud SQL Auth Proxy dimulai dengan benar dengan melihat log di bagian Operations > Logging > Logs explorer pada konsolGoogle Cloud . Operasi yang berhasil akan terlihat seperti berikut:

  2021/06/14 15:47:56 Listening on /cloudsql/$PROJECT_ID:$REGION:$INSTANCE_NAME/5432 for $PROJECT_ID:$REGION:$INSTANCE_NAME
  2021/06/14 15:47:56 Ready for new connections
  

• Masalah kuota: Apabila kuota Cloud SQL Admin API dilanggar, Cloud SQL Auth Proxy akan dimulai dengan pesan error berikut:

  There was a problem when parsing a instance configuration but ignoring due
  to the configuration. Error: googleapi: Error 429: Quota exceeded for quota
  metric 'Queries' and limit 'Queries per minute per user' of service
  'sqladmin.googleapis.com' for consumer 'project_number:$PROJECT_ID.,
  rateLimitExceeded
  

  Setelah aplikasi terhubung ke proxy, akan muncul laporan error seperti berikut:

  failed to refresh the ephemeral certificate for $INSTANCE_CONNECTION_NAME:
  googleapi: Error 429: Quota exceeded for quota metric 'Queries' and limit
  'Queries per minute per user' of service 'sqladmin.googleapis.com' for
  consumer 'project_number:$PROJECT_ID., rateLimitExceeded
  

  Solusi: Identifikasi sumber masalah kuota, sebagai contoh, aplikasi menyalahgunakan konektor dan membuat koneksi baru yang tidak perlu, atau hubungi dukungan untuk meminta peningkatan kuota Cloud SQL Admin API. Apabila error kuota muncul saat memulai, aplikasi harus di-deploy kembali untuk memulai ulang proxy. Apabila error kuota muncul setelah memulai, deploy ulang tidak perlu dilakukan.

Langkah berikutnya

• Pelajari lebih lanjut Cloud SQL Auth Proxy.
• Pelajari lebih lanjut terkait Identity and Access Management (IAM).
• Pelajari lebih lanjut tentang Akun Layanan.
• Pelajari tentang dua level kontrol akses untuk instance Cloud SQL.
• Buat pengguna dan database.
• Pelajari bagaimana cara untuk menghubungkan ke instance dari aplikasi.
• Pelajari tentang Klien psql.
• Pelajari tentang opsi dukungan.