Cloud SQL Auth Proxy を使用して接続する

MySQL | PostgreSQL | SQL Server

このページでは、Cloud SQL Auth Proxy を使用して Cloud SQL インスタンスに接続する方法について説明します。

Cloud SQL Auth Proxy の動作の詳細については、Cloud SQL Auth Proxy についてをご覧ください。

概要

Cloud SQL インスタンスに接続する場合は、Cloud SQL Auth Proxy を使用することをおすすめします。Cloud SQL Auth Proxy:

パブリック IP エンドポイントとプライベート IP エンドポイントの両方で動作する。
ユーザーまたはサービスアカウントの認証情報を使用して接続を検証する。
Cloud SQL インスタンスに対して認可された SSL / TLS レイヤに接続をラップする。

一部の Google Cloud サービスとアプリケーションでは、Cloud SQL Auth プロキシを使用して暗号化と認可を行い、パブリック IP パスの接続を可能にしています。

Google Kubernetes Engine で実行されるアプリケーションは、Cloud SQL Auth Proxy を使用して接続できます。

基本的な使用方法については、Cloud SQL Auth Proxy を使用するためのクイックスタートをご覧ください。

ローカルマシンまたは Compute Engine から psql クライアントを使用して、Cloud SQL Auth Proxy の有無を問わず接続することもできます。

始める前に

Cloud SQL インスタンスに接続するには、次の作業が必要です。

- ユーザーまたはサービスアカウントについて、そのアカウントに Cloud SQL クライアントのロールがあることを確認します。このロールには、プリンシパルがプロジェクト内のすべての Cloud SQL インスタンスに接続することを承認する cloudsql.instances.connect 権限が含まれています。
  IAM ページに移動
- 必要に応じて、1 つの特定の Cloud SQL インスタンスにのみ接続する権限をアカウントに付与する IAM 条件を IAM ポリシーバインディングに含めることができます。
Enable the Cloud SQL Admin API.
Enable the API

gcloud CLI をインストールして初期化します。
省略可。Cloud SQL Auth プロキシの Docker クライアントをインストールします。

Cloud SQL Auth Proxy をダウンロードする

Linux 64 ビット

Cloud SQL Auth Proxy をダウンロードします。

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

Cloud SQL Auth Proxy を実行可能にします。
```
chmod +x cloud-sql-proxy
```

Linux 32 ビット

Cloud SQL Auth Proxy をダウンロードします。

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

curl コマンドが見つからない場合は、sudo apt install curl を実行してダウンロードコマンドを繰り返します。
Cloud SQL Auth Proxy を実行可能にします。
```
chmod +x cloud-sql-proxy
```

macOS 64 ビット

Cloud SQL Auth Proxy をダウンロードします。

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

Cloud SQL Auth Proxy を実行可能にします。
```
chmod +x cloud-sql-proxy
```

Mac M1

Cloud SQL Auth Proxy をダウンロードします。

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

Cloud SQL Auth Proxy を実行可能にします。
```
  chmod +x cloud-sql-proxy
  
```

Windows 64 ビット

https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.x64.exe を右クリックして [名前を付けてリンクを保存] を選択し、Cloud SQL Auth Proxy をダウンロードします。ファイル名を cloud-sql-proxy.exe に変更します。

Windows 32 ビット

https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.x86.exe を右クリックして [名前を付けてリンクを保存] を選択し、Cloud SQL Auth Proxy をダウンロードします。ファイル名を cloud-sql-proxy.exe に変更します。

Cloud SQL Auth Proxy Docker イメージ

Cloud SQL Auth Proxy には、distroless、alpine、buster など、さまざまなコンテナイメージがあります。デフォルトの Cloud SQL Auth Proxy コンテナイメージでは、シェルを含まない distroless を使用します。シェルまたは関連ツールが必要な場合は、alpine または buster を基盤とするイメージをダウンロードします。詳細については、Cloud SQL Auth Proxy コンテナイメージをご覧ください。

次のコマンドを使用して、ローカルマシンに最新のイメージを Docker で pull できます。

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

注: Cloud SQL Auth Proxy は、gcr.io ドメインをサポートする一方で Artifact Registry からイメージを提供するリポジトリを使用します。詳細については、Container Registry からの移行をご覧ください。

その他の OS

ここに記載されていないその他のオペレーティングシステムの場合は、ソースから Cloud SQL Auth Proxy をコンパイルできます。

Cloud SQL Auth Proxy を起動する

言語や環境に応じて、TCP ソケット、Unix ソケット、または Cloud SQL Auth Proxy Docker イメージを使用して Cloud SQL Auth Proxy を起動できます。Cloud SQL Auth Proxy バイナリは、コマンドラインで指定された 1 つ以上の Cloud SQL インスタンスに接続し、TCP または Unix ソケットとしてローカル接続をオープンします。アプリケーションコードやデータベース管理クライアントツールなど、他のアプリケーションやサービスは、これらの TCP または Unix ソケットの接続を介して Cloud SQL インスタンスに接続できます。

TCP ソケット

TCP 接続の場合、Cloud SQL Auth Proxy は、デフォルトでは localhost（127.0.0.1）でリッスンします。したがって、インスタンスに --port PORT_NUMBER を指定すると、ローカル接続は 127.0.0.1:PORT_NUMBER になります。

また、ローカル接続に別のアドレスを指定することもできます。たとえば、ローカル接続用に Cloud SQL Auth Proxy が 0.0.0.0:1234 でリッスンする方法を次に示します。

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

INSTANCE_CONNECTION_NAME をコピーします。これは、Google Cloud コンソールのインスタンスの [概要] ページに表示されます。また、次のコマンドで確認することもできます。
```
    gcloud sql instances describe INSTANCE_NAME --format='value(connectionName)'
```
例: myproject:myregion:myinstance。
インスタンスにパブリック IP とプライベート IP の両方が構成されている場合に、Cloud SQL Auth Proxy によってプライベート IP アドレスが使用されるようにするには、Cloud SQL Auth Proxy の起動時に次のオプションを指定する必要があります。
```
--private-ip
```
サービスアカウントを使用して Cloud SQL Auth Proxy を認証する場合は、サービスアカウントの作成時に作成された秘密鍵ファイルの、クライアントマシン上の場所を記録しておきます。
Cloud SQL Auth Proxy を起動します。
有効な Cloud SQL Auth Proxy の呼び出し文字列:
- Cloud SDK 認証を使用する場合:
```
./cloud-sql-proxy --port 5432 INSTANCE_CONNECTION_NAME
```
  指定されたポートは、ローカルデータベースサーバーなどがまだ使用していないものにする必要があります。
- サービスアカウントを使用して、インスタンス接続の名前を明示的に指定する場合（本番環境用に推奨）:
```
./cloud-sql-proxy \
--credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &
```
Cloud SQL Auth Proxy オプションの詳細については、Cloud SQL Auth Proxy の認証オプションをご覧ください。

Unix ソケット

Cloud SQL Auth Proxy は Unix ソケットでリッスンできます。これは、フォルダを使用して同じホスト上で動作している 2 つのプロセス間の通信を管理するための Posix 標準のメカニズムです。Unix ソケットを使用する利点は、セキュリティが向上し、レイテンシが低くなることです。ただし、外部マシンから Unix ソケットにはアクセスできません。

注: PostgreSQL 標準では、ソケットパスに接尾辞 .s.PGSQL.5432 が必要です。一部のライブラリではこの接尾辞が自動的に適用されますが、他のライブラリでは、ソケットパスを次のように指定する必要があります。

  /cloudsql/INSTANCE_CONNECTION_NAME/.s.PGSQL.5432

Unix ソケットを作成して使用するには、ターゲットディレクトリが存在し、Cloud SQL Auth Proxy とアプリケーションの両方に読み取りと書き込みのアクセス権が付与されている必要があります。

INSTANCE_CONNECTION_NAME をコピーします。これは、Google Cloud コンソールのインスタンスの [概要] ページに表示されます。また、次のコマンドで確認することもできます。
```
    gcloud sql instances describe INSTANCE_NAME --format='value(connectionName)'
```
例: myproject:myregion:myinstance。
Cloud SQL Auth Proxy ソケットを格納するディレクトリを作成します。
```
sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
```
サービスアカウントを使用して Cloud SQL Auth Proxy を認証する場合は、サービスアカウントの作成時に作成された秘密鍵ファイルの、クライアントマシン上の場所を記録しておきます。
新しい Cloud Shell ターミナルウィンドウを開き、Cloud SQL Auth Proxy を起動します。
有効な Cloud SQL Auth Proxy の呼び出し文字列:
- Google Cloud SDK 認証を使用する:
```
./cloud-sql-proxy --unix-socket /cloudsql INSTANCE_CONNECTION_NAME &
```
- サービスアカウントを使用する:
```
  ./cloud-sql-proxy --unix-socket /cloudsql
  --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &
```
専用の Cloud Shell ターミナルで Cloud SQL Auth Proxy を起動して、その出力を他のプログラムからの出力と混同せずにモニタリングできるようにします。

Cloud SQL Auth Proxy オプションの詳細については、Cloud SQL Auth Proxy の認証オプションをご覧ください。
注: Unix ソケットを使用して Cloud SQL Auth Proxy を使用する Cloud SQL に接続する場合、ソケットのファイル名の長さがシステムの上限を超えていないことを確認してください。システムによって異なりますが、通常は 91～108 文字です。Linux では、この長さが通常 108 文字と定義され、次のコマンドで確認できます。
```
cat /usr/include/linux/un.h | grep "define UNIX_PATH_MAX"
```

Docker

Docker コンテナで Cloud SQL Auth Proxy を動作させるには、Google Container Registry から入手できる Cloud SQL Auth Proxy Docker イメージを使用します。

次のコマンドで、TCP ソケットまたは Unix ソケットのどちらかを使用して、Cloud SQL Auth Proxy を起動できます。このオプションは、Cloud SQL インスタンスを識別するための接続文字列として INSTANCE_CONNECTION_NAME を使用します。INSTANCE_CONNECTION_NAME は、Google Cloud コンソールのインスタンスの [概要] ページに表示されます。また、次のコマンドで確認することもできます。

gcloud sql instances describe INSTANCE_NAME

。

例: myproject:myregion:myinstance。

言語や環境に応じて、TCP ソケットまたは Unix ソケットのどちらかを使用して Cloud SQL Auth Proxy を起動できます。Unix ソケットは、Java プログラミング言語で作成されたアプリケーションや Windows 環境ではサポートされていません。

TCP ソケットの使用

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

Compute Engine インスタンスによって提供される認証情報を使用している場合は、--credentials-file パラメータと -v PATH_TO_KEY_FILE:/path/to/service-account-key.json の行を含めないでください。

Cloud SQL Auth Proxy がローカルホストの外部に公開されないように、常に 127.0.0.1 に -p の接頭辞を指定します。インスタンスパラメータに含まれる「0.0.0.0」は、Docker コンテナの外側からポートにアクセスできるようにするために必要です。

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

コンテナ最適化イメージを使用している場合は、/cloudsql の代わりに書き込み可能なディレクトリを使用します。たとえば、次のようにします。

-v /mnt/stateful_partition/cloudsql:/cloudsql

複数のインスタンスをカンマで区切って指定できます。また、Compute Engine メタデータを使用して接続対象のインスタンスを動的に決定することもできます。Cloud SQL Auth Proxy パラメータについての詳細をご覧ください。

psql クライアントと接続する

Debian / Ubuntu

PSQL クライアントをパッケージ管理システムから次のようにインストールします。

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

CentOS / RHEL

PSQL クライアントをパッケージ管理システムから次のようにインストールします。

sudo yum install postgresql

openSUSE

PSQL クライアントをパッケージ管理システムから次のようにインストールします。

sudo zypper install postgresql

他のプラットフォーム

ご使用のプラットフォームに対応する PostgreSQL Core Distribution を、PostgreSQL のダウンロードページからダウンロードします。
Core Distribution には、PSQL クライアントが含まれています。
ダウンロードページの指示に沿って、PostgreSQL データベースをインストールします。

使用する接続文字列は、TCP ソケット、Unix ソケット、Docker のいずれを使用して Cloud SQL Auth Proxy を開始したかによって異なります。

TCP ソケット

psql クライアントを起動します。
```
psql "host=127.0.0.1 sslmode=disable dbname=DB_NAME user=USERNAME"
```
sslmode パラメータが disable に設定されていても、Cloud SQL Auth Proxy では暗号化された接続が提供されます。

TCP ソケットを使用して接続する場合、Cloud SQL Auth Proxy には 127.0.0.1 経由でアクセスします。
プロンプトが表示されたら、パスワードを入力します。
psql のプロンプトが表示されます。

Unix ソケットの使用

psql クライアントを起動します。
```
psql "sslmode=disable host=/cloudsql/INSTANCE_CONNECTION_NAME dbname=DB_NAME user=USERNAME"
```
sslmode パラメータが disable に設定されていても、Cloud SQL Auth Proxy では暗号化された接続が提供されます。
パスワードを入力します。
psql のプロンプトが表示されます。

お困りの場合、プロキシのトラブルシューティングについては、Cloud SQL Auth Proxy 接続のトラブルシューティングまたは Cloud SQL のサポートページをご覧ください。

アプリケーションに接続する

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 ソケットファクトリバージョン要件については、こちらをご覧ください。


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



    // ... 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 Auth Proxy にはコマンドライン引数で設定できる構成オプションが他にもあります。コマンドライン引数のヘルプについては、--help フラグを使用して最新のドキュメントをご覧ください。

./cloud-sql-proxy --help

Cloud SQL Auth Proxy コマンドラインオプションの使用方法のその他の例については、Cloud SQL Auth Proxy GitHub リポジトリの README をご覧ください。

Cloud SQL Auth Proxy の認証オプション

これらのオプションではすべて、Cloud SQL インスタンスを識別するための接続文字列として INSTANCE_CONNECTION_NAME を使用します。INSTANCE_CONNECTION_NAME は、Google Cloud コンソールのインスタンスの [概要] ページに表示されます。また、次のコマンドで確認することもできます。

gcloud sql instances describe --project PROJECT_ID INSTANCE_CONNECTION_NAME。

例: gcloud sql instances describe --project myproject myinstance

これらのオプションの中には、アカウントの RSA 秘密鍵を含む JSON 認証情報ファイルを使用するものもあります。サービスアカウントの JSON 認証情報ファイルを作成する手順については、サービスアカウントの作成をご覧ください。

Cloud SQL Auth Proxy では、環境に応じて、認証のための代替手段が複数用意されています。Cloud SQL Auth Proxy は、次の順序で各項目をチェックし、最初に見つかったものを使用して認証を試みます。

credential_file フラグによって指定された認証情報。
サービスアカウントを使用して、関連付けられた JSON ファイルを作成してダウンロードし、Cloud SQL Auth Proxy を起動するとき、そのファイルのパスに --credentials-file フラグを設定します。サービスアカウントには、Cloud SQL インスタンスに対する必要な権限が付与されていることが必要です。
コマンドラインでこのオプションを使用するには、--credentials-file フラグを JSON 認証情報ファイルのパスとファイル名に設定して、cloud-sql-proxy コマンドを呼び出します。パスは現在の作業ディレクトリへの絶対パス、または相対パスとして設定できます。例:
```
./cloud-sql-proxy --credentials-file PATH_TO_KEY_FILE \
INSTANCE_CONNECTION_NAME
  
```
サービスアカウントに IAM ロールを追加する方法の詳細については、サービスアカウントへのロールの付与をご覧ください。
Cloud SQL がサポートするロールの詳細については、Cloud SQL に適用される IAM のロールをご覧ください。
アクセストークンによって指定された認証情報。
アクセストークンを作成し、OAuth 2.0 アクセストークンに --token フラグを設定して cloud-sql-proxy コマンドを呼び出します。例:
```
./cloud-sql-proxy --token ACCESS_TOKEN \
INSTANCE_CONNECTION_NAME
  
```
環境変数によって指定された認証情報。
このオプションは、--credentials-file コマンドライン引数を使用する代わりに、GOOGLE_APPLICATION_CREDENTIALS 環境変数で設定する JSON 認証情報ファイルを指定する点を除けば、--credentials-file フラグを使用する場合と類似しています。
認証済みの gcloud CLI クライアントからの認証情報。

gcloud CLI をインストールし、個人アカウントで認証した場合は、Cloud SQL Auth Proxy で同じアカウント認証情報を使用できます。この方法は、開発環境の運用を開始する際に特に便利です。

Cloud SQL Auth Proxy で gcloud CLI 認証情報を使用できるようにするには、次のコマンドを使用して gcloud CLI を認証します。
```
gcloud auth application-default login
```
Compute Engine インスタンスに関連付けられている認証情報。
Cloud SQL に Compute Engine インスタンスから接続している場合、Cloud SQL Auth Proxy は Compute Engine インスタンスに関連付けられているサービスアカウントを使用できます。サービスアカウントに Cloud SQL インスタンスに対する必要な権限が付与されている場合、Cloud SQL Auth Proxy は正常に認証を行います。
Compute Engine インスタンスが Cloud SQL インスタンスと同じプロジェクトに属している場合、Compute Engine インスタンスのデフォルトのサービスアカウントには、Cloud SQL Auth Proxy の認証に必要な権限が付与されています。この 2 つのインスタンスが別々のプロジェクトに属している場合は、Cloud SQL インスタンスが属するプロジェクトに Compute Engine インスタンスのサービスアカウントを追加する必要があります。
環境のデフォルトのサービスアカウント
前述のいずれの場所でも認証情報を見つけることができない場合、Cloud SQL Auth Proxy はサーバー間での本番環境アプリケーションの認証の設定に記載されたロジックに従います。一部の環境（Compute Engine、App Engine など）では、アプリケーションがデフォルトで認証に使用できるデフォルトのサービスアカウントが用意されています。デフォルトのサービスアカウントを使用する場合は、アカウントにロールと権限で概説している権限が付与されている必要があります。Google Cloud の認証のアプローチについて詳しくは、認証の概要をご覧ください。

サービスアカウントを作成する

Compute Engine から接続する場合は、VM に Cloud SQL Admin API を使用して接続するための適切な scope があることを確認してください。

次のいずれかのアクセススコープを持つようにサービスアカウントを構成します。

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

Google Cloud コンソールで、[サービスアカウント] ページに移動します。
[サービスアカウント] に移動
Cloud SQL インスタンスを含むプロジェクトを選択します。
[サービスアカウントを作成] をクリックします。
[サービスアカウント名] フィールドに、サービスアカウントのわかりやすい名前を入力します。
[サービスアカウント ID] を一意のわかりやすい値に変更し、[作成して続行] をクリックします。
[ロールを選択] フィールドをクリックして、以下のいずれかのロールを選択します。
- [Cloud SQL] > [Cloud SQL クライアント]
- [Cloud SQL] > [Cloud SQL 編集者]
- [Cloud SQL] > [Cloud SQL 管理者]
[完了] をクリックして、サービスアカウントの作成を完了します。
新しいサービスアカウントの操作メニューをクリックし、[鍵を管理] を選択します。
[鍵を追加] プルダウンメニューをクリックして、[新しい鍵を作成] をクリックします。
鍵のタイプが JSON であることを確認し、[作成] をクリックします。
秘密鍵ファイルがマシンにダウンロードされます。秘密鍵ファイルは、別の場所に移動できます。安全な場所に鍵ファイルを保管してください。

プライベート IP で Cloud SQL Auth Proxy を使用する

プライベート IP を使用して Cloud SQL インスタンスに接続するには、Cloud SQL Auth Proxy が、そのインスタンスと同じ VPC ネットワークにアクセスできるリソース上に存在する必要があります。

Cloud SQL Auth Proxy は、IP を使用して Cloud SQL インスタンスとの接続を確立します。デフォルトでは、Cloud SQL Auth Proxy は、パブリック IPv4 アドレスを使用して接続を試行します。

Cloud SQL インスタンスにプライベート IP しかない場合、またはインスタンスにパブリック IP とプライベート IP の両方が構成されている場合に、Cloud SQL Auth Proxy でプライベート IP アドレスを使用するには、Cloud SQL Auth Proxy の起動時に次のオプションを指定する必要があります。

--private-ip

Private Service Connect が有効化されたインスタンスで Cloud SQL Auth Proxy を使用する

Private Service Connect が有効化されている Cloud SQL インスタンスに、Cloud SQL Auth Proxy を使用して接続できます。

Cloud SQL Auth Proxy は、承認済みネットワークや SSL の構成を必要とせず、このインスタンスに安全にアクセスできるコネクタです。

Cloud SQL Auth Proxy クライアントの接続を許可するには、インスタンスに指定された推奨 DNS 名に一致する DNS レコードを設定する必要があります。DNS レコードは、DNS リソースとドメイン名のマッピングです。

Cloud SQL Auth Proxy を使用して Private Service Connect が有効化されているインスタンスに接続する方法については、Cloud SQL Auth Proxy を使用して接続するをご覧ください。

別のプロセスで Cloud SQL Auth Proxy を実行する

Cloud SQL Auth Proxy を別の Cloud Shell ターミナルプロセスで実行することは、コンソール出力と他のプログラムからの出力が混在するのを回避するうえで有用な可能性があります。以下の構文を使用して、別のプロセスで Cloud SQL Auth Proxy を呼び出します。

Linux

Linux または macOS の場合、コマンドラインで末尾の & を使用して Cloud SQL Auth Proxy を別のプロセスで起動します。

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

Windows

Windows PowerShell で、Start-Process コマンドを使用して、別のプロセスで Cloud SQL Auth Proxy を起動します。

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

Docker コンテナで Cloud SQL Auth Proxy を実行する

Docker コンテナで Cloud SQL Auth Proxy を動作させるには、Google Container Registry から入手できる Cloud SQL Auth Proxy Docker イメージを使用します。Cloud SQL Auth Proxy Docker イメージは、次の gcloud コマンドを使用してインストールできます。

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

次のコマンドで、TCP ソケットまたは Unix ソケットのどちらかを使用して、Cloud SQL Auth Proxy を起動できます。

TCP ソケット

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

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

コンテナ最適化イメージを使用している場合は、/cloudsql の代わりに書き込み可能なディレクトリを使用します。たとえば、次のようにします。

v /mnt/stateful_partition/cloudsql:/cloudsql

Compute Engine インスタンスによって提供される認証情報を使用している場合は、credential_file パラメータと -v PATH_TO_KEY_FILE:/path/to/service-account-key.json の行を含めないでください。

サービスとしての Cloud SQL Auth Proxy の実行

ローカルでの開発と本番環境ワークロードでは、Cloud SQL Auth Proxy をバックグラウンドサービスとして動作させることができます。開発段階で Cloud SQL インスタンスにアクセスする必要がある場合は、バックグラウンドでサービスを開始し、終了したらサービスを停止できます。

本番環境ワークロードの場合、Cloud SQL Auth Proxy には現在、Windows サービスとして動作する組み込みのサポートはありませんが、サードパーティのサービスマネージャーを使用することで、サービスとしての動作が可能です。たとえば、NSSM を使用して Cloud SQL Auth Proxy を Windows のサービスとして構成できます。NSSM が Cloud SQL Auth Proxy をモニタリングし、応答しなくなった場合は自動的に再起動します。詳細については、NSSM のドキュメントをご覧ください。

Cloud SQL Auth Proxy の使用を適用する

ConnectorEnforcement を使用して Cloud SQL 内での Cloud SQL Auth Proxy の使用を有効にします。

gcloud

次のコマンドは、Cloud SQL コネクタの使用を強制します。

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

強制を無効にするには、コードの次の行を使用します。 --connector-enforcement NOT_REQUIRED 更新によって再起動はトリガーされません。

REST v1

次のコマンドは、Cloud SQL コネクタの使用を強制します。

リクエストのデータを使用する前に、次のように置き換えます。

project-id: プロジェクト ID。
instance-id: インスタンス ID。

HTTP メソッドと URL:

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

リクエストの本文（JSON）:

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

リクエストを送信するには、次のいずれかのオプションを開きます。

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

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）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$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

次のような JSON レスポンスが返されます。

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "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"
}

強制を無効にするには、代わりに "connectorEnforcement": "NOT_REQUIRED" を使用します。更新しても再起動は行われません。

REST v1beta4

次のコマンドは、Cloud SQL コネクタの使用を強制します。

リクエストのデータを使用する前に、次のように置き換えます。

project-id: プロジェクト ID。
instance-id: インスタンス ID。

HTTP メソッドと URL:

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

リクエストの本文（JSON）:

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

リクエストを送信するには、次のいずれかのオプションを開きます。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

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）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$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

次のような JSON レスポンスが返されます。

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "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"
}

強制を無効にするには、代わりに "connectorEnforcement": "NOT_REQUIRED" を使用します。更新しても再起動は行われません。

Cloud SQL Auth Proxy の使用に関するヒント

Cloud SQL Auth Proxy を呼び出す

プロキシ呼び出し例はすべてバックグラウンドで Cloud SQL Auth Proxy を起動し、プロンプトが返されます。Cloud SQL Auth Proxy 用に Cloud Shell ターミナルを確保して、その出力が他のプログラムからの出力と混在しないようにします。また、Cloud SQL Auth Proxy からの出力は接続の問題を診断する際に役立つため、ログファイルに記録しておくことをおすすめします。Cloud SQL Auth Proxy をバックグラウンドで起動しない場合、リダイレクトしなければ stdout に出力されます。

Cloud SQL Auth Proxy ソケットのディレクトリとして /cloudsql を使用する必要はありません（このディレクトリ名は、App Engine の接続文字列との相違を最小限に抑えるために選択されたものです）。ただし、ディレクトリ名を変更する場合は、全体の長さを最小限に保ってください。ディレクトリ名は、さらに長い文字列に組み込まれ、オペレーティングシステムの長さ上限が適用されます。システムによって異なりますが、通常は 91～108 文字です。Linux では、この長さが通常 108 文字と定義され、次のコマンドで確認できます。

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

Cloud SQL Auth Proxy を使用して複数のインスタンスに接続する

1 つのローカル Cloud SQL Auth Proxy クライアントを使用して、複数の Cloud SQL インスタンスに接続できます。これを行う方法は、Unix ソケットまたは TCP のどちらを使用しているかによって異なります。

Unix ソケット

Cloud SQL Auth Proxy を複数のインスタンスに接続するには、各インスタンス接続名をスペース区切りのリストで、Cloud SQL Auth Proxy の引数として指定します。Cloud SQL Auth Proxy は、起動時に各インスタンスに接続します。

指定されたディレクトリ内のソケットを使用して各インスタンスに接続します。

例:

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

TCP ソケット

TCP を使用して接続する場合は、Cloud SQL Auth プロキシが Cloud SQL インスタンスごとにリッスンするマシン上のポートを指定します。複数の Cloud SQL インスタンスに接続する場合は、指定された各ポートが一意であり、マシンで使用できる必要があります。

例:

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

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

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

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

Cloud SQL Auth Proxy 接続のトラブルシューティング

Cloud SQL Auth Proxy Docker イメージは、Cloud SQL Auth Proxy の特定のバージョンに基づいています。Cloud SQL Auth Proxy の新しいバージョンが利用可能になったら、Cloud SQL Auth Proxy Docker イメージの新しいバージョンを pull して、環境を最新の状態に保ってください。Cloud SQL Auth Proxy の最新バージョンは Cloud SQL Auth Proxy GitHub リリースページで確認できます。

Cloud SQL Auth Proxy を使用した Cloud SQL インスタンスへの接続の問題が発生した場合は、原因を特定するため、以下の点を確認してください。

Cloud SQL Auth Proxy の出力を確認します。

Cloud SQL Auth Proxy の出力は、多くの場合、問題の原因と解決方法を判断するのに役立ちます。出力をファイルに保存するか、Cloud SQL Auth Proxy を起動した Cloud Shell ターミナルを確認してください。
403 notAuthorized エラーが発生し、サービスアカウントを使用して Cloud SQL Auth Proxy を認証する場合は、サービスアカウントに正しい権限が付与されていることを確認します。

サービスアカウントを確認するには、IAM ページでその ID を検索します。cloudsql.instances.connect 権限が必要です。この権限は、事前定義ロールの Cloud SQL Admin、Client、Editor に含まれています。
App Engine から接続する際に 403 notAuthorized エラーが発生した場合は、app.yaml の値 cloud_sql_instances にスペルミスや不正なインスタンス接続名がないか確認してください。インスタンス接続名は常に PROJECT:REGION:INSTANCE の形式です。

また、App Engine サービスアカウント（たとえば、$PROJECT_ID@appspot.gserviceaccount.com）に Cloud SQL クライアント IAM ロールがあることを確認します。

App Engine サービスが 1 つのプロジェクト（プロジェクト A）に存在し、データベースは別のプロジェクト（プロジェクト B）にある場合、このエラーは、App Engine サービスアカウントには、そのデータベース（プロジェクト B）があるプロジェクトにおいて Cloud SQL クライアント IAM のロールが付与されていないことを意味します。
必ず Cloud SQL Admin API を有効にしてください。

有効になっていない場合は、Cloud SQL Auth Proxy に Error 403: Access Not Configured のような出力が含まれています。
インスタンスリストに複数のインスタンスを含めている場合は、区切り記号としてカンマを使用していることを確認します。TCP を使用している場合は、インスタンスごとに異なるポートを指定していることを確認してください。
UNIX ソケットを使用して接続している場合は、Cloud SQL Auth Proxy の起動時に指定したディレクトリを一覧表示して、ソケットが作成されていることを確認します。
アウトバウンドファイアウォールポリシーがある場合は、ターゲット Cloud SQL インスタンス上のポート 3307 への接続が許可されていることを確認してください。

注: Cloud SQL Auth プロキシは、3307 を使用して Cloud SQL Auth プロキシサーバーに接続します。ポート 5432 は、（Cloud SQL Auth Proxy を使用せず）直接の TCP 接続を経由する PostgreSQL プロトコルのデフォルトポートです。
Google Cloud コンソールの [オペレーション] > [ロギング] > [ログエクスプローラ] でログを調べることで、Cloud SQL Auth プロキシが正しく開始されていることを確認できます。正常なオペレーションは次のようになります。
```
2021/06/14 15:47:56 Listening on /cloudsql/$PROJECT_ID:$REGION:$INSTANCE_NAME/5432 for $PROJECT_ID:$REGION:$INSTANCE_NAME
2021/06/14 15:47:56 Ready for new connections
```
割り当ての問題: Cloud SQL Admin API の割り当てに違反していると、Cloud SQL Auth プロキシは次のエラーメッセージで起動します。
```
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
```
アプリケーションがプロキシに接続すると、プロキシから次のエラーが報告されます。
```
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
```
解決策: 割り当ての問題の原因（たとえば、アプリケーションがコネクタを誤って使用していて、不要な新しい接続を作成している場合があります）を特定するか、サポートに連絡して Cloud SQL Admin API 割り当ての増加をリクエストします。起動時に割り当てエラーが発生した場合は、アプリケーションを再デプロイしてプロキシを再起動する必要があります。起動後に割り当てエラーが発生した場合、再デプロイは必要ありません。

次のステップ

Cloud SQL Auth Proxy の詳細を確認する。
Identity and Access Management（IAM）について確認する。
サービスアカウントの詳細を確認します。
Cloud SQL インスタンスの 2 レベルのアクセス制御について学習します。
ユーザーとデータベースを作成します。
アプリケーションからインスタンスへの接続について学習します。
psql クライアントについて学習します。
サポート用オプションについて学習します。

Cloud SQL Auth Proxy を使用して接続する

概要

始める前に

Cloud SQL Auth Proxy をダウンロードする

Linux 64 ビット

Linux 32 ビット

macOS 64 ビット

Mac M1

Windows 64 ビット

Windows 32 ビット

Cloud SQL Auth Proxy Docker イメージ

その他の OS

Cloud SQL Auth Proxy を起動する

TCP ソケット

Unix ソケット

Docker

TCP ソケットの使用

Unix ソケットの使用

psql クライアントと接続する

Debian / Ubuntu

CentOS / RHEL

openSUSE

他のプラットフォーム

TCP ソケット

Unix ソケットの使用

アプリケーションに接続する

TCP で接続

Python

Java

Node.js

Go

C#

Ruby

PHP

Unix ソケットとの接続

Python

Java

Node.js

C#

Go

Ruby

PHP

その他のトピック

Cloud SQL Auth Proxy のコマンドライン引数

Cloud SQL Auth Proxy の認証オプション

credential_file フラグによって指定された認証情報。

アクセス トークンによって指定された認証情報。

環境変数によって指定された認証情報。

認証済みの gcloud CLI クライアントからの認証情報。

Compute Engine インスタンスに関連付けられている認証情報。

環境のデフォルトのサービス アカウント

サービス アカウントを作成する

プライベート IP で Cloud SQL Auth Proxy を使用する

Private Service Connect が有効化されたインスタンスで Cloud SQL Auth Proxy を使用する

別のプロセスで Cloud SQL Auth Proxy を実行する

Linux

Windows

Docker コンテナで Cloud SQL Auth Proxy を実行する

TCP ソケット

Unix ソケット

サービスとしての Cloud SQL Auth Proxy の実行

Cloud SQL Auth Proxy の使用を適用する

gcloud

REST v1

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

REST v1beta4

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

Cloud SQL Auth Proxy の使用に関するヒント

Cloud SQL Auth Proxy を呼び出す

Cloud SQL Auth Proxy を使用して複数のインスタンスに接続する

Unix ソケット

TCP ソケット

Cloud SQL Auth Proxy 接続のトラブルシューティング

次のステップ

アクセストークンによって指定された認証情報。

環境のデフォルトのサービスアカウント

サービスアカウントを作成する