Connettiti utilizzando PGAdapter

Questo documento descrive come connettersi a Spanner Omni utilizzando PGAdapter. Configura PGAdapter per stabilire connessioni sicure. PGAdapter supporta connessioni in testo normale, Transport Layer Security (TLS), TLS con credenziali, e mutual TLS (mTLS). Queste configurazioni di sicurezza proteggono i dati durante la trasmissione fornendo vari livelli di crittografia e autenticazione. Ogni configurazione richiede impostazioni client specifiche per garantire l'integrità e la riservatezza dei dati.

Puoi eseguire PGAdapter come processo autonomo o integrarlo direttamente nella tua applicazione. Per la gestione interattiva e l'esecuzione manuale delle query, connettiti al database utilizzando gli strumenti PostgreSQL standard come psql. Per creare applicazioni automatizzate, utilizza driver compatibili con PostgreSQL come i seguenti:

• Java Database Connectivity (JDBC)

• pgx per Go

• psycopg2

• psycopg3 per Python

• node-postgres per Node.js

Per esempi di codice che utilizzano alcuni di questi driver, consulta il codice campione in questo documento.

Prima di iniziare

Per utilizzare PGAdapter con Spanner Omni, utilizza PGAdapter versione 0.55.2 o successive.

Se utilizzi Maven senza la distinta base (BOM), aggiungi quanto segue alle dipendenze del file pom.xml:

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

Configurazioni di sicurezza

Spanner Omni PGAdapter supporta quattro configurazioni di sicurezza, che definiscono la modalità di crittografia e autenticazione della comunicazione tra PGAdapter e il database. Per utilizzare queste configurazioni, imposta le opzioni client descritte nella tabella seguente:

Eseguire come processo autonomo

Esegui PGAdapter come processo autonomo per applicazioni non Java e per strumenti PostgreSQL standard, ad esempio psql, quando hai bisogno di un'interazione manuale con il database. Questo approccio disaccoppia il proxy dal ciclo di vita dell'applicazione, consentendoti di gestirlo e aggiornarlo in modo indipendente. Per avviare PGAdapter come processo autonomo, utilizza i seguenti metodi di configurazione in base alla configurazione di sicurezza selezionata:

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

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"

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"

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

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"

Connettersi con psql

Dopo aver stabilito una connessione utilizzando uno dei metodi precedenti, esegui psql per gestire il database ed eseguire query. Per connetterti a psql, utilizza il comando seguente:

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

Sostituisci quanto segue:

• PG_HOST: il nome host o l'indirizzo IP della macchina in cui è in esecuzione PGAdapter. In caso di esecuzione locale, utilizza localhost.

• PG_PORT: il numero di porta su cui è in esecuzione PGAdapter. Se non hai specificato una porta personalizzata, PGAdapter utilizza la porta 5432 per impostazione predefinita.

• USERNAME: il tuo nome utente PostgreSQL.

Eseguire in-process con l'applicazione

Puoi anche avviare PGAdapter in-process con la tua applicazione. Per stabilire la sicurezza, configura l'oggetto OptionsMetadata per ogni configurazione di sicurezza supportata:

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

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

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

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

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();

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();

Codice campione

Questa sezione fornisce codice campione per la connessione a un database Spanner Omni utilizzando i seguenti driver compatibili con PostgreSQL:

• JDBC

• Go (pgx)

• Python (psycopg2 o psycopg3)

• Node.js (node-postgres)

Sostituisci il seguente segnaposto nelle stringhe di connessione:

• PASSWORD: la password per l'utente PostgreSQL.

JDBC

Puoi connetterti a PGAdapter utilizzando il driver JDBC PostgreSQL come se ti stessi connettendo a un database PostgreSQL. Per connetterti ed eseguire query su una tabella in un database Spanner Omni, utilizza il seguente codice campione:

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)

Puoi connetterti a PGAdapter utilizzando pgx come se ti stessi connettendo a un database PostgreSQL. Utilizza il seguente codice campione:

// 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 o psycopg3)

Puoi connetterti a PGAdapter utilizzando psycopg2 o psycopg3 come se ti stessi connettendo a un database PostgreSQL. Per connetterti ed eseguire query su una tabella in un database Spanner Omni, utilizza il seguente codice campione:

# 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)

Puoi connetterti a PGAdapter utilizzando node-postgres come se ti stessi connettendo a un database PostgreSQL. Per connetterti ed eseguire query su una tabella in un database Spanner Omni, utilizza il seguente codice campione:

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();