Démarrer PGAdapter

Cette page explique comment démarrer PGAdapter dans Spanner. Pour en savoir plus sur PGAdapter, consultez la section À propos de PGAdapter. Pour obtenir le binaire PGAdapter, consultez la section Obtenir PGAdapter.

Vous pouvez démarrer PGAdapter de différentes manières:

• En tant que processus autonome
• Dans un conteneur Docker
• Sur Cloud Run
• Utiliser PGAdapter comme proxy side-car (par exemple, dans un cluster Kubernetes)
• Dans le processus avec votre application Java

Avant de commencer

Avant de démarrer PGAdapter, assurez-vous de vous être authentifié avec un compte utilisateur ou un compte de service sur la machine sur laquelle PGAdapter s'exécutera. Si vous utilisez un compte de service, vous devez connaître l'emplacement du fichier de clé JSON (fichier d'identifiants). Vous pouvez ensuite spécifier le chemin d'accès aux identifiants avec l'option -c de PGAdapter ou en définissant la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS.

Pour en savoir plus, consultez les pages suivantes :

• S'authentifier auprès de Spanner
• Autoriser la CLI gcloud

Choisir une méthode d'exécution de PGAdapter

Vous pouvez démarrer PGAdapter en tant que processus autonome, dans un conteneur Docker, sur Cloud Run ou en cours de traitement avec votre application Java. Lorsque vous démarrez PGAdapter, vous spécifiez le projet, l'instance Spanner et la base de données à laquelle vous souhaitez vous connecter. Vous pouvez également spécifier le chemin d'accès à un fichier d'identifiants au format JSON (fichier de clé).

Autonome

Téléchargez PGAdapter à l'aide de la commande suivante.

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

Démarrez PGAdapter avec la commande suivante.

    java -jar pgadapter.jar -p PROJECT_NAME -i INSTANCE_NAME -d DATABASE_NAME \
    -c CREDENTIALS_FILE_PATH \
    ADDITIONAL_OPTIONS
    

Les options suivantes sont requises :

-p project_name

Nom du projet dans lequel la base de données Spanner s'exécute.

-i instance_name

Nom de l'instance Spanner.

-d database_name

Nom de la base de données à laquelle se connecter.

Les options suivantes sont facultatives :

-r databaseRole=database_role

Rôle de base de données à utiliser pour la session. Pour en savoir plus, consultez la section Autorisation avec PGAdapter.

-c credentials_file_path

Chemin d'accès complet au fichier de clés contenant les identifiants du compte de service au format JSON. Si cette option n'est pas définie, les identifiants sont lus à partir du chemin spécifié par la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS.

Pour savoir comment créer un compte de service et télécharger un fichier de clé au format JSON, consultez la section Créer un compte de service.

Assurez-vous d'accorder au compte de service des identifiants suffisants pour accéder à la base de données.

Vous pouvez omettre cette option si vous vous authentifiez d'abord avec Google Cloud CLI à l'aide de la commande suivante:

gcloud auth application-default login

Pour en savoir plus, consultez la section Configurer l'authentification et l'autorisation.

-s port

Port sur lequel PGAdapter écoute. La valeur par défaut est 5432 (le port PostgreSQL par défaut).

-v version_number

Numéro de version de PostgreSQL à exposer au client pendant la connexion. La valeur par défaut est 14.1.

Certains pilotes et applications PostgreSQL permettent des fonctionnalités supplémentaires en fonction de ce numéro de version. Il est possible que Spanner ne soit pas compatible avec ces fonctionnalités. Pour obtenir la liste complète des clients compatibles, consultez Pilotes et clients.

-x

Active les connexions à partir d'hôtes autres que localhost. N'utilisez pas cette option lors du démarrage de PGAdapter en mode autonome. N'utilisez cette option que lors du démarrage dans un conteneur Docker

Par défaut, par mesure de sécurité, PGAdapter n'accepte que les connexions de "localhost".

L'exemple suivant démarre PGAdapter en mode autonome sur le port 5432 à l'aide des identifiants d'application par défaut.

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

Docker

Démarrez PGAdapter avec la commande suivante.

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

Outre les options de PGAdapter nécessaires pour spécifier un projet, une instance, une base de données et des identifiants, les options suivantes sont requises:

-p 127.0.0.1:HOST-PORT:DOCKER-PORT

Cette option Docker mappe le port DOCKER-PORT du conteneur Docker au port HOST-PORT en dehors du conteneur. DOCKER-PORT doit correspondre à la configuration de PGAdapter dans le conteneur. Sa valeur par défaut est 5432. HOST-PORT est le port sur lequel Docker doit écouter en dehors du conteneur pour les requêtes de connexion. Il doit toujours s'agir d'un port disponible sur localhost.

Pour en savoir plus, consultez la section Publier ou exposer le port (-p, --expose) dans la documentation de Docker.

-v CREDENTIALS_FILE_PATH:in_container_mount_point

Cette option Docker crée un montage lié (bind mount) d'un volume partagé. Elle mappe le chemin d'accès de l'hôte en dehors du conteneur avec un volume (point d'installation) à l'intérieur du conteneur. Les chemins d'accès à l'hôte et au conteneur sont séparés par un signe deux-points (:).

Cette option permet à PGAdapter d'accéder au fichier d'identifiants JSON qui se trouve en dehors du conteneur. Dans l'exemple précédent, l'option -c fait référence au point d'installation intégré au conteneur. Cet exemple nomme le point d'installation intégré au conteneur /acct_credentials.json. Vous pouvez le nommer comme vous le souhaitez.

Pour en savoir plus, consultez la page VOLUME (systèmes de fichiers partagés) dans la documentation de Docker.

-x

Active les connexions à partir d'hôtes autres que localhost. Cela est nécessaire, car le port interne au conteneur mappé au port hôte n'apparaît pas dans PGAdapter en tant que localhost.

Les options suivantes sont facultatives :

-r databaseRole=database_role

Rôle de base de données à utiliser pour la session. Pour en savoir plus, consultez la section Autorisation avec PGAdapter.

Dans l'exemple suivant, le port Docker et le port hôte sont tous deux définis sur le port par défaut du service de base de données PostgreSQL (port 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

Vous ne pouvez pas déployer PGAdapter en tant que service autonome sur Cloud Run, mais vous pouvez le déployer en tant que proxy side-car.

Nous vous recommandons d'exécuter PGAdapter dans un modèle de sidecar plutôt que de l'exécuter en tant que service distinct pour les raisons suivantes :

• Évite les points de défaillance uniques. L'accès de chaque application à votre base de données est indépendant des autres, ce qui rend l'ensemble plus résilient.
• Le nombre d'instances PGAdapter évolue automatiquement de manière linéaire avec le nombre d'instances d'application.

Le dépôt GitHub de PGAdapter contient plusieurs Exemples d'applications fonctionnelles utilisant Cloud Run et PGAdapter en tant que proxy secondaire pour différents langages de programmation.

Le fichier de configuration suivant montre comment ajouter PGAdapter en tant que proxy side-car à 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

Vous pouvez utiliser PGAdapter comme proxy side-car dans, par exemple, un cluster Kubernetes. Les conteneurs side-car Kubernetes s'exécutent en parallèle avec le conteneur principal du pod.

Nous vous recommandons d'exécuter PGAdapter dans un modèle sidecar plutôt que de l'exécuter en tant que service distinct pour les raisons suivantes:

• Évite les points de défaillance uniques. L'accès de chaque application à votre base de données est indépendant des autres, ce qui rend l'ensemble plus résilient.
• Comme PGAdapter consomme des ressources de façon linéaire, ce modèle vous permet de définir plus précisément la portée et les demandes des ressources pour les adapter à vos applications à mesure qu'elles évoluent.

Le fichier de configuration suivant montre comment ajouter PGAdapter en tant que proxy side-car à votre cluster 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"

Le dépôt GitHub de PGAdapter contient un guide par étapes et un exemple d'application. Cet exemple inclut des instructions pour utiliser la fédération d'identité de charge de travail pour GKE avec PGAdapter.

Java In-process

Créez et démarrez une instance PGAdapter avec votre code Java. Il s'agit de la configuration recommandée pour les applications Java.

Si vous utilisez un compte de service pour l'authentification, assurez-vous que la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS est définie sur le chemin d'accès du fichier d'identifiants.

1. Ajoutez google-cloud-spanner-pgadapter en tant que dépendance à votre projet. Pour en savoir plus, consultez la section Obtenir PGAdapter.
2. Créez un serveur à l'aide de la classe 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);
}

Le dépôt GitHub de PGAdapter contient un exemple d'application complet.

Étape suivante

• Connecter psql à une base de données PostgreSQL
• Connecter JDBC à une base de données PostgreSQL
• Connecter pgx à une base de données PostgreSQL
• Connecter psycopg2 à une base de données PostgreSQL
• Connecter psycopg3 à une base de données PostgreSQL
• Connecter node-postgres à une base de données PostgreSQL