Tentang opsi koneksi

MySQL   |  PostgreSQL   |  SQL Server

Halaman ini memberikan ringkasan tentang cara terhubung ke instance Cloud SQL dan menjelaskan opsi autentikasi dan otorisasi yang tersedia.

Ringkasan

Saat mempertimbangkan cara untuk terhubung ke instance Cloud SQL, terdapat banyak pilihan yang perlu diingat, termasuk:

• Apakah Anda ingin instance Cloud SQL dapat diakses dari internet, atau dirahasiakan dalam jaringan Virtual Private Cloud (VPC), atau membuatnya dapat diakses secara publik dan pribadi?
• Apakah Anda berencana menulis kode koneksi sendiri, atau ingin terhubung menggunakan alat yang tersedia untuk publik seperti Proxy Auth Cloud SQL atau klien psql?
• Apakah Anda ingin mewajibkan enkripsi melalui SSL/TLS atau mengizinkan traffic yang tidak terenkripsi?

Di bagian berikut, kita akan membahas opsi yang disediakan Cloud SQL untuk menghubungkan, memberi otorisasi, dan mengautentikasi ke database Anda.

• Cara menghubungkan - jalur jaringan mana yang Anda gunakan untuk menjangkau instance:
  • Alamat IP internal khusus VPC (Pribadi).
  • Alamat IP eksternal yang dapat diakses internet (Publik).
• Cara memberikan otorisasi - koneksi mana yang diotorisasi dan diizinkan untuk terhubung ke instance Cloud SQL Anda:
  • Library proxy Auth Cloud SQL dan konektor Cloud SQL untuk Java dan Python - library ini menyediakan akses berdasarkan IAM.
  • Sertifikat SSL/TLS yang dikelola sendiri - sertifikat ini hanya mengizinkan koneksi berdasarkan kunci publik tertentu.
  • Jaringan yang diizinkan - daftar alamat IP yang diizinkan untuk terhubung.
• Cara mengautentikasi - metode untuk login ke database Anda.
  • Autentikasi database bawaan - login dengan nama pengguna/sandi yang disetel di mesin database.
  • Autentikasi database IAM - login dengan email atau token OAuth 2.0 sebagai sandi.

Gunakan informasi berikut untuk memutuskan opsi koneksi, otorisasi, dan autentikasi yang paling cocok bagi Anda.

Anda dapat membuat akun untuk mengevaluasi performa Cloud SQL dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk dibelanjakan di Cloud SQL guna menjalankan, menguji, dan men-deploy workload. Anda tidak akan dikenai biaya hingga Anda mengupgrade.

Daftar untuk mencoba Cloud SQL secara gratis.

Sebelum memulai

Memberi akses ke aplikasi tidak otomatis mengaktifkan akun pengguna database untuk terhubung ke instance. Sebelum dapat terhubung ke instance, Anda harus memiliki akun pengguna database yang dapat dihubungkan. Untuk instance baru, ini berarti Anda harus mengonfigurasi akun pengguna default. Untuk informasi selengkapnya, lihat Mengelola pengguna dengan autentikasi bawaan.

Cara terhubung ke Cloud SQL

Koneksi database menggunakan resource di server dan aplikasi yang terhubung. Selalu gunakan praktik pengelolaan koneksi yang baik untuk meminimalkan jejak aplikasi Anda dan mengurangi kemungkinan terlampauinya batas koneksi Cloud SQL. Untuk mengetahui informasi selengkapnya, lihat Mengelola koneksi database.

IP publik dan pribadi

Di Cloud SQL, IP publik berarti instance dapat diakses melalui internet publik. Sebaliknya, instance yang hanya menggunakan IP pribadi tidak dapat diakses melalui internet publik, tetapi dapat diakses melalui Virtual Private Cloud (VPC). Instance Cloud SQL dapat memiliki alamat IP publik dan pribadi.

IP Pribadi

IP pribadi adalah alamat IPv4 yang dapat diakses di Virtual Private Cloud (VPC).

Anda dapat menggunakan alamat ini untuk terhubung dari resource lain yang memiliki akses ke VPC. Koneksi melalui IP pribadi biasanya memberikan latensi yang lebih rendah dan vektor serangan terbatas karena tidak perlu melintasi internet. Secara opsional, Anda dapat mewajibkan agar semua koneksi menggunakan proxy Cloud SQL atau sertifikat SSL yang dikelola sendiri.

Sebaiknya konfigurasi instance dengan IP pribadi saat terhubung dari klien di resource yang memiliki akses ke VPC. Untuk mengetahui informasi lebih lanjut tentang resource yang dapat menggunakan IP pribadi, lihat Persyaratan untuk IP Pribadi.

Untuk jalur IP pribadi, layanan dan aplikasi berikut terhubung langsung ke instance Anda melalui Akses VPC Serverless:

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

Pelajari lebih lanjut cara menggunakan IP pribadi dengan Cloud SQL

Untuk mengetahui petunjuk tentang cara menambahkan IP pribadi ke instance, lihat salah satu hal berikut:

• Mengonfigurasi Konektivitas IP Pribadi.
• Menghubungkan ke instance menggunakan Private Service Connect

IP Publik

IP publik adalah alamat IPv4 yang tersedia secara eksternal di internet publik. Alamat ini dapat menerima koneksi dari perangkat di dalam dan di luar jaringan Google, termasuk dari lokasi seperti rumah atau kantor Anda.

Untuk membantu menjaga keamanan instance Anda, setiap koneksi ke instance Cloud SQL yang menggunakan IP publik harus diberi otorisasi menggunakan Proxy Auth Cloud SQL atau jaringan yang diizinkan.

Mengonfigurasi instance dengan IP publik adalah cara terbaik saat terhubung dari klien yang tidak memenuhi persyaratan VPC.

Untuk mengetahui petunjuk tentang cara menambahkan IP publik ke instance, lihat Mengonfigurasi Konektivitas IP Publik.

Untuk mengetahui informasi tentang cara menghubungkan klien psql ke instance Cloud SQL menggunakan IP publik, lihat Menghubungkan menggunakan klien database.

Alamat IP yang ditetapkan secara dinamis

Beberapa aplikasi perlu terhubung ke instance Cloud SQL Anda menggunakan alamat IP yang ditetapkan secara dinamis atau sementara. Hal ini berlaku untuk aplikasi Platform as a Service (PaaS), dan lain-lain.

Dalam hal ini, Anda harus menggunakan Proxy Auth Cloud SQL.

Cara memberikan otorisasi ke Cloud SQL

Catatan: Opsi ini hanya memungkinkan Anda mengontrol koneksi mana yang diizinkan untuk terhubung ke instance Anda. Anda tetap harus memberikan nama pengguna dan sandi database untuk melakukan autentikasi dengan mesin database.

Cloud SQL Language Connector

Konektor Bahasa Cloud SQL adalah library klien yang memberikan enkripsi dan otorisasi IAM saat terhubung ke instance Cloud SQL. Cloud SQL merekomendasikan penggunaan Cloud SQL Language Connectors untuk terhubung ke instance Cloud SQL Anda, bukan opsi koneksi lainnya.

Anda dapat menggunakan library ini secara langsung dari bahasa pemrograman yang didukung. Keduanya memberikan autentikasi yang sama dengan Proxy Auth Cloud SQL tanpa memerlukan proses eksternal. Hal ini memberikan keamanan yang lebih kuat dan persyaratan konfigurasi yang lebih rendah untuk terhubung ke Cloud SQL. Cloud SQL Language Connector juga menggunakan kode yang sama saat terhubung menggunakan alamat IP publik atau alamat IP pribadi.

Untuk memulai, lihat Cloud SQL Language Connector.

Proxy Auth Cloud SQL

Dengan Proxy Auth Cloud SQL, Anda dapat memberi otorisasi dan mengamankan koneksi menggunakan izin Identity and Access Management (IAM). Proxy Auth Cloud SQL memvalidasi koneksi menggunakan kredensial untuk pengguna atau akun layanan, dan menggabungkan koneksi dalam lapisan SSL/TLS yang diberi otorisasi untuk instance Cloud SQL. Untuk mengetahui detail selengkapnya tentang cara kerja Proxy Auth Cloud SQL, lihat Tentang Proxy Auth Cloud SQL.

Menggunakan Proxy Auth Cloud SQL adalah metode yang direkomendasikan untuk mengautentikasi koneksi ke instance Cloud SQL karena merupakan metode teraman.

Proxy Auth Cloud SQL adalah library open source yang didistribusikan sebagai biner yang dapat dieksekusi. Proxy Auth Cloud SQL bertindak sebagai server perantara yang memproses koneksi masuk, menggabungkannya ke dalam SSL/TLS, lalu meneruskannya ke instance Cloud SQL.

Beberapa lingkungan menyediakan mekanisme yang terhubung menggunakan Proxy Auth Cloud SQL. Untuk mengetahui petunjuk tentang cara menghubungkan menggunakan lingkungan tersebut, lihat salah satu hal berikut:

• Terhubung dari Cloud Run
• Terhubung dari Cloud Functions
• Terhubung dari lingkungan standar App Engine
• Menghubungkan dari lingkungan Fleksibel App Engine
• Terhubung dari Google Kubernetes Engine

Sertifikat SSL/TLS yang dikelola sendiri

Daripada menggunakan Proxy Auth Cloud SQL untuk mengenkripsi koneksi Anda, ini memungkinkan untuk menyiapkan sertifikat SSL/TLS klien/server yang khusus untuk instance Cloud SQL. Sertifikat ini digunakan untuk memvalidasi klien dan server satu sama lain dan mengenkripsi koneksi di antara keduanya.

Sangat disarankan untuk menggunakan sertifikat SSL/TLS yang dikelola sendiri untuk memberikan enkripsi saat tidak menggunakan Proxy Auth Cloud SQL. Jika hal ini tidak dilakukan, data Anda akan disebarkan secara tidak aman dan mungkin dicegat atau diperiksa oleh pihak ketiga.

Untuk mulai menggunakan sertifikat SSL/TLS yang dikelola sendiri, lihat Memberikan otorisasi dengan sertifikat SSL/TLS.

Jaringan resmi

Catatan: Sangat disarankan untuk selalu menggunakan sertifikat SSL/TLS yang dikelola sendiri saat menggunakan jaringan resmi untuk mengautentikasi koneksi. Kecuali jika dienkripsi, traffic Anda mungkin rentan terhadap intersepsi oleh pihak ketiga.

Kecuali menggunakan Proxy Auth Cloud SQL, koneksi ke alamat IP publik suatu instance hanya diizinkan jika koneksi tersebut berasal dari jaringan resmi. Jaringan yang diizinkan adalah alamat atau rentang IP yang telah ditentukan sebagai pengguna memiliki izin untuk terhubung.

Peringatan: Hati-hati saat menambahkan jaringan resmi. Karena semua perangkat di jaringan sering kali berbagi alamat IP eksternal yang sama, memberikan otorisasi satu alamat dapat mengizinkan semua perangkat di jaringan yang sama, bukan klien tunggal.

Untuk mulai menggunakan jaringan resmi lihat Memberikan otorisasi dengan Jaringan Resmi.

Cara mengautentikasi ke Cloud SQL

Autentikasi memberikan kontrol akses dengan memverifikasi identitas pengguna. Untuk pengguna akhir, autentikasi dicapai saat pengguna memasukkan kredensial (nama pengguna dan sandi). Untuk aplikasi, autentikasi dilakukan saat kredensial pengguna ditetapkan ke akun layanan.

Cloud SQL menggunakan autentikasi bawaan database yang melakukan autentikasi menggunakan nama pengguna dan sandi. Untuk mengetahui informasi selengkapnya, lihat membuat dan mengelola pengguna PostgreSQL.

Cloud SQL juga terintegrasi dengan IAM untuk membantu Anda memantau dan mengelola akses database pengguna dan akun layanan dengan lebih baik. Fitur ini disebut autentikasi database IAM.

Pelajari lebih lanjut tentang autentikasi database IAM.

Pelajari lebih lanjut tentang cara membuat dan mengelola pengguna yang menggunakan autentikasi database IAM.

Alat untuk terhubung ke Cloud SQL

Tabel berikut berisi beberapa opsi untuk terhubung ke Cloud SQL:

Opsi koneksi	Informasi selengkapnya
Proxy Auth Cloud SQL	Tentang Proxy Auth Cloud SQL Terhubung menggunakan Proxy Auth Cloud SQL Terhubung menggunakan Image Docker Proxy Auth Cloud SQL
gcloud CLI	gcloud sql connect
Cloud SQL language connector	Terhubung menggunakan Konektor Cloud SQL untuk Java, Python, dan Go.
Cloud Shell	Terhubung menggunakan Cloud Shell
Cloud Code	Terhubung menggunakan Cloud Code di JetBrains IDE
Terhubung menggunakan alat administrasi database pihak ketiga
pgAdmin	pgAdmin.org untuk PostgreSQL
Toad Edge	Toad Edge untuk PostgreSQL
Blendo	Cara menghubungkan PostgreSQL Google Cloud SQL dengan Blendo

Contoh kode

Anda dapat terhubung ke Proxy Auth Cloud SQL 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 Proxy Auth Cloud SQL:

./cloud-sql-proxy INSTANCE_CONNECTION_NAME &

Python

Untuk menemukan cuplikan ini dalam konteks aplikasi web, lihat README pada 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 di sini .

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 menemukan cuplikan ini dalam konteks aplikasi web, lihat README pada 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 menemukan cuplikan ini dalam konteks aplikasi web, lihat README pada 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 menemukan cuplikan ini dalam konteks aplikasi web, lihat README pada 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 menemukan cuplikan ini dalam konteks aplikasi web, lihat README pada 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 menemukan cuplikan ini dalam konteks aplikasi web, lihat README pada 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 Proxy Auth Cloud SQL:

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

Python

Untuk menemukan cuplikan ini dalam konteks aplikasi web, lihat README pada 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 menemukan cuplikan ini dalam konteks aplikasi web, lihat README pada 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);
    }

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

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

Node.js

Untuk menemukan cuplikan ini dalam konteks aplikasi web, lihat README pada 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 menemukan cuplikan ini dalam konteks aplikasi web, lihat README pada 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 menemukan cuplikan ini dalam konteks aplikasi web, lihat README pada 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 menemukan cuplikan ini dalam konteks aplikasi web, lihat README pada 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 menemukan cuplikan ini dalam konteks aplikasi web, lihat README pada 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;
    }
}

Memecahkan masalah

Jika Anda mengalami masalah saat menghubungkan, periksa halaman berikut untuk membantu melakukan proses debug atau menemukan solusi untuk masalah umum:

• Proses debug masalah koneksi
• Error konektivitas umum
• Memecahkan masalah koneksi Proxy Auth Cloud SQL
• Masalah koneksi umum

Langkah selanjutnya

• Pelajari cara terhubung dengan Panduan memulai Cloud SQL untuk postgres.
• Pelajari praktik terbaik untuk mengelola koneksi database.
• Pelajari tentang autentikasi database IAM.
• Pelajari cara terhubung menggunakan klien psql dari mesin lokal atau Compute Engine.
• Pelajari cara mengonfigurasi konektivitas IP.
• Pelajari tentang Proxy Auth Cloud SQL.
• Pelajari opsi untuk dukungan.