從外部應用程式連線至 Cloud SQL

本頁面說明如何從在 Google Cloud Platform 外執行的應用程式連線至 Cloud SQL。

如要瞭解連線至 Cloud SQL 的各種選項,請參閱外部應用程式的連線選項。如需如何設定公開 IP 的資訊,請參閱設定公開 IP

資料庫連線會耗用伺服器與連線中應用程式的資源,因此請務必要使用合適的連線管理做法,以便將應用程式耗用的資源降到最低,同時降低超過 Cloud SQL 連線限制的可能性。詳情請參閱管理資料庫連線

事前準備

授予應用程式的存取權限,並不會讓資料庫使用者帳戶自動連結執行個體。您必須要有可用來連線的資料庫使用者帳戶,才能連線至執行個體。而對於新的執行個體,這代表您必須已經設定預設的使用者帳戶。瞭解詳情

您可以使用下列方法連線至 Cloud SQL 執行個體:

使用 Proxy 從外部應用程式連結

如果您要在本機測試環境 (而不是實際工作環境) 中設定 Cloud SQL Proxy,可以使用 Proxy 快速入門而無需遵循下列操作說明。

如果您是使用 Java 或 Go 程式設計語言,可以採用其他替代方案來使用 Cloud SQL Proxy。瞭解詳情

1. 啟用 API

啟用Cloud SQL Admin API。

啟用 API

2.在本機電腦上安裝 Proxy 用戶端

Linux 64 位元

  1. 下載 Proxy:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
    
  2. 將 Proxy 設定為可執行:
    chmod +x cloud_sql_proxy
    

Linux 32 位元

  1. 下載 Proxy:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
    
  2. 將 Proxy 設定為可執行:
    chmod +x cloud_sql_proxy
    

macOS 64 位元

  1. 下載 Proxy:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
    
  2. 將 Proxy 設定為可執行:
    chmod +x cloud_sql_proxy
    

macOS 32 位元

  1. 下載 Proxy:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
    
  2. 將 Proxy 設定為可執行:
    chmod +x cloud_sql_proxy
    

Windows 64 位元

用滑鼠右鍵按一下 https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe,然後選取 [Save Link As] (另存連結為) 來下載 Proxy。請將檔案重新命名為 cloud_sql_proxy.exe

Windows 32 位元

用滑鼠右鍵按一下 https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe,然後選取 [Save Link As] (另存連結為) 來下載 Proxy。請將檔案重新命名為 cloud_sql_proxy.exe
如果這裡沒有列出您的作業系統,您也可以利用原始碼編譯 Proxy

3. 決定您要驗證 Proxy 的方式

進一步瞭解 Proxy 驗證選項

4. 建立服務帳戶 (如果驗證方式要求您這麼做)

  1. 前往 Google Cloud Platform 主控台的「Service accounts」(服務帳戶) 頁面。

    前往「Service accounts」(服務帳戶) 頁面

  2. 視需要選取包含您的 Cloud SQL 執行個體的專案。
  3. 按一下 [Create service account] (建立服務帳戶)
  4. 在「建立服務帳戶」對話方塊中,提供服務帳戶的描述性名稱。
  5. 在「Role」(角色) 部分,選取下列其中一個角色:
    • Cloud SQL > Cloud SQL 用戶端
    • Cloud SQL > Cloud SQL 編輯者
    • Cloud SQL > Cloud SQL 管理員

    或者,您可以選取 [Project] (專案) > [Editor] (編輯者) 來使用原始編輯者角色,但編輯者角色包含跨 Google Cloud Platform 的權限。

    如果您沒有看到這些角色,即表示您的 Google Cloud Platform 使用者可能沒有 resourcemanager.projects.setIamPolicy 權限。 您可以前往 Google Cloud Platform 主控台的 IAM 頁面,然後搜尋您的使用者 ID,藉以檢查您的權限。

  6. 將「Service account ID」(服務帳戶 ID) 變更為您可辨識的唯一值,方便您日後能夠在需要時輕鬆找到這個服務帳戶。
  7. 按一下 [Furnish a new private key] (提供一組新的私密金鑰)
  8. 預設金鑰類型為 JSON,這就是正確的值。
  9. 按一下 [Create] (建立)

    私密金鑰檔案會下載到您的機器中,您可以將它移到其他位置。請妥善保護這個金鑰檔案。

5. 決定如何指定 Proxy 的執行個體

進一步瞭解 Proxy 執行個體規格選項

6. 啟動 Proxy

您傳送給 Proxy 的選項取決於您之前選擇的驗證與執行個體規格選項。

依據您使用的語言和環境,您可以使用 TCP 通訊端或 Unix 通訊端啟動 Proxy。

TCP 通訊端

  1. 從「Instance details」(執行個體詳細資料) 頁面複製您的執行個體連線名稱。

    例如:myproject:us-central1:myinstance

  2. 如果您使用服務帳戶來驗證 Proxy,請記下您在建立服務帳戶時建立的私密金鑰檔案的用戶端機器位置。
  3. 啟動 Proxy。

    下列為一些可能使用的 Proxy 叫用字串:

    • 使用 Cloud SDK 驗證:
      ./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432
      
      請勿指定使用中的通訊埠,例如本機資料庫伺服器正在使用的通訊埠。
    • 使用服務帳戶並明確指定執行個體 (建議用於實際工作環境):
      ./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432 \
                        -credential_file=<PATH_TO_KEY_FILE> &
      

    如要進一步瞭解 Proxy 選項,請參閱驗證 Proxy 的選項指定執行個體的選項相關各節。

Unix 通訊端

  1. 如果您要明確指定執行個體,請從「Instance details」(執行個體詳細資料) 頁面複製執行個體連線名稱。
  2. 建立 Proxy 通訊端運作的目錄:
    sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
  3. 如果您使用服務帳戶來驗證 Proxy,請記下您之前建立服務帳戶時,私密金鑰檔案在用戶端機器上的建立位置。
  4. 開啟新的終端機視窗,然後啟動 Proxy。

    以下是幾個可能的 Proxy 叫用字串:

    • 使用服務帳戶並明確指定執行個體 (建議用於實際工作環境):
      ./cloud_sql_proxy -dir=/cloudsql -instances=<INSTANCE_CONNECTION_NAME> \
                        -credential_file=<PATH_TO_KEY_FILE> &
    • 使用 Cloud SDK 驗證和自動探索執行個體功能:
      ./cloud_sql_proxy -dir=/cloudsql &

    建議您在 Proxy 本身的終端機上啟動 Proxy,如此可避免將 Proxy 的輸出與其他程式的輸出混在一起,以便您監控 Proxy 的輸出。

    如要進一步瞭解 Proxy 選項,請參閱驗證 Proxy 的選項指定執行個體的選項相關各節。

7. 更新應用程式以使用 Proxy 連線至 Cloud SQL

使用 Proxy 連線至 Cloud SQL 執行個體所需的正確程式碼陳述式,取決於您使用的語言和架構。

連線至 Proxy 的方式與連線至 TCP 或 Unix 通訊端的方式相同 (視您叫用 Proxy 的方式而定):

TCP 通訊端

如果您使用 TCP 通訊端,Proxy 可做為本機主機:

127.0.0.1:5432

Unix 通訊端

如果您使用 Unix 通訊端,則可利用下列路徑來使用 Proxy:

<PROXY_PATH>/<INSTANCE_CONNECTION_NAME>
其中 PROXY_PATH 是您在啟動 Proxy 時使用 -dir 選項設定的目錄路徑。本說明文件中的範例使用 /cloudsql。您可以在 Google Cloud Platform 主控台的「Instance details」(執行個體詳細資料) 頁面,或是使用 <PROJECT-ID>:<REGION>:<INSTANCE_NAME> 找出執行個體的連線名稱。

需要協助嗎?如需針對 Proxy 進行疑難排解,請參閱 Cloud SQL Proxy 連線疑難排解一節。或者,請參閱我們的 Cloud SQL 支援頁面

特定程式語言的資訊和範例

任何可讓您連線至 Unix 或 TCP 通訊端的程式語言,都能用來連線至 Proxy。以下是幾個 Proxy 叫用和連線陳述式的範例,可協助您瞭解它們如何在應用程式中搭配運作。

Python

為求簡潔,以下的 Proxy 叫用陳述式使用本機 Cloud SDK 驗證;您的叫用陳述式可能會與範例不同,全視您的驗證方式和執行個體的指定方式而定。 瞭解詳情

Psycopg2 與 TCP

叫用 Proxy:

./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432 &

連線陳述式:

import psycopg2
conn = psycopg2.connect(user=<USER>, password=<PASSWORD>,
                        host='localhost', port='5432')

Psycopg2 與 Unix

叫用 Proxy:

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

連線陳述式:

import psycopg2
conn = psycopg2.connect(user=<USER>, password=<PASSWORD>,
                        host='/cloudsql/<INSTANCE_CONNECTION_NAME>')

SQLAlchemy 與 TCP

叫用 Proxy:

./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432 &

連線陳述式:

from sqlalchemy import create_engine
engine = create_engine('postgresql+psycopg2://<USER>:<PASSWORD>@localhost:5432/')

SQLAlchemy 與 Unix

叫用 Proxy:

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

連線陳述式:

from sqlalchemy import create_engine
engine = create_engine('postgresql+psycopg2://<USER>:<PASSWORD>@/?host=/cloudsql/<INSTANCE_CONNECTION_NAME>')

Java

Java 程式設計語言不提供 Unix 通訊端原生支援。 您可以使用提供 Unix 通訊端支援的 TCP 通訊端或程式庫搭配使用 Cloud SQL Proxy,但在不將 IP 位址加入許可清單的情況下,連結 PostgreSQL 執行個體的最簡單方式是使用 JDBC 通訊端處理站。

JDBC 通訊端處理站可以做為用戶端 Proxy 軟體的替代方案,您必須啟用 Cloud SQL API,就像啟用 Cloud SQL Proxy 一樣。通訊端處理站提供的加密層級與 Proxy 相同,且會使用 Cloud SDK 憑證進行驗證,所以必須安裝和驗證 Cloud SDK。

如需程式碼範例,請參閱 Cloud SQL Socket Factory for JDBC drivers。相關操作說明請查看 README 檔案。

Go

您可以透過下列兩種方式使用 Cloud SQL Proxy 與 Go 程式設計語言:

  • Go Proxy 程式庫
  • 隨附程序
Go Proxy 程式庫

程式庫是從 Go 程式使用 Proxy 的最簡單方式,原因是您不需要以 Proxy 本身的程序明確啟動 Proxy。

import (
    "github.com/GoogleCloudPlatform/cloudsql-proxy/proxy/dialers/postgres"
)
...
dsn := fmt.Sprintf("host=%s dbname=%s user=%s password=%s sslmode=disable",
                   <INSTANCE_CONNECTION_NAME>,
                   <DATABASE_NAME>,
                   <DATABASE_USER>,
                   <PASSWORD>)
db, err := sql.Open("cloudsqlpostgres", dsn)

詳情請參閱 Cloud SQL Proxy GitHub 頁面

隨附程序

您也可以將 Proxy 當成一個隨附程序執行,然後從應用程式連線至 Proxy。

為求簡潔,以下的 Proxy 叫用陳述式使用本機 Cloud SDK 驗證;您的叫用陳述式可能會與範例不同,全視您的驗證方式和執行個體的指定方式而定。 瞭解詳情

TCP

Proxy 叫用陳述式:

./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432 &

連線陳述式:

import (
       "database/sql"
        _ "github.com/lib/pq"
)

dsn := fmt.Sprintf("host=localhost port=5432 user=%s password=%s dbname=%s sslmode=disable",
       dbUser,
       dbPassword,
       dbName)
db, err := sql.Open("postgres", dsn)

Unix 通訊端

Proxy 叫用陳述式:

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

連線陳述式:

import (
       "database/sql"
        _ "github.com/lib/pq"
)

dsn := fmt.Sprintf("host=/cloudsql/%s user=%s password=%s dbname=%s sslmode=disable",
       INSTANCE_CONNECTION_NAME,
       dbUser,
       dbPassword,
       dbName)
db, err := sql.Open("postgres", dsn)

設定公開 IP 連線的存取權

您可以將 Cloud SQL 執行個體的存取權授予任何應用程式,方法是針對應用程式用來連線的公開 IP 位址進行授權

您無法將私人網路 (例如 10.x.x.x) 指定為已授權的網路。

PostgreSQL 執行個體僅支援 IPv4 位址,系統會自動使用靜態 IP 位址設定這些執行個體。

如何設定 IP 連線的存取權:

主控台

  1. 確認應用程式的 IP 位址。 瞭解詳情。
  2. 授權應用程式用來連線至執行個體的 IP 位址。

    詳情請參閱新增已授權位址

  3. 如需指派給執行個體的 IP 位址,請參閱相關的「執行個體詳細資料」頁面。這就是您應用程式的連線字串需要的值。

gcloud

  1. 確認用戶端機器的 IP 位址。 瞭解詳情。
  2. 授權應用程式用來連線至執行個體的 IP 位址。

    詳情請參閱新增已授權位址

  3. 擷取執行個體的 IP 位址:
    gcloud sql instances describe [INSTANCE_NAME]
    

    在輸出中,找出 ipAddress 欄位。這就是您應用程式的連線字串需要的值。

cURL

  1. 確認應用程式的 IP 位址。 瞭解詳情。
  2. 授權應用程式用來連線至執行個體的 IP 位址。

    詳情請參閱新增已授權位址

  3. 擷取執行個體的 IP 位址:
    ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"
    curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
           -X GET \
           https://www.googleapis.com/sql/v1beta4/projects/[PROJECT-ID]/instances/[INSTANCE_NAME]
    

    請記下 ipAddresses.ipAddress 的值,這就是您應用程式的連線字串需要的值。

需要協助嗎?如需針對 Proxy 進行疑難排解,請參閱 Cloud SQL Proxy 連線疑難排解一節。或者,請參閱我們的 Cloud SQL 支援頁面

搭配動態指派的 IP 位址設定應用程式的存取權

有些應用程式必須使用動態指派的 IP 位址或臨時 IP 位址連線至 Cloud SQL 執行個體。平台式服務 (PaaS) 應用程式就屬於這種情況。

在這種情況下,您必須使用 Cloud SQL Proxy

測試您的連線

您可以使用 psql 用戶端,測試您從本機環境建立連線的能力。詳情請參閱使用 IP 位址連線 psql 用戶端使用 Cloud SQL Proxy 連線 psql 用戶端

需要協助嗎?如需針對 Proxy 進行疑難排解,請參閱 Cloud SQL Proxy 連線疑難排解一節。或者,請參閱我們的 Cloud SQL 支援頁面

確認應用程式的 IP 位址

如要確認執行應用程式的電腦所使用的 IP 位址,以便您能夠授權該位址存取 Cloud SQL 執行個體,請使用下列一項選項:

  • 如果電腦並非位於 Proxy 後端,請登入電腦並使用這個連結確定電腦 IP 位址。
  • 如果電腦位於 Proxy 後端,請登入該電腦,並使用 whatismyipaddress.com 等工具或服務來確認電腦真正的 IP 位址。

後續步驟

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
PostgreSQL 適用的 Cloud SQL