Se connecter à l'aide de PGAdapter

Aperçu

Ce produit ou cette fonctionnalité est une offre en version bêta soumise aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Il ne peut être utilisé qu'à des fins de développement, de test, de prototypage et de démonstration de programmes logiciels. Il ne peut être utilisé à des fins de traitement de données ni à des fins commerciales. Les produits et fonctionnalités de pré-DG sont proposés "en l'état" et peuvent présenter une compatibilité limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Ce document explique comment se connecter à Spanner Omni à l'aide de PGAdapter. Vous configurez PGAdapter pour établir des connexions sécurisées. PGAdapter est compatible avec les connexions en texte brut, TLS (Transport Layer Security), TLS avec identifiants et TLS mutuel (mTLS). Ces configurations de sécurité protègent vos données pendant la transmission en fournissant différents niveaux de chiffrement et d'authentification. Chaque configuration nécessite des paramètres client spécifiques pour garantir l'intégrité et la confidentialité des données.

Vous pouvez exécuter PGAdapter en tant que processus autonome ou l'intégrer directement à votre application. Pour la gestion interactive et l'exécution manuelle des requêtes, connectez-vous à votre base de données à l'aide d'outils PostgreSQL standards tels que psql. Pour créer des applications automatisées, utilisez des pilotes compatibles avec PostgreSQL, tels que les suivants :

• JDBC (Java Database Connectivity)

• pgx pour Go

• psycopg2

• psycopg3 pour Python

• node-postgres pour Node.js

Pour obtenir des exemples de code utilisant certains de ces pilotes, consultez la section Exemples de code de ce document.

Avant de commencer

Pour utiliser PGAdapter avec Spanner Omni, utilisez la version 0.55.2 ou une version ultérieure de PGAdapter.

Si vous utilisez Maven sans la nomenclature (BOM), ajoutez les éléments suivants aux dépendances du fichier pom.xml :

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-spanner-pgadapter</artifactId>
  <version>0.55.2</version>
</dependency>

Configurations de sécurité

Spanner Omni PGAdapter est compatible avec quatre configurations de sécurité, qui définissent la manière dont la communication est chiffrée et authentifiée entre PGAdapter et la base de données. Pour utiliser ces configurations, définissez les options client décrites dans le tableau suivant :

Configuration de la sécurité	Description
Texte brut	La communication n'est pas chiffrée.
TLS	La communication est chiffrée à l'aide du protocole TLS (Transport Layer Security). Cette configuration nécessite que vous ajoutiez le certificat CA Spanner Omni au truststore Java, comme décrit dans la section Configurer le truststore Java.
TLS avec identifiants	La communication est chiffrée à l'aide du protocole TLS, et l'authentification est effectuée à l'aide d'un nom d'utilisateur et d'un mot de passe.
mTLS	La communication est chiffrée à l'aide du protocole TLS mutuel (mTLS). Cette configuration nécessite que vous fournissiez à la fois un certificat client et une clé privée client.

Exécuter en tant que processus autonome

Exécutez PGAdapter en tant que processus autonome pour les applications non Java et pour les outils PostgreSQL standards, par exemple psql, lorsque vous avez besoin d'une interaction manuelle avec la base de données. Cette approche dissocie le proxy du cycle de vie de votre application, ce qui vous permet de le gérer et de le mettre à jour indépendamment. Pour démarrer PGAdapter en tant que processus autonome, utilisez les méthodes de configuration suivantes en fonction de la configuration de sécurité sélectionnée :

Texte brut

Pour démarrer PGAdapter avec une communication en texte brut, exécutez la commande suivante :

java -jar pgadapter.jar \
     -d DATABASE_ID \
     -e ENDPOINT \
     -r "type=omni;usePlainText=true"

Remplacez les éléments suivants :

• DATABASE_ID: ID de votre base de données Spanner Omni, par exemple test-db.

• ENDPOINT: point de terminaison de votre instance Spanner Omni, par exemple localhost:15000.

TLS

Pour configurer une connexion PGAdapter à l'aide du protocole TLS, vous devez ajouter votre certificat CA Spanner Omni au truststore Java, comme décrit dans Configurer le truststore Java.

Pour démarrer PGAdapter à l'aide du protocole TLS, exécutez la commande suivante :

java -Djavax.net.ssl.trustStore=$JAVA_HOME/lib/security/cacerts \
     -Djavax.net.ssl.trustStoreType=JKS \
     -jar pgadapter.jar \
     -d DATABASE_ID \
     -e ENDPOINT \
     -r "type=omni"

TLS avec identifiants

Pour établir une connexion TLS avec authentification par nom d'utilisateur et mot de passe, utilisez le paramètre -r pour spécifier le username et le password :

java -Djavax.net.ssl.trustStore=$JAVA_HOME/lib/security/cacerts \
     -Djavax.net.ssl.trustStoreType=JKS \
     -jar pgadapter.jar \
     -d DATABASE_ID \
     -e ENDPOINT \
     -r "type=omni;username=USERNAME;password=PASSWORD"

Remplacez les éléments suivants :

• USERNAME : nom d'utilisateur de votre utilisateur Spanner Omni.

• PASSWORD : mot de passe de votre utilisateur Spanner Omni.

mTLS

Avant de pouvoir démarrer PGAdapter à l'aide du protocole mTLS, vous devez vous assurer que votre clé client est au format PKCS#8. Pour convertir une clé existante au format PKCS#8, exécutez la commande suivante :

openssl pkcs8 -topk8 -in ~/.spanner/certs/client.key -out ~/.spanner/certs/java-client.key -nocrypt

Vous pouvez également, lorsque vous créez votre certificat et votre clé client à l'aide de l'interface de ligne de commande Spanner Omni, fournir le paramètre --generate-pkcs8-key pour générer la clé au format PKCS#8.

Pour démarrer PGAdapter à l'aide du protocole mTLS, exécutez la commande suivante :

java -Djavax.net.ssl.trustStore=$JAVA_HOME/lib/security/cacerts \
    -Djavax.net.ssl.trustStoreType=JKS \
    -jar pgadapter.jar \
    -d DATABASE_ID \
    -e ENDPOINT \
    -r "type=omni;clientCertificate=PATH_TO_CLIENT_CERT;clientKey=PATH_TO_CLIENT_KEY"

Remplacez les éléments suivants :

• PATH_TO_CLIENT_CERT: chemin d'accès à votre fichier de certificat client.

• PATH_TO_CLIENT_KEY : chemin d'accès à votre fichier de clé client.

Se connecter avec psql

Une fois que vous avez établi une connexion à l'aide de l'une des méthodes précédentes, exécutez psql pour gérer votre base de données et exécuter des requêtes. Pour vous connecter à psql, exécutez la commande suivante :

psql -h PG_HOST -p PG_PORT -U USERNAME -d DATABASE_ID

Remplacez les éléments suivants :

• PG_HOST: nom d'hôte ou adresse IP de la machine sur laquelle PGAdapter est exécuté. Si vous exécutez localement, utilisez localhost.

• PG_PORT : numéro de port sur lequel PGAdapter est exécuté. Si vous n'avez pas spécifié de port personnalisé, PGAdapter utilise le port 5432 par défaut.

• USERNAME : nom d'utilisateur PostgreSQL.

Exécuter en cours de traitement avec votre application

Vous pouvez également démarrer PGAdapter en cours de traitement avec votre application. Pour établir la sécurité, configurez l'objet OptionsMetadata pour chaque configuration de sécurité compatible :

Texte brut

Pour une communication en texte brut dans des environnements tels que le développement local ou les tests, utilisez la configuration suivante :

OptionsMetadata.Builder builder =
    OptionsMetadata.newBuilder()
        .setEndpoint("ENDPOINT")
        .setType("omni")
        .setUsePlainText();

ProxyServer server = new ProxyServer(builder.build());
server.startServer();
server.awaitRunning();

TLS

Pour établir une connexion TLS, ajoutez le certificat CA à votre truststore Java , comme décrit dans Configurer le truststore Java, et utilisez la configuration suivante :

OptionsMetadata.Builder builder =
    OptionsMetadata.newBuilder()
        .setEndpoint("ENDPOINT")
        .setType("omni");

ProxyServer server = new ProxyServer(builder.build());
server.startServer();
server.awaitRunning();

TLS avec identifiants

Pour établir une connexion TLS avec authentification par nom d'utilisateur et mot de passe, utilisez setProperties() pour spécifier le nom d'utilisateur et le mot de passe :

OptionsMetadata.Builder builder =
    OptionsMetadata.newBuilder()
        .setEndpoint("ENDPOINT")
        .setType("omni")
        .setProperties(
            Map.of(
                "username", "USERNAME",
                "password", "PASSWORD"));

ProxyServer server = new ProxyServer(builder.build());
server.startServer();
server.awaitRunning();

mTLS

Pour démarrer PGAdapter en cours de traitement avec votre application Java à l'aide du protocole mTLS, votre clé client doit utiliser le format PKCS#8.

Pour établir une connexion mTLS en cours de traitement, utilisez cette configuration :

OptionsMetadata.Builder builder =
    OptionsMetadata.newBuilder()
        .setEndpoint("ENDPOINT")
        .setType("omni")
        .useClientCert(
            "PATH_TO_CLIENT_CERT",
            "PATH_TO_CLIENT_KEY");

ProxyServer server = new ProxyServer(builder.build());
server.startServer();
server.awaitRunning();

Exemple de code

Cette section fournit un exemple de code pour se connecter à une base de données Spanner Omni à l'aide des pilotes compatibles avec PostgreSQL suivants :

• JDBC

• Go (pgx)

• Python (psycopg2 ou psycopg3)

• Node.js (node-postgres)

Remplacez l'espace réservé suivant dans vos chaînes de connexion :

• PASSWORD : mot de passe de votre utilisateur PostgreSQL.

JDBC

Vous pouvez vous connecter à PGAdapter à l'aide du pilote JDBC PostgreSQL comme si vous vous connectiez à une base de données PostgreSQL. Pour vous connecter à une table d'une base de données Spanner Omni et l'interroger, utilisez l'exemple de code suivant :

String jdbcUrl =
    "jdbc:postgresql://PG_HOST:PG_PORT/DATABASE_ID";

try (Connection connection = DriverManager.getConnection(jdbcUrl)) {
  // Example: Query data
  try (Statement statement = connection.createStatement();
      ResultSet resultSet = statement.executeQuery("SELECT * FROM Singers")) {

    System.out.println("Query Results:");
    while (resultSet.next()) {
      long id = resultSet.getLong("id");
      String name = resultSet.getString("name");
      System.out.printf("ID: %d, Name: %s\n", id, name);
    }
  } catch (SQLException e) {
    throw new RuntimeException(e);
  }
}

Go (pgx)

Vous pouvez vous connecter à PGAdapter à l'aide de pgx comme si vous vous connectiez à une base de données PostgreSQL. Utilisez l'exemple de code suivant :

// Database connection string
connString := "postgres://USERNAME:PASSWORD@PG_HOST:PG_PORT/DATABASE_ID?sslmode=disable"
ctx := context.Background()

// Connect to PGAdapter
conn, err := pgx.Connect(ctx, connString)
if err != nil {
  log.Fatalf("Connection error: %s", err.Error())
}
defer conn.Close(ctx)

// Query all rows from the Singers table
rows, err := conn.Query(ctx, "SELECT id, name FROM Singers")
if err != nil {
  log.Fatalf("Query error: %s", err.Error())
}
defer rows.Close()

// Iterate over the result set
fmt.Println("Singers Table Data:")
for rows.Next() {
  var id int
  var name string
  if err := rows.Scan(&id, &name); err != nil {
    log.Fatalf("Scan error: %s", err.Error())
  }
  fmt.Printf("ID: %d, Name: %s\n", id, name)
}

Python (psycopg2 ou psycopg3)

Vous pouvez vous connecter à PGAdapter à l'aide de psycopg2 ou psycopg3 comme si vous vous connectiez à une base de données PostgreSQL. Pour vous connecter à une table d'une base de données Spanner Omni et l'interroger, utilisez l'exemple de code suivant :

# psycopg2
import psycopg2

connection = psycopg2.connect(database="DATABASE_ID",
                              host="PG_HOST",
                              port=PG_PORT)

cursor = connection.cursor()
cursor.execute('SELECT * FROM Singers')
for row in cursor:
  print(row)

cursor.close()
connection.close()


# psycopg3
import psycopg

with psycopg.connect("host=PG_HOST port=PG_PORT dbname=DATABASE_ID sslmode=disable") as conn:
  conn.autocommit = True
  with conn.cursor() as cur:
    cur.execute("SELECT * FROM Singers")
    for row in cur:
      print(row)

Node.js (node-postgres)

Vous pouvez vous connecter à PGAdapter à l'aide de node-postgres comme si vous vous connectiez à une base de données PostgreSQL. Pour vous connecter à une table d'une base de données Spanner Omni et l'interroger, utilisez l'exemple de code suivant :

const { Client } = require('pg');
const client = new Client({
  host: 'PG_HOST',
  port: PG_PORT,
  database: 'DATABASE_ID',
});
await client.connect();
const res = await client.query("SELECT * FROM Singers");
console.log(res.rows);
await client.end();