啟動 PGAdapter

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

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

• 以獨立程序執行
• 在 Docker 容器中
• 在 Cloud Run 上
• 將 PGAdapter 做為補充 Proxy (例如在 Kubernetes 叢集中)
• 在 Java 應用程式中處理

事前準備

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

如需詳細資訊，請參閱：

• 向 Spanner 進行驗證
• 授權 gcloud CLI

選擇執行 PGAdapter 的方法

您可以將 PGAdapter 啟動為獨立程序、Docker 容器內、Cloud Run 上，或 Java 應用程式的程序內。啟動 PGAdapter 時，請指定要連線的專案、Spanner 執行個體和資料庫。您也可以指定 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_NAME -i INSTANCE_NAME -d DATABASE_NAME \
    -c CREDENTIALS_FILE_PATH \
    ADDITIONAL_OPTIONS
    

以下是必要選項：

-p project_name

Spanner 資料庫執行的專案名稱。

-i instance_name

Spanner 執行個體名稱。

-d database_name

要連線的資料庫名稱。

以下是選用選項：

-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 僅接受來自本機主機的連線，這是為了確保安全。

下列範例會使用預設應用程式憑證，在通訊埠 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_NAME -i INSTANCE_NAME -d DATABASE_NAME  \
-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 (shared filesystems)」。

-x

啟用來自 localhost 以外主機的連線。這是必要步驟，因為對應至主機通訊埠的容器內部通訊埠不會以本機主機的形式顯示在 PGAdapter 中。

以下是選用選項：

-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。

建議以補充資訊模式執行 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
  

補充 Proxy

舉例來說，您可以在 Kubernetes 叢集中使用 PGAdapter 做為 Sidecar Proxy。Kubernetes 輔助容器會與 Pod 中的主要容器平行執行。

建議您以補充資訊模式執行 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 存放區包含逐步指南和範例應用程式。 這個範例包含搭配 PGAdapter 使用 Workload Identity Federation for GKE 的操作說明。

Java 處理序內

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

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

1. 將 google-cloud-spanner-pgadapter 新增為專案的依附元件。詳情請參閱「取得 PGAdapter」。
2. 使用 com.google.cloud.spanner.pgadapter.ProxyServer 類別建構伺服器。

/**
* 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 存放區包含完整範例應用程式。

PGAdapter 補充 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 分配量著手。在實際負載下監控其用量，根據特定需求微調值。

後續步驟

• 連線 psql 至 PostgreSQL 資料庫
• 連線 JDBC 至 PostgreSQL 資料庫
• 連線 pgx 至 PostgreSQL 資料庫
• 連線 psycopg2 至 PostgreSQL 資料庫
• 連線 psycopg3 至 PostgreSQL 資料庫
• 連線 node-postgres 至 PostgreSQL 資料庫