本頁說明如何在 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 環境變數已設為憑證檔案的路徑。
-
將
google-cloud-spanner-pgadapter新增為專案的依附元件。詳情請參閱「取得 PGAdapter」。 - 使用
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 存放區包含完整的範例應用程式。
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):
GOOGLE_APPLICATION_CREDENTIALS環境變數:指向服務帳戶金鑰或憑證 JSON 檔案。- Google Cloud CLI 的使用者憑證:執行
gcloud auth application-default login即可設定這些憑證。 - 附加的服務帳戶:在 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 分配開始。在實際負載下監控用量,根據特定需求微調值。