En esta página, se explica cómo iniciar PGAdapter en Spanner. Para obtener más información sobre PGAdapter, consulta Acerca de PGAdapter. Para obtener el objeto binario de PGAdapter, consulta Obtén PGAdapter.
Puedes iniciar PGAdapter de las siguientes maneras:
- Como un proceso independiente
- Dentro de un contenedor de Docker
- En Cloud Run
- Usa PGAdapter como un proxy de sidecar (por ejemplo, en un clúster de Kubernetes)
- En proceso con tu aplicación de Java
- Usa el conector de PG de Spanner (
spgc) para ejecutar herramientas de línea de comandos de PostgreSQL
Antes de comenzar
Antes de iniciar PGAdapter, asegúrate de haberte autenticado con
una cuenta de usuario o de servicio en la máquina en la que se ejecutará
PGAdapter. Si usas una cuenta de servicio,
debes conocer la ubicación del archivo de claves JSON (el archivo de credenciales). Luego, puedes especificar la ruta de acceso de las credenciales con la opción -c de PGAdapter
o configurando la variable de entorno GOOGLE_APPLICATION_CREDENTIALS.
Para obtener más información, consulta las secciones siguientes:
Elige un método para ejecutar PGAdapter
Puedes iniciar PGAdapter como un proceso independiente, dentro de un contenedor de Docker,
en Cloud Run, en proceso con tu aplicación de Java o
con el conector de PG de Spanner (spgc). Cuando
inicias PGAdapter, especificas el proyecto, el ID de la instancia de Spanner
y la base de datos a la que te conectarás. También puedes especificar la ruta de acceso de un
archivo de credenciales con formato JSON (archivo de claves).
Independiente
Descarga PGAdapter con el siguiente comando.
wget https://storage.googleapis.com/pgadapter-jar-releases/pgadapter.tar.gz \ && tar -xzvf pgadapter.tar.gz
Inicia PGAdapter con el siguiente comando.
java -jar pgadapter.jar -p PROJECT_ID -i INSTANCE_ID -d DATABASE_ID \ -c CREDENTIALS_FILE_PATH \ ADDITIONAL_OPTIONS
Se requieren las siguientes opciones:
-
-p project_id - Es el ID del proyecto en el que se ejecuta la base de datos de Spanner.
-
-i instance_id - Es el ID de la instancia de Spanner.
-
-d database_ID - ID de la base de datos de Spanner a la que se conectará.
Las siguientes configuraciones son opcionales:
-r databaseRole=database_role- Es el rol de la base de datos que se usará para la sesión. Para obtener más información, consulta Autorización con PGAdapter.
-
-c credentials_file_path - : Es la ruta de acceso completa del archivo de claves que contiene las credenciales de la cuenta de servicio en formato JSON. Si no se establece esta opción, las credenciales
se leen de la ruta de acceso especificada por la
variable de entorno
GOOGLE_APPLICATION_CREDENTIALS.Para aprender a crear una cuenta de servicio y descargar un archivo de claves con formato JSON, consulta Crea una cuenta de servicio.
Asegúrate de otorgar a la cuenta de servicio las credenciales suficientes para acceder a la base de datos.
Puedes omitir esta opción si primero te autenticas con Google Cloud CLI con el siguiente comando:
gcloud auth application-default loginPara obtener más información, consulta Configura la autenticación y la autorización.
-
-s port - Puerto en el que PGAdapter escucha. El valor predeterminado es 5432 (el puerto predeterminado de PostgreSQL).
-
-v version_number -
Es el número de versión de PostgreSQL que se expondrá al cliente durante la conexión. El valor predeterminado es 14.1.
Algunas aplicaciones y controladores de PostgreSQL habilitan funciones adicionales según este número de versión. Es posible que Spanner no admita estas funciones. Consulta Controladores y clientes para obtener una lista completa de los clientes compatibles.
-
-x -
Habilita las conexiones desde hosts que no sean localhost. No lo uses cuando inicies PGAdapter en modo independiente. Úsala solo cuando inicies dentro de un contenedor de Docker.
De forma predeterminada, como medida de seguridad, PGAdapter solo acepta conexiones de localhost.
En el siguiente ejemplo, se inicia PGAdapter en modo independiente en el puerto 5432 con las credenciales predeterminadas de la aplicación.
java -jar pgadapter.jar \ -p my-project \ -i my-instance \ -d my-database \ -s 5432
Docker
Inicia PGAdapter con el siguiente comando.
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
Además de las opciones de PGAdapter para especificar el proyecto, la instancia, la base de datos y las credenciales, se requieren las siguientes opciones:
-
-p 127.0.0.1:HOST-PORT:DOCKER-PORT -
Esta opción de Docker asigna el puerto
DOCKER-PORTdentro del contenedor de Docker al puertoHOST-PORTfuera del contenedor.DOCKER-PORTdebe coincidir con la forma en que se configura PGAdapter dentro del contenedor. El valor predeterminado es 5432.HOST-PORTes el puerto en el que Docker debe escuchar fuera del contenedor las solicitudes de conexión. Siempre debe ser un puerto disponible en localhost.Para obtener más información, consulta Publica o expón el puerto (-p, --expose) en la documentación de Docker.
-v CREDENTIALS_FILE_PATH:in_container_mount_point-
Esta opción de Docker activa un volumen compartido. Asigna la ruta de acceso del host fuera del contenedor a un volumen (punto de activación) dentro del contenedor. Las rutas de acceso de host y de contenedor están separadas por dos puntos (:).
Esta opción permite que PGAdapter acceda al archivo de credenciales JSON que está fuera del contenedor. En el ejemplo anterior, la opción
-chace referencia al punto de activación dentro del contenedor. En este ejemplo, se asigna el nombre/acct_credentials.jsonal punto de activación en el contenedor. Puedes asignarle el nombre que desees.Para obtener más información, consulta VOLUMEN (sistemas de archivos compartidos) VOLUMEN (sistemas de archivos compartidos) en la documentación de Docker.
-
-x -
Habilita las conexiones desde hosts que no sean localhost. Esto es necesario porque el puerto dentro del contenedor que se asigna al puerto del host no aparece en PGAdapter como localhost.
Las siguientes configuraciones son opcionales:
-r databaseRole=database_role- Es el rol de la base de datos que se usará para la sesión. Para obtener más información, consulta Autorización con PGAdapter.
En el siguiente ejemplo, el puerto de Docker y el puerto de host se configuran en el puerto predeterminado 5432 del servicio de base de datos de PostgreSQL.
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
No puedes implementar PGAdapter como un servicio independiente en Cloud Run, pero puedes implementarlo como un proxy de sidecar.
Se recomienda ejecutar PGAdapter en un patrón de archivo adicional en lugar de ejecutarlo como un servicio independiente por los siguientes motivos:- Evita un punto único de fallo. El acceso de cada aplicación a la base de datos es independiente de las demás, por lo que son más resistentes.
- La cantidad de instancias de PGAdapter escala de forma automática linealmente con la cantidad de instancias de la aplicación.
El repositorio de GitHub de PGAdapter contiene varias aplicaciones de ejemplo que funcionan con Cloud Run y PGAdapter como proxy sidecar para varios lenguajes de programación.
En el siguiente archivo de configuración, se muestra cómo agregar PGAdapter como un proxy de sidecar a Cloud Run:
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 sidecar
Puedes usar PGAdapter como un proxy de sidecar, por ejemplo, en un clúster de Kubernetes. Los contenedores sidecar de Kubernetes se ejecutan en paralelo con el contenedor principal en el Pod.
Se recomienda ejecutar PGAdapter en un patrón de archivo adicional en lugar de ejecutarlo como un servicio independiente por los siguientes motivos:
- Evita un punto único de fallo. El acceso de cada aplicación a la base de datos es independiente de las demás, por lo que es más resistente.
- Debido a que PGAdapter consume recursos en una relación lineal con el uso, este patrón te permite definir el alcance y solicitar recursos con mayor precisión para que se ajusten a las aplicaciones a medida que se realiza el escalamiento.
En el siguiente archivo de configuración, se muestra cómo agregar PGAdapter como un proxy de sidecar a tu clúster de Kubernetes:
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"
El repositorio de GitHub de PGAdapter contiene una guía paso a paso y una aplicación de ejemplo. En este ejemplo, se incluyen instrucciones para usar Workload Identity Federation for GKE con PGAdapter.
En proceso de Java
Crea e inicia una instancia de PGAdapter con tu código de Java. Esta es la configuración recomendada para las aplicaciones de Java.
Si usas una cuenta de servicio para la autenticación, asegúrate de que
la variable de entorno GOOGLE_APPLICATION_CREDENTIALS
esté configurada en la ruta del archivo de credenciales.
-
Agrega
google-cloud-spanner-pgadaptercomo dependencia a tu proyecto. Para obtener más información, consulta Obtén PGAdapter. - Compila un servidor con la clase
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);
}El repositorio de GitHub de PGAdapter contiene una aplicación de ejemplo completa.
Conector de Spanner para PostgreSQL (spgc)
spanner-pg-connector (con el alias spgc) es un
wrapper de CLI independiente para ejecutar herramientas de línea de comandos de PostgreSQL
(como psql o pg_dump) en
Spanner. Agrupa PGAdapter y un entorno de ejecución de Java mínimo, por lo que no necesitas tener Java ni Docker instalados de forma local. Cuando ejecutas un
comando, spgc inicia PGAdapter en segundo plano en un
puerto localhost asignado de forma dinámica y establece
PGHOST y PGPORT. Luego, ejecuta el comando del cliente de PostgreSQL y detiene PGAdapter cuando se cierra el comando.
Instala spgc con la secuencia de comandos del instalador
De forma predeterminada, el instalador descarga la versión más reciente en
~/.spanner-pg-connector y agrega ese directorio a tu
PATH.
Para instalar spgc en Linux (x86_64) o macOS
(aarch64 o x86_64), ejecuta el siguiente
comando:
curl -fsSL https://raw.githubusercontent.com/GoogleCloudPlatform/pgadapter/postgresql-dialect/spanner-pg-connector/install.sh | sh
Para instalar spgc en Windows (x86_64, PowerShell),
ejecuta el siguiente comando:
irm https://raw.githubusercontent.com/GoogleCloudPlatform/pgadapter/postgresql-dialect/spanner-pg-connector/install.ps1 | iex
Para personalizar la instalación en Linux o macOS con VERSION
y INSTALL_DIR, ejecuta el siguiente comando:
curl -fsSL https://raw.githubusercontent.com/GoogleCloudPlatform/pgadapter/postgresql-dialect/spanner-pg-connector/install.sh \ | VERSION=VERSION INSTALL_DIR="INSTALL_DIR" sh
Para personalizar la instalación en Windows (PowerShell) con
VERSION y INSTALL_DIR, ejecuta el siguiente
comando:
$env:VERSION = "VERSION"; $env:INSTALL_DIR = "INSTALL_DIR"; irm https://raw.githubusercontent.com/GoogleCloudPlatform/pgadapter/postgresql-dialect/spanner-pg-connector/install.ps1 | iex
Instala spgc de forma manual (sin la secuencia de comandos del instalador)
También puedes descargar y extraer el archivo de la versión directamente desde
Artifact Registry y, luego, agregar el directorio extraído a tu PATH.
El archivo incluye spanner-pg-connector y spgc.
Para instalar spgc de forma manual en Linux o macOS, ejecuta los siguientes
comandos (establece PLATFORM en linux-x64,
mac-aarch64 o 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"
Para instalar spgc de forma manual en Windows (PowerShell), ejecuta los
siguientes comandos:
$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"
Para mantener spgc en tu PATH en todas las sesiones de terminal, agrega el directorio de instalación a tu perfil de shell (como
~/.bashrc o ~/.zshrc en Linux y macOS) o a la variable de entorno
Path del usuario en Windows.
Para verificar la instalación, comprueba la versión de spgc:
spgc --versionAutenticación
spgc no requiere un nombre de usuario ni una contraseña de PostgreSQL entre la herramienta cliente y el proxy de PGAdapter local. Para
autenticarte en Spanner, spgc usa
Google Cloud
credenciales predeterminadas de la aplicación (ADC)
en el siguiente orden:
- Variable de entorno
GOOGLE_APPLICATION_CREDENTIALS: Apunta a una clave de cuenta de servicio o a un archivo JSON de credenciales. - Credenciales de usuario de Google Cloud CLI: Ejecuta
gcloud auth application-default loginpara configurar estas credenciales. - Cuenta de servicio adjunta:
spgcusa la cuenta de servicio adjunta cuando la ejecutas en entornos de Google Cloud , como Compute Engine, Cloud Shell, Cloud Workstations, Cloud Run o la federación de identidades para cargas de trabajo para GKE.
Cuando te conectas al
emulador de Spanner
(SPANNER_EMULATOR_HOST), spgc inhabilita
la autenticación.
Uso y variables de entorno
Pasa el comando del cliente y sus argumentos directamente a spgc
(o spanner-pg-connector):
spgc psql -d "projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID"
También puedes configurar el proyecto, la instancia, la base de datos predeterminada o el emulador con variables de entorno:
GOOGLE_CLOUD_PROJECT- Es el ID del proyecto deGoogle Cloud .
SPANNER_INSTANCE- Es el ID de la instancia de Spanner.
SPANNER_DATABASE- ID de la base de datos de Spanner predeterminada.
spgcusa este valor si el comando no especifica-d,--dbnameni--database. SPANNER_EMULATOR_HOST- Si se establece, se conecta al emulador de Spanner en
HOST:PORT(por ejemplo,localhost:9010) en lugar de Spanner. Anula la configuración de esta variable cuando te conectes a Spanner. GOOGLE_APPLICATION_CREDENTIALS- Ruta de acceso opcional a un archivo JSON de credenciales de Google Cloud .
En los siguientes ejemplos, se muestra cómo ejecutar spgc con variables de entorno:
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
Orientación sobre la asignación de recursos para el proxy de sidecar de PGAdapter
Los siguientes lineamientos pueden ayudarte a configurar los recursos de CPU y memoria para el proxy de sidecar de PGAdapter. Los valores óptimos varían según tu carga de trabajo específica.
Memoria
Debido a que PGAdapter no almacena en caché muchos datos, requiere memoria para convertir los resultados de la consulta del formato gRPC de Spanner al formato del protocolo de conexión de PostgreSQL. Esto es especialmente relevante para las cargas de trabajo con columnas binarias grandes, ya que Spanner y PostgreSQL manejan estos tipos de datos de manera diferente.
Para determinar cuánta memoria asignar, usa la siguiente fórmula de asignación de memoria, en la que <var>number of concurrent connections</var> es la cantidad de
conexiones simultáneas que controla tu aplicación:
384 MB + (2 MB * number of concurrent connections)
Por ejemplo, si tu aplicación controla 200 conexiones simultáneas, asigna aproximadamente 784 MB de memoria:
384 MB + (2 MB * 200) = 784 MB
Comienza con esta asignación de memoria de referencia. Supervisa su uso con una carga realista para ajustar el valor según tus necesidades específicas.
CPU
PGAdapter no hace un uso intensivo de la CPU. Esto se debe a que su función principal es actuar como un proxy de transferencia. Sin embargo, el uso de CPU aumenta con la cantidad de datos que se envían y reciben.
Ten en cuenta los siguientes factores cuando asignes CPU:
- Carga de trabajo: Las aplicaciones que ejecutan consultas que devuelven grandes cantidades de datos requieren más potencia de CPU por conexión que las que devuelven solo unas pocas filas y columnas.
- Patrón de acceso de la aplicación: Si tu aplicación accede a Spanner de forma síncrona, estará inactiva mientras espera los datos del proxy. En este caso, es menos probable que la aplicación y el proxy compitan por los recursos de CPU.
Comienza con una asignación de CPU de referencia. Supervisa su uso con una carga realista para ajustar el valor según tus necesidades específicas.
¿Qué sigue?
- Conecta
psqla una base de datos de PostgreSQL. - Conecta
JDBCa una base de datos de PostgreSQL. - Conecta
pgxa una base de datos de PostgreSQL. - Conecta
psycopg2a una base de datos de PostgreSQL. - Conecta
psycopg3a una base de datos de PostgreSQL. - Conecta
node-postgresa una base de datos de PostgreSQL. - Consulta una descripción general de los controladores y los ORM compatibles con Spanner