使用 Cloud SQL 語言連接器建立連線

MySQL   |  PostgreSQL   |  SQL Server

Cloud SQL 連接器是程式庫，可提供加密功能，並在連線至 Cloud SQL 執行個體時，根據 Identity and Access Management (IAM) 進行授權。如果沒有網路路徑，連接器就無法提供連線至 Cloud SQL 執行個體的路徑。

如要連線至 Cloud SQL 執行個體，也可以使用資料庫用戶端或 Cloud SQL 驗證 Proxy。如要進一步瞭解如何連線至 Cloud SQL 執行個體，請參閱「關於連線選項」頁面。

本頁將討論下列 Cloud SQL 連接器：

• Cloud SQL Java 連接器
• Cloud SQL Python 連接器 (在 Colab 中開啟)
• Cloud SQL Go 連接器
• Cloud SQL Node.js 連接器

優點

使用 Cloud SQL 連接器可享有下列優點：

• IAM 授權：使用 IAM 權限控管可連線至 Cloud SQL 執行個體的使用者或項目。
• 便利性：免除管理 SSL 憑證、設定防火牆規則或啟用授權網路的需求。

事前準備

• 啟用 Cloud SQL Admin API。

  啟用 API 時所需的角色

  如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

  啟用 API

• 建立 Cloud SQL 執行個體，包括設定預設使用者。
  

  如要進一步瞭解如何建立執行個體，請參閱建立執行個體。

  如要進一步瞭解如何設定預設使用者，請參閱「設定預設使用者帳戶的密碼」。

• 設定連線至 Cloud SQL 執行個體所需的角色和權限。
  注意： 如果授權 IAM 主體所屬的專案，與包含 Cloud SQL 執行個體的專案不同，則必須執行下列操作：

  • 在兩個專案中啟用 Cloud SQL Admin API。
  • 在包含 Cloud SQL 執行個體的專案中，為 IAM 主體新增 IAM 權限。

設定

Java

Cloud SQL Java 連接器是連線至 Cloud SQL 執行個體時，提供 IAM 授權和加密的程式庫。如果沒有網路路徑，這個連接器無法提供連線至 Cloud SQL 執行個體的路徑。

安裝

如要瞭解如何使用 Cloud SQL Java 連接器，建構及使用 JDBC 和 R2DBC 的驅動程式，請參閱下列連結：

• JDBC：使用 JDBC 連線至 Cloud SQL。
• R2DBC：使用 R2DBC 連線至 Cloud SQL。

如需在應用程式中使用這個程式庫的範例，請參閱這些範例應用程式。

驗證

這個程式庫會使用應用程式預設憑證，驗證與 Cloud SQL 伺服器的連線。

如要在本機啟用憑證，請使用下列 gcloud 指令：

    gcloud auth application-default login
    

連結 Intellij

如要將 IntelliJ 連線至 Cloud SQL 執行個體，您需要在驅動程式設定頁面的「Additional Files」部分，將程式庫新增為含有依附元件的 JAR。舉例來說，您可以在這個頁面找到預先建構的 Fat JAR。

Python

Cloud SQL Python 連接器是可與資料庫驅動程式搭配使用的程式庫，讓具備足夠權限的使用者連線至 Cloud SQL 資料庫，不必手動將 IP 加入許可清單或管理 SSL 憑證。

如需使用 Cloud SQL Python 連接器的互動式範例，請開啟 Cloud SQL Python 連接器筆記本。

SQL Server 支援的驅動程式為 pytds。

安裝

如要安裝最新版本的 Cloud SQL Python 連接器，請使用 pip install 指令，並為資料庫指定 pytds 驅動程式：

    pip install "cloud-sql-python-connector[pytds]"
    

驗證

這個程式庫會使用應用程式預設憑證，驗證與 Cloud SQL 伺服器的連線。

如要在本機啟用憑證，請使用下列 gcloud 指令：

    gcloud auth application-default login
    

Go

Cloud SQL Go 連接器是專為 Go 語言設計的 Cloud SQL 連接器。為提升安全性，這個連接器會在用戶端連接器和伺服器端 Proxy 之間，使用手動驗證的強大 TLS 1.3 加密，與資料庫通訊協定無關。

安裝

您可以使用 go get 安裝這個存放區：

    go get cloud.google.com/go/cloudsqlconn
    

Node.js

Node.js 連接器是專為 Node.js 執行階段設計的程式庫，可讓您安全連線至 Cloud SQL 執行個體。

安裝

您可以使用 npm install 安裝程式庫：

    npm install @google-cloud/cloud-sql-connector
    

使用

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 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 is equivalent to setting the config options below:
    // jdbc:sqlserver://;user=<DB_USER>;password=<DB_PASS>;databaseName=<DB_NAME>;
    // socketFactoryClass=com.google.cloud.sql.sqlserver.SocketFactory;
    // socketFactoryConstructorArg=<INSTANCE_CONNECTION_NAME>

    // 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
        .setDataSourceClassName("com.microsoft.sqlserver.jdbc.SQLServerDataSource");
    config.setUsername(DB_USER); // e.g. "root", "sqlserver"
    config.setPassword(DB_PASS); // e.g. "my-password"
    config.addDataSourceProperty("databaseName", DB_NAME);

    config.addDataSourceProperty("socketFactoryClass",
        "com.google.cloud.sql.sqlserver.SocketFactory");
    config.addDataSourceProperty("socketFactoryConstructorArg", INSTANCE_CONNECTION_NAME);

    // The Java Connector provides SSL encryption, so it should be disabled
    // at the driver level.
    config.addDataSourceProperty("encrypt", "false");

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

注意：如果您設定 encrypt=true 和 trustServerCertificate = false or blank，則必須為執行個體加入 CA file。如果您使用 Cloud SQL 驗證 Proxy，hostNameInCertificate 不得為空白。

Python

如需使用程式庫的詳細操作說明，請參閱「 如何使用這個連接器」。在 GitHub 上查看連線測試程式碼範例。

import os

from google.cloud.sql.connector import Connector, IPTypes
import pytds

import sqlalchemy


def connect_with_connector() -> sqlalchemy.engine.base.Engine:
    """
    Initializes a connection pool for a Cloud SQL instance of SQL Server.

    Uses the Cloud SQL Python Connector package.
    """
    # 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.

    instance_connection_name = os.environ[
        "INSTANCE_CONNECTION_NAME"
    ]  # e.g. 'project:region:instance'
    db_user = os.environ.get("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'

    ip_type = IPTypes.PRIVATE if os.environ.get("PRIVATE_IP") else IPTypes.PUBLIC

    # initialize Cloud SQL Python Connector object
    connector = Connector(ip_type=ip_type, refresh_strategy="LAZY")

    connect_args = {}
    # If your SQL Server instance requires SSL, you need to download the CA
    # certificate for your instance and include cafile={path to downloaded
    # certificate} and validate_host=False. This is a workaround for a known issue.
    if os.environ.get("DB_ROOT_CERT"):  # e.g. '/path/to/my/server-ca.pem'
        connect_args = {
            "cafile": os.environ["DB_ROOT_CERT"],
            "validate_host": False,
        }

    def getconn() -> pytds.Connection:
        conn = connector.connect(
            instance_connection_name,
            "pytds",
            user=db_user,
            password=db_pass,
            db=db_name,
            **connect_args
        )
        return conn

    pool = sqlalchemy.create_engine(
        "mssql+pytds://",
        creator=getconn,
        # ...
    )
    return pool

注意：如果執行個體需要 SSL 連線，您必須為執行個體加入 CA file，Pytds 才能正常運作。如果您也使用 Cloud SQL 驗證 Proxy，則 validate_host 必須設為 False。

Go

如需如何使用程式庫的詳細說明，請參閱「 使用方式」。在 GitHub 上查看連線測試程式碼範例。

package cloudsql

import (
	"context"
	"database/sql"
	"fmt"
	"log"
	"net"
	"os"

	"cloud.google.com/go/cloudsqlconn"
	mssql "github.com/denisenkom/go-mssqldb"
)

type csqlDialer struct {
	dialer     *cloudsqlconn.Dialer
	connName   string
	usePrivate bool
}

// DialContext adheres to the mssql.Dialer interface.
func (c *csqlDialer) DialContext(ctx context.Context, network, addr string) (net.Conn, error) {
	var opts []cloudsqlconn.DialOption
	if c.usePrivate {
		opts = append(opts, cloudsqlconn.WithPrivateIP())
	}
	return c.dialer.Dial(ctx, c.connName, opts...)
}

func connectWithConnector() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Fatal Error in connect_connector.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'
		dbName                 = mustGetenv("DB_NAME")                  // e.g. 'my-database'
		instanceConnectionName = mustGetenv("INSTANCE_CONNECTION_NAME") // e.g. 'project:region:instance'
		usePrivate             = os.Getenv("PRIVATE_IP")
	)

	dbURI := fmt.Sprintf("user id=%s;password=%s;database=%s;", dbUser, dbPwd, dbName)
	c, err := mssql.NewConnector(dbURI)
	if err != nil {
		return nil, fmt.Errorf("mssql.NewConnector: %w", err)
	}
	// WithLazyRefresh() Option is used to perform refresh
	// when needed, rather than on a scheduled interval.
	// This is recommended for serverless environments to
	// avoid background refreshes from throttling CPU.
	dialer, err := cloudsqlconn.NewDialer(context.Background(), cloudsqlconn.WithLazyRefresh())
	if err != nil {
		return nil, fmt.Errorf("cloudsqlconn.NewDailer: %w", err)
	}
	c.Dialer = &csqlDialer{
		dialer:     dialer,
		connName:   instanceConnectionName,
		usePrivate: usePrivate != "",
	}

	dbPool := sql.OpenDB(c)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %w", err)
	}
	return dbPool, nil
}

注意：如果執行個體需要 SSL 連線，您必須為執行個體加入 CA file，Pytds 才能正常運作。如果您也使用 Cloud SQL 驗證 Proxy，則 validate_host 必須設為 False。

Node.js

如需使用程式庫的詳細操作說明，請參閱「 使用方式」。

const {Connection} = require('tedious');
const {Connector} = require('@google-cloud/cloud-sql-connector');

// In case the PRIVATE_IP environment variable is defined then we set
// the ipType=PRIVATE for the new connector instance, otherwise defaults
// to public ip type.
const getIpType = () =>
  process.env.PRIVATE_IP === '1' || process.env.PRIVATE_IP === 'true'
    ? 'PRIVATE'
    : 'PUBLIC';

// connectWithConnector initializes a TCP connection
// to a Cloud SQL instance of SQL Server.
const connectWithConnector = 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 connector = new Connector();
  const clientOpts = await connector.getTediousOptions({
    instanceConnectionName: process.env.INSTANCE_CONNECTION_NAME,
    ipType: getIpType(),
  });
  const dbConfig = {
    // Please note that the `server` property here is not used and is only
    // defined due to a bug in the tedious driver
    // (ref: https://github.com/tediousjs/tedious/issues/1541)
    // With that in mind, do not try to change this value since it will have no
    // impact in how the connector works, this sample will be updated to remove
    // this property declaration as soon as the tedious driver bug is fixed
    server: '0.0.0.0', // e.g. '127.0.0.1'
    authentication: {
      type: 'default',
      options: {
        userName: process.env.DB_USER, // e.g. 'my-db-user'
        password: process.env.DB_PASS, // e.g. 'my-db-password'
      },
    },
    options: {
      ...clientOpts,
      // Please note that the `port` property here is not used and is only
      // defined due to a bug in the tedious driver
      // (ref: https://github.com/tediousjs/tedious/issues/1541)
      // With that in mind, do not try to change this value since it will have
      // no impact in how the connector works, this sample will be updated to
      // remove this property declaration as soon as the tedious driver bug is
      // fixed
      port: 9999,
      database: process.env.DB_NAME, // e.g. 'my-database'
      useColumnNames: true,
    },
    // ... Specify additional properties here.
    ...config,
  };

  // Establish a connection to the database.
  return new Connection(dbConfig);
};

強制執行

透過連接器強制執行，您可以強制規定只能使用 Cloud SQL Auth Proxy 或 Cloud SQL 語言連接器連線至 Cloud SQL 執行個體。強制執行連接器後，Cloud SQL 會拒絕直接連線至資料庫。

如果您使用已啟用 Private Service Connect 的執行個體，則有相關限制。如果執行個體已啟用連接器強制執行功能，就無法為該執行個體建立讀取副本。同樣地，如果執行個體有讀取副本，就無法為該執行個體啟用連接器強制執行功能。

gcloud

如要強制僅使用 Cloud SQL Auth Proxy 或 Cloud SQL 語言連接器連線至執行個體，請使用 gcloud sql instances patch 指令：

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

將 INSTANCE_NAME 改成 Cloud SQL 執行個體的名稱。

REST

使用任何要求資料之前，請先修改下列項目的值：

• PROJECT_ID：包含執行個體的專案 ID 或專案編號 Google Cloud
• INSTANCE_NAME：Cloud SQL 執行個體的名稱

注意：將 connectorEnforcement 參數的值設為 REQUIRED 後，所有連線都必須使用 Cloud SQL 語言連接器，包括 Cloud SQL Auth Proxy 和 Java、Python、Go 與 Node.js 連接器。

HTTP 方法和網址：

PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

JSON 要求主體：

{
  "kind": "sql#instance",
  "name": INSTANCE_NAME,
  "project": PROJECT_ID,
  "settings": {
  "connectorEnforcement": "REQUIRED",
  "kind": "sql#settings"
  }
}

請展開以下其中一個選項，以傳送要求：

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_NAME"

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_NAME" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

疑難排解

驅動程式版本

請務必使用最新版本的 Cloud SQL 連接器和資料庫驅動程式，以免發生不相容問題。部分舊版驅動程式不受支援。

連線路徑

Cloud SQL 連接器會授權連線，但不會提供新的連線路徑。舉例來說，如要使用私人 IP 位址連線至 Cloud SQL 執行個體，應用程式必須已具備虛擬私有雲存取權。

針對連線問題進行偵錯

如需連線問題的相關說明，請參閱「疑難排解」和「偵錯連線問題」頁面。

後續步驟

• 請參閱 GitHub 上的 Cloud SQL Java 連接器首頁。
• 請參閱 GitHub 上的 Cloud SQL Python 連接器首頁。
• 進一步瞭解 Cloud SQL Auth Proxy。
• 進一步瞭解身分與存取權管理。
• 瞭解支援的選項。