啟動 PGAdapter

本頁說明如何在 Spanner 啟動 PGAdapter。如要瞭解 PGAdapter,請參閱「關於 PGAdapter」。如要取得 PGAdapter 二進位檔,請參閱「取得 PGAdapter」。

您可以透過下列方式啟動 PGAdapter:

  • 做為獨立程序
  • 在 Docker 容器中
  • 在 Cloud Run
  • 將 PGAdapter 做為 Sidecar Proxy 使用 (例如在 Kubernetes 叢集中)
  • 與 Java 應用程式在同一個程序中
  • 使用 Spanner PG 連接器 (spgc) 執行 PostgreSQL 指令列工具

事前準備

啟動 PGAdapter 之前,請務必在要執行 PGAdapter 的機器上,使用使用者帳戶或服務帳戶完成驗證。如果您使用服務帳戶,則必須知道 JSON 金鑰檔案 (憑證檔案) 的位置。接著,您可以使用 PGAdapter -c 選項,或設定 GOOGLE_APPLICATION_CREDENTIALS 環境變數,指定憑證路徑。

如需詳細資訊,請參閱:

選擇執行 PGAdapter 的方法

您可以在 Docker 容器、Cloud Run、Java 應用程式內,或使用 Spanner PG 連接器 (spgc),將 PGAdapter 做為獨立程序啟動。啟動 PGAdapter 時,請指定要連線的專案、Spanner 執行個體 ID 和資料庫。您也可以指定 JSON 格式憑證檔案 (金鑰檔案) 的路徑。

獨立式

使用下列指令下載 PGAdapter。

    wget https://storage.googleapis.com/pgadapter-jar-releases/pgadapter.tar.gz \
    && tar -xzvf pgadapter.tar.gz
    

使用下列指令啟動 PGAdapter。

    java -jar pgadapter.jar -p PROJECT_ID -i INSTANCE_ID -d DATABASE_ID \
    -c CREDENTIALS_FILE_PATH \
    ADDITIONAL_OPTIONS
    

必須提供下列選項:

-p project_id
執行 Spanner 資料庫的專案 ID。
-i instance_id
Spanner 執行個體 ID。
-d database_ID
要連線的 Spanner 資料庫 ID。

以下為選用選項:

-r databaseRole=database_role
工作階段要使用的資料庫角色。詳情請參閱「使用 PGAdapter 授權」。
-c credentials_file_path
:金鑰檔案的完整路徑,其中包含 JSON 格式的服務帳戶憑證。如未設定這個選項,系統會從 GOOGLE_APPLICATION_CREDENTIALS 環境變數指定的路徑讀取憑證。

如要瞭解如何建立服務帳戶及下載 JSON 格式的金鑰檔案,請參閱「建立服務帳戶」。

請務必授予服務帳戶足夠的憑證,以便存取資料庫。

如果您先使用下列指令,透過 Google Cloud CLI 進行驗證,則可省略這個選項:

gcloud auth application-default login

詳情請參閱「設定驗證和授權」。

-s port
:PGAdapter 監聽的通訊埠。預設值為 5432 (預設 PostgreSQL 通訊埠)。
-v version_number

連線期間向用戶端公開的 PostgreSQL 版本號碼。預設值為 14.1

部分 PostgreSQL 應用程式和驅動程式會根據這個版本號碼啟用額外功能。Spanner 可能不支援這些功能。如需支援用戶端的完整清單,請參閱「驅動程式和用戶端」。

-x

啟用 localhost 以外主機的連線。以獨立模式啟動 PGAdapter 時,請勿使用此選項。僅在 Docker 容器中啟動時使用。

根據預設,PGAdapter 只接受來自 localhost 的連線,這是一項安全措施。

下列範例會使用預設應用程式憑證,在通訊埠 5432 上以獨立模式啟動 PGAdapter。

java -jar pgadapter.jar \
-p my-project \
-i my-instance \
-d my-database \
-s 5432

Docker

使用下列指令啟動 PGAdapter。

docker run -d -p HOST-PORT:DOCKER-PORT \
-v CREDENTIALS_FILE_PATH:/acct_credentials.json \
gcr.io/cloud-spanner-pg-adapter/pgadapter:latest \
-p PROJECT_ID -i INSTANCE_ID -d DATABASE_ID  \
-c /acct_credentials.json -x OTHER_PGAdapter_OPTIONS

除了指定專案、執行個體、資料庫和憑證的 PGAdapter 選項外,還必須指定下列選項:

-p 127.0.0.1:HOST-PORT:DOCKER-PORT

這個 Docker 選項會將 Docker 容器內的通訊埠 DOCKER-PORT 對應至容器外的通訊埠 HOST-PORT。DOCKER-PORT 必須與容器內 PGAdapter 的設定方式相符。預設值為 5432。HOST-PORT 是 Docker 應在容器外監聽連線要求的通訊埠。這個通訊埠必須一律是 localhost 上的可用通訊埠。

詳情請參閱 Docker 說明文件中的「發布或公開通訊埠 (-p, --expose)」一節。

-v CREDENTIALS_FILE_PATH:in_container_mount_point

這個 Docker 選項會繫結掛接共用磁碟區。這項設定會將容器外的主機路徑對應至容器內的磁碟區 (掛接點)。主機和容器路徑會以半形冒號 (:) 分隔。

這個選項可讓 PGAdapter 存取容器外的 JSON 憑證檔案。在上述範例中,-c 選項會參照容器內掛接點。在這個範例中,容器內掛接點的名稱為 /acct_credentials.json。命名方式不限。

詳情請參閱 Docker 說明文件中的「VOLUME (共用檔案系統)」。

-x

啟用 localhost 以外主機的連線。這是因為對應至主機通訊埠的容器內部通訊埠不會顯示為 PGAdapter 的 localhost。

以下為選用選項:

-r databaseRole=database_role
工作階段要使用的資料庫角色。詳情請參閱「使用 PGAdapter 授權」。

在以下範例中,Docker 通訊埠和主機通訊埠都設為 PostgreSQL 資料庫服務預設通訊埠 5432。

docker run -d -p 127.0.0.1:5432:5432 \
-v /tmp/credentials.json:/acct_credentials.json \
gcr.io/cloud-spanner-pg-adapter/pgadapter:latest \
-p my_project -i my_instance -d my_database \
-c /acct_credentials.json -x

Cloud Run

您無法在 Cloud Run 將 PGAdapter 部署為獨立服務,但可以部署為 Sidecar Proxy。

建議以 sidecar 模式執行 PGAdapter,而非做為獨立服務執行,原因如下:
  • 避免單點故障。每個應用程式對資料庫的存取權都各自獨立,因此更具彈性。
  • PGAdapter 執行個體數量會隨著應用程式執行個體數量線性自動調度。

PGAdapter GitHub 存放區包含多個使用 Cloud Run 和 PGAdapter 做為 Sidecar Proxy 的工作範例應用程式,適用於各種程式設計語言。

下列設定檔說明如何將 PGAdapter 新增為 Cloud Run 的 Sidecar Proxy:

  apiVersion: serving.knative.dev/v1
  kind: Service
  metadata:
  annotations:
    # This example uses an in-memory volume for Unix domain sockets.
    # This is a Cloud Run beta feature.
    run.googleapis.com/launch-stage: BETA
  name: pgadapter-sidecar-example
  spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/execution-environment: gen1
        # This registers 'pgadapter' as a dependency of 'app' and ensures that pgadapter starts
        # before the app container.
        run.googleapis.com/container-dependencies: '{"app":["pgadapter"]}'
    spec:
      # Create an in-memory volume that can be used for Unix domain sockets.
      volumes:
        - name: sockets-dir
          emptyDir:
            # This directory contains the virtual socket files that are used to
            # communicate between your application and PGAdapter.
            sizeLimit: 50Mi
            medium: Memory
      containers:
        # This is the main application container.
        - name: app
          # Example: europe-north1-docker.pkg.dev/my-test-project/cloud-run-source-deploy/pgadapter-sidecar-example
          image: MY-REGION.pkg.dev/MY-PROJECT/cloud-run-source-deploy/pgadapter-sidecar-example
          # The PGADAPTER_HOST variable is set to point to /sockets, which is the shared in-memory
          # volume that is used for Unix domain sockets.
          env:
            - name: SPANNER_PROJECT
              value: my-project
            - name: SPANNER_INSTANCE
              value: my-instance
            - name: SPANNER_DATABASE
              value: my-database
            - name: PGADAPTER_HOST
              value: /sockets
            - name: PGADAPTER_PORT
              value: "5432"
          ports:
            - containerPort: 8080
          volumeMounts:
            - mountPath: /sockets
              name: sockets-dir
        # This is the PGAdapter sidecar container.
        - name: pgadapter
          image: gcr.io/cloud-spanner-pg-adapter/pgadapter
          volumeMounts:
            - mountPath: /sockets
              name: sockets-dir
          args:
            - -dir /sockets
            - -x
          # Add a startup probe that checks that PGAdapter is listening on port 5432.
          startupProbe:
            initialDelaySeconds: 10
            timeoutSeconds: 10
            periodSeconds: 10
            failureThreshold: 3
            tcpSocket:
              port: 5432
  

Sidecar Proxy

您可以在 Kubernetes 叢集等環境中,將 PGAdapter 做為 Sidecar Proxy 使用。Kubernetes 邊車容器會與 Pod 中的主要容器並行運作。

建議以 sidecar 模式執行 PGAdapter,而非做為獨立服務執行,原因如下:

  • 避免單點故障。每個應用程式對資料庫的存取權都彼此獨立,因此更具彈性。
  • 由於 PGAdapter 耗用的資源與用量呈線性關係,因此這種模式可讓您更準確地界定及要求資源,以配合應用程式的擴充。

下列設定檔說明如何將 PGAdapter 新增為 Kubernetes 叢集的 Sidecar Proxy:

containers:
- name: pgadapter
image: gcr.io/cloud-spanner-pg-adapter/pgadapter
ports:
  - containerPort: 5432
args:
  - "-p my-project"
  - "-i my-instance"
  - "-d my-database"
  - "-x"
resources:
  requests:
    # PGAdapter's memory use scales linearly with the number of active
    # connections. Fewer open connections will use less memory. Adjust
    # this value based on your application's requirements.
    memory: "512Mi"
    # PGAdapter's CPU use scales linearly with the amount of IO between
    # the database and the application. Adjust this value based on your
    # application's requirements.
    cpu: "1"

PGAdapter GitHub 存放區提供逐步指南和範例應用程式。這個範例包含如何搭配使用 Workload Identity Federation for GKE 與 PGAdapter 的操作說明。

Java 內建程序

使用 Java 程式碼建立並啟動 PGAdapter 執行個體。這是 Java 應用程式的建議設定。

如果您使用服務帳戶進行驗證,請確認 GOOGLE_APPLICATION_CREDENTIALS 環境變數已設為憑證檔案的路徑。

  1. 將 google-cloud-spanner-pgadapter 新增為專案的依附元件。詳情請參閱「取得 PGAdapter」。
  2. 使用 com.google.cloud.spanner.pgadapter.ProxyServer 類別建構伺服器。
  3. /**
    * Starts PGAdapter in-process and returns a reference to the server. Use this reference to
    * gracefully shut down the server when your application shuts down.
    *
    * @param project the Google Cloud project that PGAdapter should connect to
    * @param instance the Spanner instance that PGAdapter should connect to
    * @param credentialsFile the full path of a credentials file that PGAdapter should use, or 
    *     null if PGAdapter should use the application default credentials
    */
    static Server startPGAdapter(String project, String instance, String credentialsFile) {
    OptionsMetadata.Builder builder =
        OptionsMetadata.newBuilder()
            .setProject(project)
            .setInstance(instance)
            // Start PGAdapter on any available port.
            .setPort(0);
    if (credentialsFile != null) {
      builder.setCredentialsFile(credentialsFile);
    }
    ProxyServer server = new ProxyServer(builder.build());
    server.startServer();
    server.awaitRunning();
    
    return new PGAdapter(server);
    }

PGAdapter GitHub 存放區包含完整的範例應用程式。

Spanner PG 連接器 (spgc)

spanner-pg-connector (別名為 spgc) 是獨立的 CLI 包裝函式,用於對 Spanner 執行 PostgreSQL 指令列工具 (例如 psql 或 pg_dump)。其中包含 PGAdapter 和精簡版 Java 執行階段,因此您不必在本機安裝 Java 或 Docker。執行指令時,spgc 會在背景啟動 PGAdapter,並在動態指派的 localhost 通訊埠上設定 PGHOST 和 PGPORT。接著,系統會執行 PostgreSQL 用戶端指令,並在指令結束時停止 PGAdapter。

使用安裝程式指令碼安裝 spgc

根據預設,安裝程式會將最新版本下載到 ~/.spanner-pg-connector,並將該目錄新增至 PATH。

如要在 Linux (x86_64) 或 macOS (aarch64 或 x86_64) 上安裝 spgc,請執行下列指令:

curl -fsSL https://raw.githubusercontent.com/GoogleCloudPlatform/pgadapter/postgresql-dialect/spanner-pg-connector/install.sh | sh

如要在 Windows (x86_64、PowerShell) 上安裝 spgc,請執行下列指令:

irm https://raw.githubusercontent.com/GoogleCloudPlatform/pgadapter/postgresql-dialect/spanner-pg-connector/install.ps1 | iex

如要在 Linux 或 macOS 上使用 VERSION 和 INSTALL_DIR 自訂安裝,請執行下列指令:

curl -fsSL https://raw.githubusercontent.com/GoogleCloudPlatform/pgadapter/postgresql-dialect/spanner-pg-connector/install.sh \
  | VERSION=VERSION INSTALL_DIR="INSTALL_DIR" sh

如要使用 VERSION 和 INSTALL_DIR 自訂 Windows (PowerShell) 安裝作業,請執行下列指令:

$env:VERSION = "VERSION"; $env:INSTALL_DIR = "INSTALL_DIR"; irm https://raw.githubusercontent.com/GoogleCloudPlatform/pgadapter/postgresql-dialect/spanner-pg-connector/install.ps1 | iex

手動安裝 spgc (不使用安裝指令碼)

您也可以直接從 Artifact Registry 下載並擷取版本封存檔,然後將擷取的目錄新增至 PATH。封存檔包含 spanner-pg-connector 和 spgc。

如要在 Linux 或 macOS 上手動安裝 spgc,請執行下列指令 (將 PLATFORM 設為 linux-x64、mac-aarch64 或 mac-x64):

VERSION=VERSION
PLATFORM=PLATFORM # linux-x64, mac-aarch64, or mac-x64
INSTALL_DIR="INSTALL_DIR"
mkdir -p "${INSTALL_DIR}"
curl -fsSL "https://artifactregistry.googleapis.com/v1/projects/cloud-spanner-pg-adapter/locations/us/repositories/spanner-pg-connector/files/spanner-pg-connector:${VERSION}:spanner-pg-connector-${PLATFORM}.tar.gz:download?alt=media" \
  | tar -xz -C "${INSTALL_DIR}"
export PATH="${INSTALL_DIR}:$PATH"

如要在 Windows (PowerShell) 上手動安裝 spgc,請執行下列指令:

$Version = "VERSION"
$InstallDir = "INSTALL_DIR"
$ZipPath = Join-Path $env:TEMP "spanner-pg-connector-windows-x64.zip"
New-Item -ItemType Directory -Path $InstallDir -Force | Out-Null
Invoke-RestMethod -Uri "https://artifactregistry.googleapis.com/v1/projects/cloud-spanner-pg-adapter/locations/us/repositories/spanner-pg-connector/files/spanner-pg-connector:${Version}:spanner-pg-connector-windows-x64.zip:download?alt=media" -OutFile $ZipPath
Expand-Archive -Path $ZipPath -DestinationPath $InstallDir -Force
$env:PATH = "$env:PATH;$InstallDir"

如要在終端機工作階段中保留 PATH 上的 spgc,請將安裝目錄新增至殼層設定檔 (例如 Linux 和 macOS 上的 ~/.bashrc 或 ~/.zshrc),或 Windows 上的使用者 Path 環境變數。

如要驗證安裝,請檢查 spgc 版本:

spgc --version

驗證

spgc 不需要用戶端工具和本機 PGAdapter Proxy 之間的 PostgreSQL 使用者名稱或密碼。為向 Spanner 進行驗證,spgc 會依下列順序使用 Google Cloud應用程式預設憑證 (ADC):

  1. GOOGLE_APPLICATION_CREDENTIALS 環境變數:指向服務帳戶金鑰或憑證 JSON 檔案。
  2. Google Cloud CLI 的使用者憑證:執行 gcloud auth application-default login 即可設定這些憑證。
  3. 附加的服務帳戶:在 Compute Engine、Cloud Shell、Cloud Workstations、Cloud Run 或 Workload Identity Federation for GKE 等 Google Cloud 環境中執行 spgc 時,會使用附加的服務帳戶。

連線至 Spanner 模擬器 (SPANNER_EMULATOR_HOST) 時,spgc 會停用驗證功能。

用量和環境變數

將用戶端指令及其引數直接傳遞至 spgc (或 spanner-pg-connector):

spgc psql -d "projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID"

您也可以使用環境變數設定專案、執行個體、預設資料庫或模擬器:

GOOGLE_CLOUD_PROJECT
Google Cloud 專案 ID。
SPANNER_INSTANCE
Spanner 執行個體 ID。
SPANNER_DATABASE
預設 Spanner 資料庫 ID。如果指令未指定 -d、--dbname 或 --database,spgc 會使用這個值。
SPANNER_EMULATOR_HOST
如果設定,則會連線至 HOST:PORT 的 Spanner 模擬器 (例如 localhost:9010),而非 Spanner。連線至 Spanner 時,請取消設定這個變數。
GOOGLE_APPLICATION_CREDENTIALS
憑證 JSON 檔案的 Google Cloud 選用路徑。

以下範例說明如何使用環境變數執行 spgc:

export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export SPANNER_INSTANCE=INSTANCE_ID

# Start an interactive psql session
spgc psql -d DATABASE_ID

# Run a single query
spgc psql -d DATABASE_ID -c "SELECT 1"

# Connect to the Spanner emulator
SPANNER_EMULATOR_HOST=localhost:9010 spgc psql -d test-database

PGAdapter Sidecar Proxy 的資源分配指南

下列指南可協助您設定 PGAdapter Sidecar Proxy 的 CPU 和記憶體資源。最佳值會因特定工作負載而異。

記憶體

由於 PGAdapter 不會快取太多資料,因此需要記憶體,才能將查詢結果從 Spanner gRPC 格式轉換為 PostgreSQL 有線通訊協定格式。這對具有大型二進位資料欄的工作負載特別重要,因為 Spanner 和 PostgreSQL 處理這些資料類型的方式不同。

如要判斷應分配多少記憶體,請使用下列記憶體分配公式,其中 <var>number of concurrent connections</var> 是應用程式處理的並行連線數:

384 MB + (2 MB * number of concurrent connections)

舉例來說,如果應用程式會處理 200 個並行連線,請分配約 784 MB 的記憶體:

384 MB + (2 MB * 200) = 784 MB

請先從這個基準記憶體配置開始。請在實際負載下監控用量,並根據特定需求微調值。

CPU

PGAdapter 不會耗用大量 CPU 資源。這是因為其主要角色是做為傳遞 Proxy。不過,CPU 使用率會隨著傳送和接收的資料量增加而提高。

分配 CPU 時,請考量下列因素:

  • 工作負載:如果應用程式執行的查詢會傳回大量資料,則每個連線所需的 CPU 運算能力,會高於僅傳回幾列和幾欄資料的應用程式。
  • 應用程式存取模式:如果應用程式同步存取 Spanner,則在等待 Proxy 傳送資料時會處於閒置狀態。在這種情況下,應用程式和 Proxy 較不可能爭奪 CPU 資源。

先從基準 CPU 分配開始。在實際負載下監控用量,根據特定需求微調值。

後續步驟