使用 Cloud SQL Proxy Docker 映像檔連結 psql 用戶端

這個頁面說明如何使用 Cloud SQL Proxy Docker 映像檔,從執行 Linux 或 Compute Engine Linux 執行個體的本機機器將 psql 用戶端連線至 Cloud SQL 執行個體。

事前準備

您必須做好以下準備:

使用 Proxy Docker 映像檔連結 psql 用戶端

使用 Proxy Docker 映像檔進行連結:

  1. 啟用Cloud SQL Admin API。

    啟用 API

  2. 如果您正在使用 Compute Engine 執行個體,請做好執行個體的相關準備:
    1. 顯示 Compute Engine 執行個體屬性:
      gcloud compute instances describe [GCE_INSTANCE_NAME]
    2. 驗證在執行個體上啟用的範圍。

      驗證使用範圍需要下列兩個範圍:

      • https://www.googleapis.com/auth/sqlservice.admin
      • https://www.googleapis.com/auth/devstorage.read_write

      或者,https://www.googleapis.com/auth/cloud-platform 範圍啟用了所有 Google Cloud Platform API。

      如果您的 Compute Engine 執行個體沒有正確的範圍,您可以更新使執行個體包含這些範圍。如需詳細資訊,請參閱 Compute Engine 說明文件

    3.     使用連線至 Linux 執行個體的說明,開啟執行個體的終端機連線。
  3. 若尚未在 Compute Engine 執行個體或用戶端機器上安裝 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
    

    其他平台

    1. PostgreSQL 下載頁面下載您的平台適用的 PostgreSQL Core Distribution。
      Core Distribution 中包含 psql 用戶端。
    2. 依照下載頁面的說明安裝 PostgreSQL 資料庫。
  4. 如有需要,請安裝 Docker 用戶端
    curl https://get.docker.com | sh
    sudo usermod -aG docker $USER
    

    如果您正在使用將容器最佳化的 Compute Engine 執行個體,即表示已經安裝 Docker 用戶端。

  5. Google Container Registry 安裝 Proxy Docker 映像檔。
    docker pull gcr.io/cloudsql-docker/gce-proxy:1.12
  6. 如果您正在本機機器上執行 Proxy Docker 影像檔 (非 Compute Engine 執行個體),或者您的 Compute Engine 執行個體沒有正確的範圍,請建立 Google Cloud Platform 服務帳戶。
    1. 前往 Google Cloud Platform 主控台的「Service accounts」(服務帳戶) 頁面。

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

    2. 如有需要,請選取包含您的 Cloud SQL 執行個體的專案。
    3. 按一下 [Create service account] (建立服務帳戶)。
    4. 在「Create service account」(建立服務帳戶) 對話方塊中,提供服務帳戶的描述性名稱。
    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. 將「服務帳戶 ID」變更為您可以辨識的唯一值,使您日後能夠在有需要的情況下輕鬆找到這個服務帳戶。
    7. 按一下 [Furnish a new private key] (提供一組新的私密金鑰)
    8. 預設金鑰類型為 JSON,這是要使用的正確值。
    9. 按一下 [Create] (建立)

      私密金鑰檔案就會下載到您的機器。您可以將它移到其他位置。請保證金鑰檔案的安全。

    當您啟動 Proxy 時,您會將金鑰的路徑提供為「PATH_TO_KEY_FILE」。

  7. 前往 Google Cloud Platform 主控台的「Cloud SQL 執行個體」頁面。

    前往 Cloud SQL 執行個體頁面

  8. 選取執行個體以開啟它的「Instance details」(執行個體詳細資料) 頁面,並複製「執行個體連線名稱」。

    例如:myinstance:us-central1:myproject

  9. 啟動 Proxy。

    根據您的語言與環境,您可以使用 TCP 通訊端或 Unix 通訊端啟動 Proxy。以 Java 程式設計語言編寫的應用程式或 Windows 環境都不支援 Unix 通訊端。

    TCP 通訊端

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

    如果您要使用 Compute Engine 執行個體提供的憑證,請勿加入 credential_file 參數與 -v <PATH_TO_KEY_FILE>:/config 這一行指令列。

    請一律在 -p 中指定 127.0.0.1 前置字串,以防 Proxy 暴露到本機主機之外。執行個體參數中必須要有「0.0.0.0」,才能讓 Docker 容器以外的環境存取連接埠。

    Unix 通訊端

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

    如果您要使用 Compute Engine 執行個體提供的憑證,請勿加入 credential_file 參數與 -v <PATH_TO_KEY_FILE>:/config 這一行指令列。

    如果您要使用將容器最佳化的映像檔,請使用可寫入的目錄來取代 /cloudsql,例如:

    -v /mnt/stateful_partition/cloudsql:/cloudsql

    您可以指定多個執行個體,並以半形逗號分隔。您也可以使用 Compute Engine 中繼資料來動態決定要連線的目標執行個體。 進一步瞭解 Proxy 參數。

  10. 啟動用戶端:

    您使用的連線字串取決於您是使用 TCP 通訊端還是 UNIX 通訊端啟動 Proxy。

    TCP 通訊端

    1. 啟動 psql 用戶端:
      psql "host=127.0.0.1 sslmode=disable dbname=<DB_NAME> user=<USER_NAME>"
      

      即使 sslmode 參數設定為 disable,Proxy 也會提供加密的連線。

      當您使用 TCP 通訊端連線時,可透過 127.0.0.1 存取 Proxy。

    2. 輸入密碼。
    3. 您應該會看到 psql 提示。

    Unix 通訊端

    1. 啟動 psql 用戶端:
      psql "sslmode=disable host=/cloudsql/<INSTANCE_CONNECTION_NAME> user=<USERNAME>"
      

      即使 sslmode 參數設定為 disable,Proxy 也會提供加密的連線。

    2. 輸入密碼。
    3. 您應該會看到 psql 提示。

需要協助嗎?如需疑難排解 Proxy 的說明,請參閱疑難排解 Cloud SQL Proxy 連線。 或者,請參閱我們的 Cloud SQL 支援頁面

將 Proxy Docker 映像檔保持在最新狀態

Proxy Docker 映像檔以 Cloud SQL Proxy 的特定版本為基礎。 當 Cloud SQL Proxy 推出新版本時,您應提取 Proxy Docker 映像檔的新版本,以將您的環境保持在最新狀態。您可以檢查 Cloud SQL Proxy GitHub 版本頁面查看 Cloud SQL Proxy 的目前版本。 Google Groups Cloud SQL 公告論壇中也會註記未來 Proxy 版本。

後續步驟

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

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

這個網頁
PostgreSQL 適用的 Cloud SQL