接続オプションについて

MySQL   |  PostgreSQL   |  SQL Server

このページでは、Cloud SQL インスタンスに接続する方法の概要と、利用可能な認証と認可のオプションについて説明します。

概要

Cloud SQL インスタンスに接続する方法を検討する際は、次のように、考慮すべき多くの選択肢があります。

• インターネットから Cloud SQL インスタンスにアクセスできるようにするか、Virtual Private Cloud（VPC）ネットワーク内で限定公開にするか、または、一般公開と限定公開の両方にするか。
• 独自の接続コードを記述するか、Cloud SQL Auth Proxy や psql クライアントなど、一般公開されているツールを使用して接続するか。
• SSL / TLS による暗号化を必須とするか、暗号化されていないトラフィックを許可するか。

以降のセクションでは、Cloud SQL がデータベースの接続、認可、認証のために提供しているオプションについて説明します。

• 接続方法: どのネットワーク パスを使用してインスタンスに到達するのか。
  • VPC のみの内部（プライベート）IP アドレス。
  • インターネットにアクセスできる外部（パブリック）IP アドレス。
• 認可方法: どの接続が認可され、Cloud SQL インスタンスへの接続が許可されるのか。
  • Java と Python の Cloud SQL Auth Proxy と Cloud SQL コネクタ ライブラリ: IAM に基づいてアクセスを提供する。
  • セルフマネージド SSL / TLS 証明書: 特定の公開鍵に基づく接続のみを許可する。
  • 承認済みネットワーク: 接続可能な IP アドレスのリスト。
• 認証方法: データベースにログインする方法。
  • 組み込みのデータベース認証: データベース エンジンで設定されたユーザー名とパスワードでログイン。
  • IAM データベース認証: メールまたは OAuth 2.0 トークンをパスワードとして使用してログインする。

以下の情報を参考に、最適な接続、認可、認証のオプションを決定してください。

アカウントを作成して、実際のシナリオでの Cloud SQL のパフォーマンスを評価してください。新規のお客様には、Cloud SQL でワークロードを実行、テスト、デプロイできる無料クレジット $300 分を差し上げます。アップグレードするまで料金は発生しません。

登録して Cloud SQL を無料でお試しください。

始める前に

アプリケーションへのアクセスを付与しても、データベース ユーザー アカウントがインスタンスに自動的に接続できるようになるわけではありません。インスタンスに接続するには、接続に使用できるデータベース ユーザー アカウントが必要です。つまり、新しいインスタンスの場合はデフォルトのユーザー アカウントを構成しておく必要があります。詳細については、組み込み認証を使用してユーザーを管理するをご覧ください。

Cloud SQL に接続する方法

データベース接続は、サーバーと接続元アプリケーションのリソースを消費します。アプリケーションのフットプリントを最小限に抑え、Cloud SQL の接続制限を超える可能性を少なくするには、常に適切な接続管理方法を採用してください。詳細については、データベース接続の管理をご覧ください。

パブリック IP とプライベート IP

Cloud SQL では、パブリック IP は、インスタンスに公共のインターネット経由でアクセスできることを意味します。逆に、プライベート IP のみを使用するインスタンスに、公共のインターネットからはアクセスできませんが、Virtual Private Cloud（VPC）経由ではアクセスできます。Cloud SQL インスタンスでは、パブリック IP アドレスとプライベート IP アドレスのどちらも使用できます。

プライベート IP

プライベート IP は、Virtual Private Cloud（VPC）でアクセス可能な IPv4 アドレスです。

このアドレスを使用して、VPC にアクセスできる他のリソースから接続できます。プライベート IP 経由の接続では、インターネットを経由する必要がないため、通常はレイテンシが小さく、攻撃ベクトルが制限されます。任意で、すべての接続で Cloud SQL Proxy またはセルフマネージド SSL 証明書のいずれかを使用するよう要求できます。

VPC にアクセスできるリソース上のクライアントから接続を行う場合は、プライベート IP を使用するインスタンスを構成することをおすすめします。プライベート IP を使用できるリソースの詳細については、プライベート IP の要件をご覧ください。

プライベート IP パスの場合は、次のサービスとアプリケーションがサーバーレス VPC アクセスを介してインスタンスに直接接続されます。

• App Engine スタンダード環境
• App Engine フレキシブル環境
• Cloud Run functions
• Cloud Run

詳細については Cloud SQL でプライベート IP を使用するをご覧ください。

インスタンスにプライベート IP を追加する手順については、次のいずれかをご覧ください。

• プライベート IP 接続の構成。
• Private Service Connect を使用してインスタンスに接続する

パブリック IP

パブリック IP は、公共のインターネット上で外部から利用できる IPv4 アドレスです。このアドレスは、自宅や職場など、Google のネットワーク内外のデバイスからの接続を受信できます。

インスタンスのセキュリティを保つため、パブリック IP を使用する Cloud SQL インスタンスへの接続は、Cloud SQL Auth Proxy または承認済みネットワークのいずれかを使用して認可する必要があります。

VPC の要件を満たしていないクライアントから接続する場合は、パブリック IP を使用してインスタンスを構成することをおすすめします。

インスタンスにパブリック IP を追加する手順については、パブリック IP 接続を構成するをご覧ください。

パブリック IP を使用して psql クライアントを Cloud SQL インスタンスに接続する方法については、データベース クライアントを使用して接続するをご覧ください。

動的に割り振られる IP アドレス

一部のアプリケーションでは、動的に割り振られる一時的な IP アドレスを使用して、Cloud SQL インスタンスに接続する必要があります。これは、特に Platform as a Service（PaaS）アプリケーションの場合に該当します。

この場合、Cloud SQL Auth Proxy を使用する必要があります。

インスタンスの接続オプション

このセクションでは、Cloud SQL がインスタンスへの接続についてサポートする機能について説明します。このセクションには、インスタンスの作成、無効化、有効化に使用できる接続オプションも含まれています。

サポートされている機能

次の表に、Cloud SQL がプライベート接続を使用してインスタンスに接続するためにサポートする機能を示します。

機能	プライベート サービス アクセスのみを使用するインスタンス	Private Service Connect のみを使用するインスタンス	プライベート サービス アクセスと Private Service Connect の両方を使用するインスタンス
複数の VPC から接続する	サポートされていません。	サポート対象	Private Service Connect エンドポイントを使用してサポートされます。
pglogical、PL/Proxy、dblink、postgres_fdw の拡張子	サポート対象	サポートされていません。	プライベート サービス アクセスのアウトバウンド接続を使用してサポートされます。
外部レプリカ	サポート対象	サポートされていません。	プライベート サービス アクセスのアウトバウンド接続を使用してサポートされます。
書き込みエンドポイント	サポート対象	サポートされていません。	プライベート サービス アクセスでサポートされています。
プライベート サービス アクセスに関連付けられている VPC ネットワークを変更する	サポート対象	該当なし	インスタンスで Private Service Connect が有効になっているため、プライベート サービス アクセスではサポートされていません。Private Service Connect には適用されません。
Cloud SQL に対するクライアント IP アドレスの可視性	サポート対象	サポートされていません。	プライベート サービス アクセスの IP アドレスを使用することでサポートされます。Private Service Connect エンドポイントではサポートされていません。

インスタンスの作成用の接続オプション

Cloud SQL は、プライベート IP とパブリック IP の構成をサポートしています。接続オプションは、アプリケーションの要件に基づいて選択できます。

プライベート IP を構成して、VPC ネットワーク内で Cloud SQL インスタンスを非公開できます。次のタイプのプライベート接続がサポートされています。

• プライベート サービス アクセス: 単一の VPC ネットワークから Cloud SQL インスタンスに接続する
• Private Service Connect: 異なるグループ、チーム、プロジェクト、組織に属する複数の VPC ネットワークから Cloud SQL インスタンスに接続する

インスタンスがパブリック インターネット経由で Google Cloudのネットワークの内外のクライアントからの接続にアクセスできるようにするには、インスタンスのパブリック IP を構成します。

Cloud SQL は、インスタンスの作成に次の接続オプションをサポートしています。

• プライベート サービス アクセスのみ
• Private Service Connect のみ
• パブリック IP のみ
• プライベート サービス アクセスと Private Service Connect の両方
• パブリック IP とプライベート サービス アクセスの両方
• パブリック IP、プライベート サービス アクセス、Private Service Connect

接続オプションを無効にする

Cloud SQL では、インスタンスの次の接続オプションを無効にできます。

• プライベート サービス アクセスとパブリック IP の両方を使用するインスタンスのパブリック IP
• パブリック IP、プライベート サービス アクセス、Private Service Connect を使用するインスタンスのパブリック IP
• Private Service Connect とプライベート サービス アクセスの両方を使用するインスタンスの Private Service Connect
• Private Service Connect、プライベート サービス アクセス、パブリック IP を使用するインスタンスの Private Service Connect

接続オプションを有効にする

Cloud SQL では、インスタンスで次の接続オプションを有効にできます。

• パブリック IP のみを使用するインスタンスのプライベート サービス アクセス
• プライベート サービス アクセスのみを使用するインスタンスの Private Service Connect
• プライベート サービス アクセスとパブリック IP の両方を使用するインスタンスの Private Service Connect
• プライベート サービス アクセスのみを使用するインスタンスのパブリック IP

制限事項

• パブリック IP と Private Service Connect の両方を使用してインスタンスを作成することはできません。
• プライベート サービス アクセスと Private Service Connect の両方を使用するインスタンスのプライベート サービス アクセスを無効にすることはできません。
• プライベート サービス アクセスとパブリック IP の両方を使用するインスタンスのプライベート サービス アクセスを無効にすることはできません。
• パブリック IP のみを使用するインスタンスがある場合、プライベート サービス アクセスと Private Service Connect の両方を有効にすることはできません。まず、プライベート サービス アクセスを有効にしてから、Private Service Connect を有効にします。
• Private Service Connect が有効になっているインスタンスでは、承認済みネットワークを使用した IP ベースの許可リストはサポートされていません。

Cloud SQL の承認方法

注: このオプションでは、インスタンスへの接続の許可のみを制御できます。データベース エンジンで認証を行う場合は、データベースのユーザー名とパスワードを指定する必要があります。

Cloud SQL 言語コネクタ

Cloud SQL 言語コネクタは、Cloud SQL インスタンスへの接続時に暗号化と IAM 承認を行うクライアント ライブラリです。Cloud SQL インスタンスに接続するには、他の接続オプションではなく、Cloud SQL 言語コネクタを使用することをおすすめします。

これらのライブラリは、サポート対象のプログラミング言語から直接使用できます。外部プロセスを必要とせずに Cloud SQL Auth Proxy と同じ認証が行われます。これにより、セキュリティが向上し、Cloud SQL に接続するための構成要件が削減されます。Cloud SQL 言語コネクタは、パブリック IP アドレスまたはプライベート IP アドレスを使用して接続する場合も同じコードを使用します。

開始するには、Cloud SQL 言語コネクタについてをご覧ください。

Cloud SQL Auth Proxy

Cloud SQL Auth Proxy では、Identity and Access Management（IAM）権限を使用して接続を承認し、保護できます。Cloud SQL Auth Proxy は、ユーザーまたはサービス アカウントの認証情報を使用して接続を検証し、Cloud SQL インスタンスに対して承認された SSL / TLS レイヤに接続をラップします。Cloud SQL Auth Proxy の動作の詳細については、Cloud SQL Auth Proxy についてをご覧ください。

Cloud SQL インスタンスへの接続の認証には、Cloud SQL Auth Proxy を使用することをおすすめします。これは最も安全な方法です。

Cloud SQL Auth Proxy は、実行可能なバイナリとして配布されるオープンソース ライブラリです。Cloud SQL Auth Proxy は、受信接続をリッスンして SSL / TLS でラップし、Cloud SQL インスタンスに渡す中間サーバーとして機能します。

環境によっては、Cloud SQL Auth Proxy を使用して接続するメカニズムが提供されています。これらの環境を使用した接続の手順については、次のいずれかをご覧ください。

• Cloud Run から接続する
• Cloud Run 関数から接続する
• App Engine スタンダード環境から接続する
• App Engine フレキシブル環境から接続する
• Google Kubernetes Engine から接続する

セルフマネージド SSL / TLS 証明書

Cloud SQL Auth Proxy を使用して接続を暗号化する代わりに、Cloud SQL インスタンスに固有のクライアントとサーバーの SSL / TLS 証明書を設定できます。この証明書は、クライアントとサーバーの両方を相互に検証し、その間の接続を暗号化するために使用されます。

Cloud SQL Auth Proxy を使用しない場合は、セルフマネージド SSL / TLS 証明書を使用して暗号化することを強くおすすめします。暗号化しないと、データが安全に送信されず、第三者によって傍受または監視されるおそれがあります。

セルフマネージド SSL / TLS 証明書のご利用にあたっては、SSL / TLS 証明書による承認をご覧ください。

承認済みネットワーク

注: 承認済みネットワークで接続の認証を行う場合は、セルフマネージド SSL / TLS 証明書を常に使用することを強くおすすめします。暗号化しないと、トラフィックが第三者によって傍受されるおそれがあります。

Cloud SQL Auth Proxy を使用する場合を除き、インスタンスのパブリック IP アドレスへの接続は、接続が承認済みネットワークから送信された場合のみ許可されます。承認済みネットワークとは、ユーザーが接続権限を持たせるよう指定した IP アドレスまたは範囲のことです。

警告: 承認済みネットワークを追加する際は注意が必要です。ネットワークのすべてのデバイスが同じ外部 IP アドレスを共有することが多いため、1 つのアドレスを承認すると、1 つのクライアントだけでなく、同じネットワーク上のすべてのデバイスが承認される可能性があります。

承認済みネットワークのご利用にあたっては、承認済みネットワークでの認証をご覧ください。

Cloud SQL への認証方法

認証とは、ユーザーの ID を確認することによるアクセス制御です。エンドユーザーについては、ユーザーが認証情報（ユーザー名とパスワード）を入力すると認証が行われます。アプリケーションでは、ユーザーの認証情報がサービス アカウントに割り当てられている場合に認証が行われます。

Cloud SQL では、ユーザー名とパスワードで認証を行うデータベースの組み込み認証を使用します。詳細については、PostgreSQL ユーザーの作成と管理をご覧ください。

また、Cloud SQL は IAM と統合されており、ユーザーとサービス アカウントのデータベース アクセスのモニタリングおよび管理を適切に行うことができます。この機能を IAM データベース認証と呼びます。

IAM データベース認証について学習する。

IAM データベース認証を使用するユーザーの作成と管理について学習する。

Cloud SQL に接続するためのツール

次の表に、Cloud SQL に接続するためのオプションを示します。

接続オプション	詳細
Cloud SQL Auth Proxy	Cloud SQL Auth Proxy について Cloud SQL Auth Proxy を使用して接続する Cloud SQL Auth Proxy Docker イメージを使用して接続する
gcloud CLI	gcloud sql connect
Cloud SQL 言語コネクタ	Java、Python、Go 用の Cloud SQL コネクタを使用して接続する
Cloud Shell	Cloud Shell を使用して接続する
Cloud Code	JetBrains IDE で Cloud Code を使用して接続する
サードパーティのデータベース管理ツールを使用して接続する
pgAdmin	PostgreSQL 向けの pgAdmin.org
Toad Edge	PostgreSQL 向けの Toad Edge
Blendo	Google Cloud SQL PostgreSQL と Blendo を接続する方法

コードサンプル

Unix または TCP ソケットに接続できる任意の言語を使用して、Cloud SQL Auth Proxy に接続できます。アプリケーションでどのように連携するのかを把握できるように、GitHub の詳細な例からコード スニペットをいくつか紹介します。

TCP で接続

Cloud SQL Auth Proxy 呼び出しステートメント:

./cloud-sql-proxy INSTANCE_CONNECTION_NAME &

Python

このスニペットをウェブ アプリケーションのコンテキストで表示するには、GitHub の README をご覧ください。

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

このスニペットをウェブ アプリケーションのコンテキストで表示するには、GitHub の README をご覧ください。

注:

• CLOUD_SQL_CONNECTION_NAME は <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME> のように指定する必要があります。
• 引数 ipTypes=PRIVATE を使用すると、SocketFactory はインスタンスに関連付けられたプライベート IP を使用して接続するようになります。
• pom.xml ファイルの JDBC ソケット Factory バージョン要件をご覧ください。

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

このスニペットをウェブ アプリケーションのコンテキストで表示するには、GitHub の README をご覧ください。

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

このスニペットをウェブ アプリケーションのコンテキストで表示するには、GitHub の README をご覧ください。

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#

このスニペットをウェブ アプリケーションのコンテキストで表示するには、GitHub の README をご覧ください。

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

このスニペットをウェブ アプリケーションのコンテキストで表示するには、GitHub の README をご覧ください。

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

このスニペットをウェブ アプリケーションのコンテキストで表示するには、GitHub の README をご覧ください。

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;
    }
}

Unix ソケットとの接続

Cloud SQL Auth Proxy 呼び出しステートメント:

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

Python

このスニペットをウェブ アプリケーションのコンテキストで表示するには、GitHub の README をご覧ください。

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

このスニペットをウェブ アプリケーションのコンテキストで表示するには、GitHub の README をご覧ください。

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

public class ConnectorConnectionPoolFactory extends ConnectionPoolFactory {

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

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

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

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

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

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


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

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

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

Node.js

このスニペットをウェブ アプリケーションのコンテキストで表示するには、GitHub の README をご覧ください。

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#

このスニペットをウェブ アプリケーションのコンテキストで表示するには、GitHub の README をご覧ください。

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

このスニペットをウェブ アプリケーションのコンテキストで表示するには、GitHub の README をご覧ください。

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

このスニペットをウェブ アプリケーションのコンテキストで表示するには、GitHub の README をご覧ください。

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

このスニペットをウェブ アプリケーションのコンテキストで表示するには、GitHub の README をご覧ください。

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;
    }
}

トラブルシューティング

接続に問題がある場合は、以下のページで既知の問題のデバッグ方法やソリューションを確認してください。

• 接続の問題のデバッグ
• 既知の接続エラー
• Cloud SQL Auth Proxy 接続のトラブルシューティング
• 接続に関する一般的な問題

次のステップ

• Cloud SQL for Postgres のクイックスタートを使用して接続方法を学習する。
• データベース接続の管理についてのベスト プラクティス
• IAM データベース認証について学習する。
• ローカルマシンまたは Compute Engine からの psql クライアントを使用した接続について学習する。
• IP 接続を構成する方法を学習する。
• Cloud SQL Auth Proxy について学習する。
• サポート用オプションについて学習する。