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

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

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

プロキシの仕組みの詳細については、Cloud SQL Auth Proxy についてをご覧ください。

始める前に

MySQL を Cloud SQL インスタンスに接続するには、以下を実行しておく必要があります。

Cloud SQL Admin API を有効にする

API を有効にする
Cloud SQL インスタンスを作成し、デフォルトユーザーを構成する。

インスタンスの作成の詳細については、インスタンスを作成するをご覧ください。

デフォルトユーザーの構成については、デフォルトユーザーアカウントを構成するをご覧ください。
MySQL クライアントをインストールします。
Cloud SDK をインストールし、初期化する。
必要に応じて、Docker クライアントをインストールする。

Cloud SQL Auth Proxy を認証するためのオプション

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

gcloud sql instances describe INSTANCE_NAME

例: myproject:myregion:myinstance。

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

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

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

gcloud auth login 用のアカウントが選択されていない場合は、Cloud SQL Auth Proxy によって 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 Console の [サービスアカウント] ページに移動します。
[サービスアカウント] ページに移動
Cloud SQL インスタンスを含むプロジェクトを選択します。
[サービスアカウントを作成] をクリックします。
[サービスアカウントの作成] ダイアログで、わかりやすいサービスアカウント名を指定します。
[サービスアカウント ID] を一意のわかりやすい値に変更してから、[作成] をクリックします。
[ロール] には、次のいずれかのロールを選択してから、[続行] をクリックし、[完了] をクリックします。
- [Cloud SQL] > [Cloud SQL クライアント]
- [Cloud SQL] > [Cloud SQL 編集者]
- [Cloud SQL] > [Cloud SQL 管理者]
新しいサービスアカウントの操作メニューをクリックし、[鍵を管理] を選択します。
[鍵を追加] プルダウンメニューをクリックして、[新しい鍵の作成] をクリックします。
鍵のタイプが JSON であることを確認し、[作成] をクリックします。
秘密鍵ファイルがマシンにダウンロードされます。秘密鍵ファイルは、別の場所に移動できます。安全な場所に鍵ファイルを保管してください。

Cloud SQL Auth Proxy をインストールする

Linux 64 ビット

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

wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy

Cloud SQL Auth Proxy を動作可能にします。
```
chmod +x cloud_sql_proxy
```

Linux 32 ビット

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

wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy

Cloud SQL Auth Proxy を動作可能にします。
```
chmod +x cloud_sql_proxy
```

macOS 64 ビット

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

curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64

Cloud SQL Auth Proxy を動作可能にします。
```
chmod +x cloud_sql_proxy
```

macOS 32 ビット

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

curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386

Cloud SQL Auth Proxy を動作可能にします。
```
chmod +x cloud_sql_proxy
```

Windows 64 ビット

https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe を右クリックして [名前を付けてリンク先を保存] を選択し、Cloud SQL Auth Proxy をダウンロードします。ファイル名を cloud_sql_proxy.exe に変更します。

Windows 32 ビット

https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe を右クリックして [名前を付けてリンク先を保存] を選択し、Cloud SQL Auth Proxy をダウンロードします。ファイル名を cloud_sql_proxy.exe に変更します。

Cloud SQL Auth Proxy の Docker イメージ

便宜上、Cloud SQL チームは、お客様が使用する Cloud SQL Auth Proxy を含むいくつかのコンテナイメージを保持しています。これらのイメージの詳細については、GitHub の Cloud SQL Auth Proxy リポジトリをご覧ください。次のコマンドを使用して、最新のイメージをローカルマシンに Docker で pull できます。

docker pull gcr.io/cloudsql-docker/gce-proxy:1.19.1

その他の 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）でリッスンします。したがって、インスタンスに tcp:PORT_NUMBER を指定すると、ローカル接続は 127.0.0.1:PORT_NUMBER になります。

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

  ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1234

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

Unix ソケット

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

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

明示的なインスタンス指定を使用する場合は、INSTANCE_CONNECTION_NAME をコピーします。これは、Google Cloud Console のインスタンスの [概要] ページで確認できます。また、以下のコマンドを実行して確認することもできます。
```
gcloud sql instances describe INSTANCE_NAME
```
.
例: myproject:myregion:myinstance。
Cloud SQL Auth Proxy ソケットを格納するディレクトリを作成します。
```
sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
```
サービスアカウントを使用して Cloud SQL Auth Proxy を認証する場合は、サービスアカウントを作成したときに作成された秘密鍵ファイルのクライアントマシン上での場所を記録しておきます。
新しいターミナルウィンドウを開き、Cloud SQL Auth Proxy を起動します。
有効な Cloud SQL Auth Proxy の呼び出し文字列:
- サービスアカウントを使用して、インスタンス接続の名前を明示的に指定する場合（本番環境用に推奨）:
```
./cloud_sql_proxy -dir=/cloudsql -instances=INSTANCE_CONNECTION_NAME
-credential_file=PATH_TO_KEY_FILE &
```
- Cloud SDK 認証と自動インスタンス検出を使用する場合
```
./cloud_sql_proxy -dir=/cloudsql &
```
専用のターミナルで 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"

Cloud SQL Auth Proxy の 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 Console のインスタンスの [概要] ページに表示されます。また、次のコマンドを実行して確認することもできます。

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:/config \\
  -p 127.0.0.1:3306:3306 \\
  gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy \\
  -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:3306 -credential_file=/config

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

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:/config \\
  gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy -dir=/cloudsql \\
  -instances=INSTANCE_CONNECTION_NAME -credential_file=/config

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

-v /mnt/stateful_partition/cloudsql:/cloudsql

複数のインスタンスをカンマで区切って指定できます。また、Compute Engine メタデータを使用して接続対象のインスタンスを動的に決定することもできます。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 に接続する

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

TCP ソケット

MySQL クライアントを起動します。
```
mysql -u USERNAME -p --host 127.0.0.1
```
TCP ソケットを使用して接続する場合、Cloud SQL Auth Proxy には 127.0.0.1 経由でアクセスします。
プロンプトが表示されたら、パスワードを入力します。
MySQL プロンプトが表示されます。

Unix ソケットの使用

MySQL クライアントを起動します。

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

パスワードを入力します。
MySQL プロンプトが表示されます。

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

言語別のコードサンプル

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

TCP で接続

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

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:3306 &

Python

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

cloud-sql/mysql/sqlalchemy/main.py

GitHub で表示

# Remember - storing secrets in plaintext is potentially unsafe. Consider using
# something like https://cloud.google.com/secret-manager/docs/overview to help keep
# secrets secret.
db_user = os.environ["DB_USER"]
db_pass = os.environ["DB_PASS"]
db_name = os.environ["DB_NAME"]
db_host = os.environ["DB_HOST"]

# Extract host and port from db_host
host_args = db_host.split(":")
db_hostname, db_port = host_args[0], int(host_args[1])

pool = sqlalchemy.create_engine(
    # Equivalent URL:
    # mysql+pymysql://<db_user>:<db_pass>@<db_host>:<db_port>/<db_name>
    sqlalchemy.engine.url.URL(
        drivername="mysql+pymysql",
        username=db_user,  # e.g. "my-database-user"
        password=db_pass,  # e.g. "my-database-password"
        host=db_hostname,  # e.g. "127.0.0.1"
        port=db_port,  # e.g. 3306
        database=db_name,  # e.g. "my-database-name"
    ),
    **db_config
)

Java

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

cloud-sql/mysql/servlet/src/main/java/com/example/cloudsql/ConnectionPoolContextListener.java

GitHub で表示

// Note: For Java users, the Cloud SQL JDBC Socket Factory can provide authenticated connections
// which is preferred to using the Cloud SQL Proxy with Unix sockets.
// See https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory for details.

// The configuration object specifies behaviors for the connection pool.
HikariConfig config = new HikariConfig();

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

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

config.addDataSourceProperty("socketFactory", "com.google.cloud.sql.mysql.SocketFactory");
config.addDataSourceProperty("cloudSqlInstance", CLOUD_SQL_CONNECTION_NAME);

// The ipTypes argument can be used to specify a comma delimited list of preferred IP types
// for connecting to a Cloud SQL instance. The argument ipTypes=PRIVATE will force the
// SocketFactory to connect with an instance's associated private IP.
config.addDataSourceProperty("ipTypes", "PUBLIC,PRIVATE");

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

// Initialize the connection pool using the configuration object.
DataSource pool = new HikariDataSource(config);

Node.js

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

cloud-sql/mysql/mysql/server.js

GitHub で表示

const createTcpPool = async config => {
  // Extract host and port from socket address
  const dbSocketAddr = process.env.DB_HOST.split(':');

  // Establish a connection to the database
  return await mysql.createPool({
    user: process.env.DB_USER, // e.g. 'my-db-user'
    password: process.env.DB_PASS, // e.g. 'my-db-password'
    database: process.env.DB_NAME, // e.g. 'my-database'
    host: dbSocketAddr[0], // e.g. '127.0.0.1'
    port: dbSocketAddr[1], // e.g. '3306'
    // ... Specify additional properties here.
    ...config,
  });
};

Go

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

cloudsql/mysql/database-sql/cloudsql.go

GitHub で表示

var (
	dbUser    = mustGetenv("DB_USER") // e.g. 'my-db-user'
	dbPwd     = mustGetenv("DB_PASS") // e.g. 'my-db-password'
	dbTCPHost = mustGetenv("DB_HOST") // e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
	dbPort    = mustGetenv("DB_PORT") // e.g. '3306'
	dbName    = mustGetenv("DB_NAME") // e.g. 'my-database'
)

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

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

// ...

return dbPool, nil

C#

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

cloud-sql/mysql/Startup.cs

GitHub で表示

            // Equivalent connection string:
            // "Uid=<DB_USER>;Pwd=<DB_PASS>;Host=<DB_HOST>;Database=<DB_NAME>;"
            var connectionString = new MySqlConnectionStringBuilder()
            {
                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = MySqlSslMode.None,

                // Remember - storing secrets in plain text is potentially unsafe. Consider using
                // something like https://cloud.google.com/secret-manager/docs/overview to help keep
                // secrets secret.
                Server = Environment.GetEnvironmentVariable("DB_HOST"),   // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                UserID = Environment.GetEnvironmentVariable("DB_USER"),   // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;

Ruby

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

cloud-sql/mysql/activerecord/config/database.yml

GitHub で表示

development:
  adapter: mysql2
  # Configure additional properties here
  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("DB_HOST") { "127.0.0.1" }%>" # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT") { 3306 }%>
  socket: "<%= ENV.fetch("DB_SOCKET_DIR") { '/cloudsql' } %>/<%= ENV["INSTANCE_CONNECTION_NAME"] %>"

PHP

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

cloud_sql/mysql/pdo/src/DBInitializer.php

GitHub で表示

// $username = 'your_db_user';
// $password = 'yoursupersecretpassword';
// $dbName = 'your_db_name';
// $dbHost = "127.0.0.1";

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

// Connect to the database
$conn = new PDO($dsn, $username, $password, $connConfig);

Unix ソケットとの接続

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

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME -dir=/cloudsql &

Python

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

cloud-sql/mysql/sqlalchemy/main.py

GitHub で表示

# Remember - storing secrets in plaintext is potentially unsafe. Consider using
# something like https://cloud.google.com/secret-manager/docs/overview to help keep
# secrets secret.
db_user = os.environ["DB_USER"]
db_pass = os.environ["DB_PASS"]
db_name = os.environ["DB_NAME"]
db_socket_dir = os.environ.get("DB_SOCKET_DIR", "/cloudsql")
cloud_sql_connection_name = os.environ["CLOUD_SQL_CONNECTION_NAME"]

pool = sqlalchemy.create_engine(
    # Equivalent URL:
    # mysql+pymysql://<db_user>:<db_pass>@/<db_name>?unix_socket=<socket_path>/<cloud_sql_instance_name>
    sqlalchemy.engine.url.URL(
        drivername="mysql+pymysql",
        username=db_user,  # e.g. "my-database-user"
        password=db_pass,  # e.g. "my-database-password"
        database=db_name,  # e.g. "my-database-name"
        query={
            "unix_socket": "{}/{}".format(
                db_socket_dir,  # e.g. "/cloudsql"
                cloud_sql_connection_name)  # i.e "<PROJECT-NAME>:<INSTANCE-REGION>:<INSTANCE-NAME>"
        }
    ),
    **db_config
)

Java

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

cloud-sql/mysql/servlet/src/main/java/com/example/cloudsql/ConnectionPoolContextListener.java

GitHub で表示

// Note: For Java users, the Cloud SQL JDBC Socket Factory can provide authenticated connections
// which is preferred to using the Cloud SQL Proxy with Unix sockets.
// See https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory for details.

// The configuration object specifies behaviors for the connection pool.
HikariConfig config = new HikariConfig();

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

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

config.addDataSourceProperty("socketFactory", "com.google.cloud.sql.mysql.SocketFactory");
config.addDataSourceProperty("cloudSqlInstance", CLOUD_SQL_CONNECTION_NAME);

// The ipTypes argument can be used to specify a comma delimited list of preferred IP types
// for connecting to a Cloud SQL instance. The argument ipTypes=PRIVATE will force the
// SocketFactory to connect with an instance's associated private IP.
config.addDataSourceProperty("ipTypes", "PUBLIC,PRIVATE");

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

// Initialize the connection pool using the configuration object.
DataSource pool = new HikariDataSource(config);

Node.js

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

cloud-sql/mysql/mysql/server.js

GitHub で表示

const createUnixSocketPool = async config => {
  const dbSocketPath = process.env.DB_SOCKET_PATH || '/cloudsql';

  // Establish a connection to the database
  return await mysql.createPool({
    user: process.env.DB_USER, // e.g. 'my-db-user'
    password: process.env.DB_PASS, // e.g. 'my-db-password'
    database: process.env.DB_NAME, // e.g. 'my-database'
    // If connecting via unix domain socket, specify the path
    socketPath: `${dbSocketPath}/${process.env.CLOUD_SQL_CONNECTION_NAME}`,
    // Specify additional properties here.
    ...config,
  });
};

C#

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

cloud-sql/mysql/Startup.cs

GitHub で表示

// Equivalent connection string:
// "Server=<dbSocketDir>/<INSTANCE_CONNECTION_NAME>;Uid=<DB_USER>;Pwd=<DB_PASS>;Database=<DB_NAME>;Protocol=unix"
String dbSocketDir = Environment.GetEnvironmentVariable("DB_SOCKET_PATH") ?? "/cloudsql";
String instanceConnectionName = Environment.GetEnvironmentVariable("INSTANCE_CONNECTION_NAME");
var connectionString = new MySqlConnectionStringBuilder()
{
    // The Cloud SQL proxy provides encryption between the proxy and instance.
    SslMode = MySqlSslMode.None,
    // Remember - storing secrets in plain text is potentially unsafe. Consider using
    // something like https://cloud.google.com/secret-manager/docs/overview to help keep
    // secrets secret.
    Server = String.Format("{0}/{1}", dbSocketDir, instanceConnectionName),
    UserID = Environment.GetEnvironmentVariable("DB_USER"),   // e.g. 'my-db-user
    Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
    Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'
    ConnectionProtocol = MySqlConnectionProtocol.UnixSocket
};
connectionString.Pooling = true;
// Specify additional properties here.
return connectionString;

Go

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

cloudsql/mysql/database-sql/cloudsql.go

GitHub で表示

var (
	dbUser                 = mustGetenv("DB_USER")                  // e.g. 'my-db-user'
	dbPwd                  = mustGetenv("DB_PASS")                  // e.g. 'my-db-password'
	instanceConnectionName = mustGetenv("INSTANCE_CONNECTION_NAME") // e.g. 'project:region:instance'
	dbName                 = mustGetenv("DB_NAME")                  // e.g. 'my-database'
)

socketDir, isSet := os.LookupEnv("DB_SOCKET_DIR")
if !isSet {
	socketDir = "/cloudsql"
}

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

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

// ...

return dbPool, nil

Ruby

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

cloud-sql/mysql/activerecord/config/database.yml

GitHub で表示

production:
  adapter: mysql2
  # Configure additional properties here.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_production" } %>
  socket: "<%= ENV.fetch("DB_SOCKET_DIR") { '/cloudsql' } %>/<%= ENV["INSTANCE_CONNECTION_NAME"] %>"

PHP

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

cloud_sql/mysql/pdo/src/DBInitializer.php

GitHub で表示

// $username = 'your_db_user';
// $password = 'yoursupersecretpassword';
// $dbName = 'your_db_name';
// $connectionName = getenv("CLOUD_SQL_CONNECTION_NAME");
// $socketDir = getenv('DB_SOCKET_DIR') ?: '/cloudsql';

// Connect using UNIX sockets
$dsn = sprintf(
    'mysql:dbname=%s;unix_socket=%s/%s',
    $dbName,
    $socketDir,
    $connectionName
);

// Connect to the database.
$conn = new PDO($dsn, $username, $password, $conn_config);

その他のトピック

プライベート IP でのプロキシの使用

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

プロキシは、IP を使用して Cloud SQL インスタンスとの接続を確立します。デフォルトでは、プロキシはパブリック IPv4 アドレスを使用して接続を試行します。Cloud SQL インスタンスにプライベート IP しかない場合、プロキシはプライベート IP アドレスを使用して接続します。

インスタンスにパブリック IP とプライベート IP の両方が構成されている場合に、プロキシによってプライベート IP アドレスが使用されるようにするには、プロキシの開始時に次のオプションを指定する必要があります。

-ip_address_types=PRIVATE

データベースユーザーアカウントに Cloud SQL Auth Proxy を要求する

プロキシを使用してインスタンスに接続するときは、インスタンスにログインするためのユーザーアカウントを指定します。この場合、任意のデータベースユーザーアカウントを使用することができます。ただし、プロキシは常にプロキシ以外ではアクセスできないホスト名から接続するので、プロキシによってのみ使用できるユーザーアカウントを作成できます。このようにすると、インスタンスまたはデータのセキュリティを損なうことなく、パスワードを使用しないでこのアカウントを指定できるという利点があります。

Cloud SQL Auth Proxy でのみ使用できるユーザーアカウントを作成するには、ホスト名を 'cloudsqlproxy~[IP_ADDRESS]' として指定します。また、IP アドレスのワイルドカードを使用して、'cloudsqlproxy~%' にすることもできます。完全なユーザーアカウント名は次のようになります。

'[USER_NAME]'@'cloudsqlproxy~%'

または

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

ユーザーの作成については、ユーザーを作成して管理するをご覧ください。Cloud SQL でユーザーアカウントがどのように使用されるかについては、ユーザーをご覧ください。

プロキシを別のプロセスで実行する

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

Linux

Linux または macOS では、コマンドラインで末尾の & を使用して、別のプロセスでプロキシを起動します。

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER
  -credential_file=PATH_TO_KEY_FILE &

Windows

Windows PowerShell では、Start-Process コマンドを使用してプロキシを別のプロセスで起動します。

Start-Process -filepath "cloud_sql_proxy.exe"
  -ArgumentList "-instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER
  -credential_file=PATH_TO_KEY_FILE"

Docker コンテナでの Cloud SQL Auth Proxy の実行

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

docker pull gcr.io/cloudsql-docker/gce-proxy:1.19.1

プロキシは、次のコマンドで TCP ソケットまたは Unix ソケットのどちらかを使用して開始できます。

TCP ソケット

    docker run -d \
      -v PATH_TO_KEY_FILE:/config \
      -p 127.0.0.1:3306:3306 \
      gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy \
      -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:3306 \
      -credential_file=/config

Unix ソケット

    docker run -d \
      -v /PATH_TO_HOST_TARGET:/PATH_TO_GUEST_TARGET \
      -v PATH_TO_KEY_FILE:/config \
      gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy -dir=/cloudsql \
      -instances=INSTANCE_CONNECTION_NAME
      -credential_file=/config/PATH_TO_KEY_FILE

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

-v /mnt/stateful_partition/cloudsql:/cloudsql

Cloud SQL Auth Proxy をサービスとして実行する

プロキシをバックグラウンドサービスとして実行すると、ローカルでの開発やテストに便利です。Cloud SQL インスタンスにアクセスする必要がある場合は、バックグラウンドでサービスを開始し、終了したらサービスを停止できます。

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

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

Cloud SQL Auth Proxy の呼び出し

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

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

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

プロキシを使用した複数のインスタンスへの接続

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

Unix ソケット

プロキシを複数のインスタンスに接続するには、インスタンス接続名をカンマ区切りリスト（スペースなし）で、-instances パラメータ付きで指定します。プロキシは、起動時に各インスタンスに接続します。

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

次に例を示します。

      ./cloud_sql_proxy -dir=/cloudsql -instances=myProject:us-central1:myInstance,myProject:us-central1:myInstance2 &
      mysql -u myUser -S /cloudsql/myProject:us-central1:myInstance2

TCP ソケット

TCP を使用して接続する場合は、インスタンスへの接続に使用するマシンでポートを指定します。すべてのインスタンスに専用のポートが必要です。mysql ツールではデフォルトで 3306 を使用しますが、別のポートを使用するように指定することもできます。

次に例を示します。

    # Start the proxy for two instances, each with its own port:

    ./cloud_sql_proxy -instances=myProject:us-central1:myInstance=tcp:3306,myProject:us-central1:myInstance2=tcp:1234

    # Connect to "myInstance" on port 3306, and "myInstance2" on port 1234

    mysql -u myInstanceUser --host 127.0.0.1  --port 3306
    mysql -u myInstance2User --host 127.0.0.1  --port 1234

プロキシの呼び出しと MySQL クライアント接続文字列

myProject プロジェクトの us-central1 にある myInstance インスタンスの MySQL ユーザー myUser に対するプロキシ呼び出しと接続文字列を使用できます。

自動インスタンス検出と gcloud 認証情報を使用する場合:

    ./cloud_sql_proxy -dir=/cloudsql &
    mysql -u myUser -S /cloudsql/myProject:us-central1:myInstance

プロジェクト検出と gcloud 認証情報を使用する場合:

    ./cloud_sql_proxy -dir=/cloudsql -projects=myProject &
    mysql -u myUser -S /cloudsql/myProject:us-central1:

Compute Engine インスタンスでインスタンスを明示的に指定する場合:

    ./cloud_sql_proxy -dir=/cloudsql -instances=myProject:us-central1:myInstance &
    mysql -u myUser -S /cloudsql/myProject:us-central1:myInstance

Unix で TCP を使用する場合:

    ./cloud_sql_proxy -instances=myProject:us-central1:myInstance=tcp:3306 &
    mysql -u myUser --host 127.0.0.1

Windows の場合（コマンドラインプロンプト）:

    cloud_sql_proxy.exe -instances=myProject:us-central1:myInstance=tcp:3306
    mysql -u myUser --host 127.0.0.1

Cloud SQL Auth Proxy のオプションと接続文字列の詳細については、Cloud SQL Auth Proxy GitHub ページをご覧ください。

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

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

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

プロキシ出力を確認します。

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

サービスアカウントを確認するには、IAM ページでアカウントの ID を検索します。cloudsql.instances.connect 権限が必要です。この権限は、事前定義ロールの Cloud SQL Admin、Client、Editor に含まれています。
必ず Cloud SQL Admin API を有効にしてください。

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

注: ポート 3307 は、Cloud SQL Auth Proxy がプロキシサーバーに接続するために使用します。ポート 3306 は、（Cloud SQL Auth Proxy を使用せず）直接の TCP 接続を経由する MySQL プロトコルのデフォルトポートです。

次のステップ

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

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

始める前に

Cloud SQL Admin API を有効にする

Cloud SQL Auth Proxy を認証するためのオプション

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

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

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

認証済みの Cloud SDK クライアントの認証情報。

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

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

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

Cloud SQL Auth Proxy をインストールする

Linux 64 ビット

Linux 32 ビット

macOS 64 ビット

macOS 32 ビット

Windows 64 ビット

Windows 32 ビット

Cloud SQL Auth Proxy の Docker イメージ

その他の OS

Cloud SQL Auth Proxy の起動

TCP ソケット

Unix ソケット

Cloud SQL Auth Proxy の Docker イメージ

TCP ソケットの使用

Unix ソケットの使用

その他のコマンドライン引数

Cloud SQL Auth Proxy に接続する

TCP ソケット

Unix ソケットの使用

言語別のコードサンプル

TCP で接続

Python

Java

Node.js

Go

C#

Ruby

PHP

Unix ソケットとの接続

Python

Java

Node.js

C#

Go

Ruby

PHP

その他のトピック

プライベート IP でのプロキシの使用

データベース ユーザー アカウントに Cloud SQL Auth Proxy を要求する

プロキシを別のプロセスで実行する

Linux

Windows

Docker コンテナでの Cloud SQL Auth Proxy の実行

TCP ソケット

Unix ソケット

Cloud SQL Auth Proxy をサービスとして実行する

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

Cloud SQL Auth Proxy の呼び出し

プロキシを使用した複数のインスタンスへの接続

Unix ソケット

TCP ソケット

プロキシの呼び出しと MySQL クライアント接続文字列

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

次のステップ

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

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

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

データベースユーザーアカウントに Cloud SQL Auth Proxy を要求する