Se connecter à l'aide de PGAdapter

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 modes de sécurité en texte brut, TLS (Transport Layer Security), et mTLS (Mutual TLS). Ces modes protègent vos données pendant leur transmission en fournissant différents niveaux de chiffrement et d'authentification. Chaque mode de sécurité nécessite des configurations 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 une gestion interactive et une 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 :

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

Modes de sécurité

Spanner Omni PGAdapter est compatible avec trois modes 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 modes, configurez les options client comme décrit dans le tableau suivant :

Mode de 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). Ce mode nécessite que vous ajoutiez le certificat CA Spanner Omni au truststore Java par défaut.
mTLS	La communication est chiffrée à l'aide du protocole mTLS (Mutual TLS). Ce mode nécessite que vous fournissiez 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 du mode de sécurité sélectionné.

Utiliser le mode texte brut

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

java -jar pgadapter.jar \
     -d DATABASE_ID \
     -e ENDPOINT \
     -r "isExperimentalHost=true;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.

Utiliser le mode TLS

Avant de pouvoir démarrer PGAdapter en cours de traitement en mode TLS avec votre application Java, vous devez ajouter votre certificat CA Spanner Omni au truststore Java par défaut. Pour ajouter un certificat CA existant au truststore Java, exécutez la commande suivante :

sudo keytool -import -trustcacerts -file ~/.spanner/certs/ca.crt -alias spanner-ca -keystore $JAVA_HOME/lib/security/cacerts

Pour démarrer PGAdapter en mode 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 "isExperimentalHost=true"

Utiliser le mode mTLS

Avant de pouvoir démarrer PGAdapter en mode mTLS, vous devez vous assurer que votre clé client est au format PKCS#8. Pour convertir une clé existante dans votre keystore 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 fournir le paramètre --generate-pkcs8-key lorsque vous créez votre certificat et votre clé client à l'aide de l'interface de ligne de commande Spanner Omni pour générer la clé au format PKCS#8.

Pour démarrer PGAdapter en mode 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 "isExperimentalHost=true;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, utilisez 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 en local, 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.

Utiliser le mode texte brut

Pour une communication en texte brut, comme le développement local ou les tests dans des environnements sécurisés où la surcharge de chiffrement n'est pas nécessaire, utilisez la configuration suivante :

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

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

Utiliser le mode TLS

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

sudo keytool -import -trustcacerts -file /.spanner/certs/ca.crt -alias spanner-ca -keystore $JAVA_HOME/lib/security/cacerts

Pour établir une connexion TLS en cours de traitement, utilisez la configuration suivante :

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

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

Utiliser le mode mTLS

Avant de pouvoir démarrer PGAdapter en mode de traitement avec votre application Java, vous devez vous assurer que votre clé client est au format PKCS#8. Pour convertir une clé existante dans votre keystore au format PKCS#8, exécutez la commande suivante :

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

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

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

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

Exemples de code

Cette section fournit des exemples 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();

Se connecter à l'aide de PGAdapter Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Modes de sécurité

Exécuter en tant que processus autonome

Utiliser le mode texte brut

Utiliser le mode TLS

Utiliser le mode mTLS

Se connecter avec psql

Exécuter en cours de traitement avec votre application

Utiliser le mode texte brut

Utiliser le mode TLS

Utiliser le mode mTLS

Exemples de code

JDBC

Go (pgx)

Python (psycopg2 ou psycopg3)

Node.js (node-postgres)

Se connecter à l'aide de PGAdapter

Se connecter avec `psql`