Terhubung menggunakan Proxy Auth Cloud SQL

MySQL   |  PostgreSQL   |  SQL Server

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

Untuk informasi lebih lanjut, terkait cara kerja Proxy Auth Cloud SQL, lihat Tentang Proxy Auth Cloud SQL.

Ringkasan

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

• 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 Proxy Auth Cloud SQL untuk menyediakan koneksi bagi jalur IP publik dengan enkripsi dan otorisasi, termasuk:

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

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

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

Lihat Panduan memulai menggunakan Proxy Auth Cloud SQL untuk mengetahui pengantar dasar penggunaannya.

Anda juga dapat terhubung, dengan atau tanpa Proxy Auth Cloud SQL, menggunakan klien mysql 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 API Cloud SQL Admin.

   Mengaktifkan API

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

Mendownload Proxy Auth Cloud SQL

Linux 64 bit

1. Download Proxy Auth Cloud SQL:

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

2. Buat Proxy Auth Cloud SQL agar dapat dieksekusi:

   chmod +x cloud-sql-proxy

Linux 32 bit

1. Download Proxy Auth Cloud SQL:

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

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

   chmod +x cloud-sql-proxy

macOS 64-bit

1. Download Proxy Auth Cloud SQL:

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

2. Buat Proxy Auth Cloud SQL agar dapat dieksekusi:

   chmod +x cloud-sql-proxy

Mac M1

1. Download Proxy Auth Cloud SQL:

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

2. Buat Proxy Auth Cloud SQL agar dapat dieksekusi:

     chmod +x cloud-sql-proxy
     

Windows 64 bit

Klik kanan https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/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.13.0/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 Proxy Auth Cloud SQL

Auth Proxy Cloud SQL memiliki image container yang berbeda, seperti distroless, alpine, dan buster. Image container Cloud SQL Auth Proxy default digunakan distroless, yang tidak mengandung {i>shell<i}. Jika Anda membutuhkan {i>shell<i} atau alat terkait, maka unduh {i>image<i} berdasarkan alpine atau buster. Untuk informasi selengkapnya, lihat Image Container Proxy Auth Cloud SQL.

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

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

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

OS Lainnya

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

Memulai Proxy Auth Cloud SQL

Anda dapat memulai Proxy Auth Cloud SQL menggunakan soket TCP soket Unix, atau image Docker Proxy Aut Cloud SQL tergantung pada bahasa dan lingkungan. Biner Proxy Auth Cloud SQL terhubung ke salah satu atau beberapa instance Cloud SQL yang ditentukan pada command line dan membuka koneksi lokal instance 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: Hati-hati saat melakukan binding Proxy Auth Cloud SQL ke antarmuka eksternal. Siapa pun yang memiliki akses ke antarmuka/port tersebut akan diizinkan untuk terhubung ke instance.

Soket TCP

Proxy Auth Cloud SQL 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 Proxy Auth Cloud SQL 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. Ini dapat ditemukan pada halaman Overview untuk instance Anda dalam Konsol Google Cloud atau dengan menjalankan perintah berikut:

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

   Misalnya: myproject:myregion:myinstance.

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

   --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. Memulai Proxy Auth Cloud SQL.

   Beberapa string pemanggilan Proxy Auth Cloud SQL memungkinkan untuk:

   • Menggunakan autentikasi Cloud SDK:

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

     Port yang ditentukan harus belum digunakan, misalnya, 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 informasi selengkapnya tentang opsi Proxy Auth Cloud SQL, lihat Opsi untuk mengautentikasi Proxy Auth Cloud SQL.

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. Keuntungan menggunakan soket Unix adalah peningkatan keamanan dan latensi yang lebih rendah, namun, Anda tidak dapat mengakses soket Unix dari mesin eksternal.

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

1. Salin INSTANCE_CONNECTION_NAME. Ini dapat ditemukan pada halaman Overview untuk instance Anda dalam Konsol Google Cloud atau dengan menjalankan perintah berikut:

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

   Misalnya: myproject:myregion:myinstance.

2. Buat direktori di tempat soket Proxy Auth Cloud SQL 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 Proxy Auth Cloud SQL.

   Beberapa string pemanggilan Proxy Auth Cloud SQL memungkinkan untuk:

   • 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 Proxy Auth Cloud SQL pada terminal Cloud Shell itu sendiri sehingga Anda dapat memantau output tersebut tanpa bercampur dengan output program lain.

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

   CATATAN: Ketika menggunakan soket unix untuk terhubung ke Cloud SQL menggunakan Proxy Auth Cloud SQL, 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 Proxy Auth Cloud SQL pada container Docker, gunakan image Docker Proxy Auth Cloud SQL yang tersedia dari Google Container Registry.

Anda dapat memulai Proxy Auth Cloud SQL 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 pada halaman Ringkasan untuk instance dalam konsol Google Cloud. atau dengan menjalankan perintah berikut:

gcloud sql instances describe INSTANCE_NAME

.

Misalnya: myproject:myregion:myinstance.

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

Anda dapat memulai Proxy Auth Cloud SQL menggunakan soket TCP atau soket Unix tergantung pada bahasa dan lingkungan. 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:3306:3306 \\
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.13.0 \\
  --address 0.0.0.0 --port 3306 \\
  --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME

Apabila 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 pada -p sehingga Proxy Auth Cloud SQL tidak diekspos ke luar host lokal. "0.0.0.0" pada parameter instance 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.13.0 --unix-socket=/cloudsql \\
  --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME

Apabila 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

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

-v /mnt/stateful_partition/cloudsql:/cloudsql

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

Terhubung dengan klien mysql

1. Download MySQL Community Server untuk platform Anda dari halaman download MySQL Community Server.
   Server Komunitas mencakup klien MySQL.
2. Instal Server Komunitas, dengan mengikuti petunjuk di halaman download.

Untuk mengetahui informasi selengkapnya tentang cara menginstal MySQL, lihat Menginstal dan Mengupgrade MySQL.

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

Soket TCP

1. Mulai klien mysql:

   mysql -u USERNAME -p --host 127.0.0.1

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

2. Jika diminta, masukkan sandi.
3. Perintah mysql akan muncul.

Menggunakan soket Unix

1. Mulai klien mysql:

   mysql -u USERNAME -p -S /cloudsql/INSTANCE_CONNECTION_NAME

2. Masukkan sandi
3. Perintah mysql akan muncul.

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

Menghubungkan dengan aplikasi

Anda dapat terhubung ke Proxy Auth Cloud SQL dari berbagai bahasa yang membantu untuk 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 Proxy Auth Cloud SQL:

./cloud-sql-proxy INSTANCE_CONNECTION_NAME &

Python

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

import os

import sqlalchemy


def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    """Initializes a TCP connection pool for a Cloud SQL instance of MySQL."""
    # 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. 3306

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

Java

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

Catatan:

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

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

public class TcpConnectionPoolFactory extends ConnectionPoolFactory {

  // Saving credentials in environment variables is convenient, but not secure - consider a more
  // secure solution such as 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:mysql://<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:mysql://%s:%s/%s", INSTANCE_HOST, DB_PORT, DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "mysql"
    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 mysql = require('promise-mysql');
const fs = require('fs');

// createTcpPool initializes a TCP connection pool for a Cloud SQL
// instance of MySQL.
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 = {
    host: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
    port: process.env.DB_PORT, // e.g. '3306'
    user: process.env.DB_USER, // e.g. 'my-db-user'
    password: process.env.DB_PASS, // e.g. 'my-db-password'
    database: process.env.DB_NAME, // e.g. 'my-database'
    // ... Specify additional properties here.
    ...config,
  };
  // Establish a connection to the database.
  return mysql.createPool(dbConfig);
};

Go

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

package cloudsql

import (
	"crypto/tls"
	"crypto/x509"
	"database/sql"
	"errors"
	"fmt"
	"io/ioutil"
	"log"
	"os"

	"github.com/go-sql-driver/mysql"
)

// connectTCPSocket initializes a TCP connection pool for a Cloud SQL
// instance of MySQL.
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'
		dbName    = mustGetenv("DB_NAME")       // e.g. 'my-database'
		dbPort    = mustGetenv("DB_PORT")       // e.g. '3306'
		dbTCPHost = mustGetenv("INSTANCE_HOST") // e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
	)

	dbURI := fmt.Sprintf("%s:%s@tcp(%s:%s)/%s?parseTime=true",
		dbUser, dbPwd, dbTCPHost, dbPort, dbName)


	// dbPool is the pool of database connections.
	dbPool, err := sql.Open("mysql", 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 MySql.Data.MySqlClient;
using System;

namespace CloudSql
{
    public class MySqlTcp
    {
        public static MySqlConnectionStringBuilder NewMysqlTCPConnectionString()
        {
            // Equivalent connection string:
            // "Uid=<DB_USER>;Pwd=<DB_PASS>;Host=<INSTANCE_HOST>;Database=<DB_NAME>;"
            var connectionString = new MySqlConnectionStringBuilder()
            {
                // 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.
                Server = Environment.GetEnvironmentVariable("INSTANCE_HOST"),   // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                UserID = 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 = MySqlSslMode.Disabled,
            };
            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: mysql2
  # 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") { 3306 }%>

PHP

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

namespace Google\Cloud\Samples\CloudSQL\MySQL;

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('mysql: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/mysql/connect-external-app',
                    $e->getMessage()
                ),
                $e->getCode(),
                $e
            );
        }

        return $conn;
    }
}

Menghubungkan dengan soket Unix

Pernyataan pemanggilan Proxy Auth Cloud SQL:

./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 MySQL."""
    # 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:
        # mysql+pymysql://<db_user>:<db_pass>@/<db_name>?unix_socket=<socket_path>/<cloud_sql_instance_name>
        sqlalchemy.engine.url.URL.create(
            drivername="mysql+pymysql",
            username=db_user,
            password=db_pass,
            database=db_name,
            query={"unix_socket": unix_socket_path},
        ),
        # ...
    )
    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:mysql:///<DB_NAME>?cloudSqlInstance=<INSTANCE_CONNECTION_NAME>&
    // socketFactory=com.google.cloud.sql.mysql.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:mysql:///%s", DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "mysql"
    config.setPassword(DB_PASS); // e.g. "my-password"

    config.addDataSourceProperty("socketFactory", "com.google.cloud.sql.mysql.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);
    }


    // ... 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 mysql = require('promise-mysql');

// createUnixSocketPool initializes a Unix socket connection pool for
// a Cloud SQL instance of MySQL.
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 mysql.createPool({
    user: process.env.DB_USER, // e.g. 'my-db-user'
    password: process.env.DB_PASS, // e.g. 'my-db-password'
    database: process.env.DB_NAME, // e.g. 'my-database'
    socketPath: 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 MySql.Data.MySqlClient;
using System;

namespace CloudSql
{
    public class MySqlUnix
    {
        public static MySqlConnectionStringBuilder NewMysqlUnixSocketConnectionString()
        {
            // Equivalent connection string:
            // "Server=<INSTANCE_UNIX_SOCKET>;Uid=<DB_USER>;Pwd=<DB_PASS>;Database=<DB_NAME>;Protocol=unix"
            var connectionString = new MySqlConnectionStringBuilder()
            {
                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = MySqlSslMode.Disabled,

                // 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.
                Server = Environment.GetEnvironmentVariable("INSTANCE_UNIX_SOCKET"), // e.g. '/cloudsql/project:region:instance'
                UserID = 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'
                ConnectionProtocol = MySqlConnectionProtocol.UnixSocket
            };
            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"

	_ "github.com/go-sql-driver/mysql"
)

// connectUnixSocket initializes a Unix socket connection pool for
// a Cloud SQL instance of MySQL.
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.", 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'
		dbName         = mustGetenv("DB_NAME")              // e.g. 'my-database'
		unixSocketPath = mustGetenv("INSTANCE_UNIX_SOCKET") // e.g. '/cloudsql/project:region:instance'
	)

	dbURI := fmt.Sprintf("%s:%s@unix(%s)/%s?parseTime=true",
		dbUser, dbPwd, unixSocketPath, dbName)

	// dbPool is the pool of database connections.
	dbPool, err := sql.Open("mysql", 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: mysql2
  # 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
  socket: "<%= ENV["INSTANCE_UNIX_SOCKET"] %>"

PHP

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

namespace Google\Cloud\Samples\CloudSQL\MySQL;

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(
                'mysql:dbname=%s;unix_socket=%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/mysql/connect-external-app',
                    $e->getMessage()
                ),
                (int) $e->getCode(),
                $e
            );
        }

        return $conn;
    }
}

Topik tambahan

Argumen command line Proxy Auth Cloud SQL

Contoh di atas termasuk kasus penggunaan paling umum, namun Proxy Auth Cloud SQL 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 pada repositori GitHub Proxy Auth Cloud SQL untuk menemukan contoh tambahan terkait cara menggunakan opsi command line Proxy Auth Cloud SQL.

Opsi untuk mengautentikasi Proxy Auth Cloud SQL

Ketika mengautentikasi Proxy Auth Cloud SQL, Anda mengaktifkannya untuk mengakses Google Cloud atas nama aplikasi menggunakan seperangkat kredensial Google. Ini terpisah dari otentikasi pengguna database.

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 konsol Google 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. Proxy Auth Cloud SQL menggunakan item pertama yang ditemukan saat percobaan autentikasi untuk mengecek setiap item sesuai urutan berikut:

1. Kredensial yang disediakan oleh flag file kredensial.

   Gunakan akun layanan untuk membuat dan mendownload file JSON terkait dan tetapkan flag --credentials-file ke jalur file saat Anda memulai Proxy Auth Cloud SQL. 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 Proxy Auth Cloud SQL AGAR dapat menggunakan kredensial gcloud CLI, gunakan perintah berikut untuk mengautentikasi gcloud CLI:

   gcloud auth application-default login

5. Kredensial yang terkait dengan instance Compute Engine.

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

   Apabila 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 Proxy Auth Cloud SQL. 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

   Apabila Proxy Cloud SQL tidak dapat menemukan kredensial di tempat mana pun yang telah dibahas sebelumnya, proxy tersebut mengikuti logika yang didokumentasikan dalam Menyiapkan Autentikasi untuk Server ke Aplikasi Produksi 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 Proxy Auth Cloud SQL dengan IP pribadi

Untuk terhubung ke instance Cloud SQL menggunakan IP pribadi, Proxy Auth Cloud SQL harus berada pada resource dengan akses ke jaringan VPC yang sama sebagai instance.

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

Apabila instance Cloud SQL hanya memiliki IP pribadi atau instance tersebut memiliki IP pribadi dan publik yang dikonfigurasi kemudian ingin Proxy Auth Cloud SQL tersebut menggunakan alamat IP pribadi, maka Anda harus menyediakan opsi berikut ketika memulai Proxy Auth Cloud SQL:

--private-ip

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

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

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

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

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

Membuat akun pengguna database untuk Proxy Auth Cloud SQL

Saat terhubung ke instance menggunakan Proxy Auth Cloud SQL, Anda memberikan akun pengguna untuk login ke instance. Untuk tujuan ini, Anda dapat menggunakan akun pengguna database apa pun. Namun, karena Proxy Auth Cloud SQL selalu terhubung dari nama host yang tidak dapat diakses kecuali oleh Proxy Auth Cloud SQL, Anda dapat membuat akun pengguna yang hanya dapat digunakan oleh Proxy Auth Cloud SQL. Keuntungan melakukannya adalah Anda dapat menentukan akun ini tanpa sandi tanpa mengorbankan keamanan instance atau data Anda.

Untuk membuat akun pengguna yang hanya dapat digunakan dengan Proxy Auth Cloud SQL, tentukan nama host sebagai 'cloudsqlproxy~[IP_ADDRESS]'. Anda juga dapat menggunakan karakter pengganti alamat IP, yang akan menghasilkan 'cloudsqlproxy~%'. Nama lengkap akun pengguna adalah:

'[USER_NAME]'@'cloudsqlproxy~%'

atau

'[USER_NAME]'@'cloudsqlproxy~[IP_ADDRESS]'

Untuk bantuan dalam membuat pengguna, lihat Membuat dan Mengelola Pengguna. Untuk mengetahui informasi tentang cara kerja Cloud SQL dengan akun pengguna, lihat Pengguna.

Menjalankan Proxy Auth Cloud SQL dalam proses terpisah

Menjalankan Proxy Auth Cloud SQL 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 Proxy Auth Cloud SQL dalam proses terpisah.

Linux

Pada Linux atau macOS, gunakan tanda penghubung & pada command line untuk meluncurkan Proxy Auth Cloud SQL 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 Proxy Auth Cloud SQL dalam proses terpisah:

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

Menjalankan Proxy Auth Cloud SQL di container Docker

Untuk menjalankan Proxy Auth Cloud SQL pada container Docker, gunakan image Docker Proxy Auth Cloud SQL yang tersedia dari Google Container Registry. Anda dapat menginstal image Docker Proxy Auth Cloud SQL dengan perintahgcloud ini:

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

Anda dapat memulai Proxy Auth Cloud SQL 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:3306:3306 \
      gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.13.0 \
      --address 0.0.0.0 \
      --credentials-file /path/to/service-account-key.json \
      INSTANCE_CONNECTION_NAME

Soket Unix

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

Apabila menggunakan image yang dioptimalkan untuk kontainer, gunakan direktori yang dapat ditulis sebagai pengganti /cloudsql, sebagai contoh:

v /mnt/stateful_partition/cloudsql:/cloudsql

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

Menjalankan Proxy Auth Cloud SQL sebagai layanan

Menjalankan Proxy Auth Cloud SQL 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. Sebagai contoh, Anda dapat menggunakan NSSM untuk mengonfigurasi Proxy Auth Cloud SQL sebagai layanan Windows, kemudian NSSM memantau Proxy Auth Cloud SQL dan memulai ulang secara otomatis apabila berhenti merespons. Lihat Dokumentasi NSSM untuk informasi lebih lanjut.

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

Menerapkan penggunaan Proxy Auth Cloud SQL

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

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 masuk ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login , atau menggunakan Cloud Shell, yang otomatis memasukkan Anda ke CLI gcloud kami. 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 masuk ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login kami. 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 respon 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 masuk ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login , atau menggunakan Cloud Shell, yang otomatis memasukkan Anda ke CLI gcloud kami. 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 masuk ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login kami. 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 respon 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 Proxy Auth Cloud SQL

Memanggil Proxy Auth Cloud SQL

Semua contoh pemanggilan proxy memulai Proxy Auth Cloud SQL 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 Proxy Auth Cloud SQL dapat membantu mendiagnosis masalah koneksi sehingga akan membantu merekam file log. Jika tidak memulai Proxy Auth Cloud SQL di latar belakang, output tersebut akan masuk ke stdout kecuali jika dialihkan.

Anda tidak perlu menggunakan /cloudsql sebagai direktori untuk soket Proxy Auth Cloud SQL. (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 Proxy Auth Cloud SQL untuk terhubung ke beberapa instance

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

Soket Unix

Untuk menghubungkan Proxy Auth Cloud SQL ke beberapa instance, Anda perlu menyediakan setiap nama koneksi instance sebagai argumen bagi Proxy Auth Cloud SQL 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 &
      mysql -u myUser -S /cloudsql/myProject:us-central1:myInstance2
  

Soket TCP

Ketika terhubung menggunakan TCP, Anda menentukan port pada mesin untuk Proxy Auth Cloud SQL yang akan dipantau selama memproses 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=3306" \
    "myProject:us-central1:myInstance2?port=1234"

    # Connect to "myInstance" using port 3306 on your machine:
    mysql -u myInstanceUser --host 127.0.0.1  --port 3306

    # Connect to "myInstance2" using port 1234 on your machine:
    mysql -u myInstance2User --host 127.0.0.1  --port 1234
  

Memecahkan masalah koneksi Proxy Auth Cloud SQL

Image Docker Proxy Auth Cloud SQL berdasarkan versi tertentu Proxy Auth Cloud SQL. Ketika versi terbaru Proxy Auth Cloud SQL tersedia, tarik image Docker Proxy Auth Cloud SQL versi baru untuk menjaga lingkungan tetap menjadi yang terbaru. Lihat versi terbaru Proxy Auth Cloud SQL dengan mengecek halaman rilis Proxy Auth Cloud SQL.

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.

• Mengecek output Proxy Cloud SQL.

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

• Jika menemukan error 403 notAuthorized dan sedang menggunakan akun layanan untuk mengautentikasi Proxy Auth Cloud SQL, 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 memiliki peran IAM Klien Cloud SQL (sebagai contoh, $[e-mail]).

  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 Proxy Auth Cloud SQL.

• 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 3306 adalah port default untuk protokol MySQL melalui koneksi TCP langsung (tidak menggunakan Proxy Auth Cloud SQL).

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

  2021/06/14 15:47:56 Listening on /cloudsql/$PROJECT_ID:$REGION:$INSTANCE_NAME/3306 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, Proxy Auth Cloud SQL 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 tentang Proxy Auth Cloud SQL.
• Pelajari lebih lanjut terkait Identity and Access Management (IAM).
• Pelajari lebih lanjut tentang Akun Layanan.
• Pelajari tentang akses kontrol dua level untuk instance Cloud SQL.
• Buat pengguna dan database.
• Pelajari cara terhubung ke instance dari aplikasi Anda.
• Pelajari Klien MySQL.
• Pelajari opsi untuk dukungan.