Inicia PGAdapter

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 login

Para 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-PORT dentro del contenedor de Docker al puerto HOST-PORT fuera del contenedor. DOCKER-PORT debe coincidir con la forma en que se configura PGAdapter dentro del contenedor. El valor predeterminado es 5432. HOST-PORT es 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 -c hace referencia al punto de activación dentro del contenedor. En este ejemplo, se asigna el nombre /acct_credentials.json al 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.

  1. Agrega google-cloud-spanner-pgadapter como dependencia a tu proyecto. Para obtener más información, consulta Obtén PGAdapter.
  2. Compila un servidor con la clase 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);
    }

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

Autenticació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:

  1. Variable de entorno GOOGLE_APPLICATION_CREDENTIALS: Apunta a una clave de cuenta de servicio o a un archivo JSON de credenciales.
  2. Credenciales de usuario de Google Cloud CLI: Ejecuta gcloud auth application-default login para configurar estas credenciales.
  3. Cuenta de servicio adjunta: spgc usa 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. spgc usa este valor si el comando no especifica -d, --dbname ni --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?