Verbindung über PGAdapter herstellen

In diesem Dokument wird beschrieben, wie Sie mit PGAdapter eine Verbindung zu Spanner Omni herstellen. Sie konfigurieren PGAdapter, um sichere Verbindungen herzustellen. PGAdapter unterstützt Verbindungen mit Nur-Text, Transport Layer Security (TLS), TLS mit Anmeldedaten, und gegenseitigem TLS (mTLS). Diese Sicherheitskonfigurationen schützen Ihre Daten bei der Übertragung durch unterschiedliche Verschlüsselungs- und Authentifizierungsebenen. Jede Konfiguration erfordert bestimmte Clienteinstellungen, um Datenintegrität und Vertraulichkeit zu gewährleisten.

Sie können PGAdapter als eigenständigen Prozess ausführen oder direkt in Ihre Anwendung einbinden. Für die interaktive Verwaltung und die manuelle Ausführung von Abfragen stellen Sie mit Standard-PostgreSQL-Tools wie psql eine Verbindung zu Ihrer Datenbank her. Verwenden Sie zum Erstellen automatisierter Anwendungen PostgreSQL-kompatible Treiber wie die folgenden:

• Java Database Connectivity (JDBC)

• pgx für Go

• psycopg2

• psycopg3 für Python

• node-postgres für Node.js

Codebeispiele, in denen einige dieser Treiber verwendet werden, finden Sie im Beispielcode in diesem Dokument.

Hinweis

Wenn Sie PGAdapter mit Spanner Omni verwenden möchten, verwenden Sie PGAdapter Version 0.55.2 oder höher.

Wenn Sie Maven ohne Bill of Materials (BOM) verwenden, fügen Sie den Abhängigkeiten der Datei pom.xml Folgendes hinzu:

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

Sicherheitskonfigurationen

Spanner Omni PGAdapter unterstützt vier Sicherheitskonfigurationen, die definieren, wie die Kommunikation zwischen PGAdapter und der Datenbank verschlüsselt und authentifiziert wird. Wenn Sie diese Konfigurationen verwenden möchten, legen Sie die in der folgenden Tabelle beschriebenen Clientoptionen fest:

Als eigenständigen Prozess ausführen

Führen Sie PGAdapter als eigenständigen Prozess für Nicht-Java-Anwendungen und für Standard-PostgreSQL-Tools wie psql aus, wenn Sie manuell mit der Datenbank interagieren müssen. Bei diesem Ansatz wird der Proxy vom Lebenszyklus Ihrer Anwendung entkoppelt, sodass Sie ihn unabhängig verwalten und aktualisieren können. Verwenden Sie die folgenden Konfigurationsmethoden, um PGAdapter als eigenständigen Prozess zu starten, je nach ausgewählter Sicherheitskonfiguration:

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"

Mit psql verbinden

Nachdem Sie mit einer der oben genannten Methoden eine Verbindung hergestellt haben, führen Sie psql aus, um Ihre Datenbank zu verwalten und Abfragen auszuführen. Verwenden Sie den folgenden Befehl, um eine Verbindung zu psql herzustellen:

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

Ersetzen Sie Folgendes:

• PG_HOST: der Hostname oder die IP-Adresse des Computers, auf dem PGAdapter ausgeführt wird. Wenn Sie lokal arbeiten, verwenden Sie localhost.

• PG_PORT: die Portnummer, auf der PGAdapter ausgeführt wird. Wenn Sie keinen benutzerdefinierten Port angegeben haben, verwendet PGAdapter standardmäßig Port 5432.

• USERNAME: Ihr PostgreSQL-Nutzername.

Als Verarbeitungsprozess mit Ihrer Anwendung ausführen

Sie können PGAdapter auch als Verarbeitungsprozess mit Ihrer Anwendung starten. Konfigurieren Sie das Objekt OptionsMetadata für jede unterstützte Sicherheitskonfiguration, um die Sicherheit zu gewährleisten:

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

Beispielcode

In diesem Abschnitt finden Sie Beispielcode für die Verbindung zu einer Spanner Omni-Datenbank mit den folgenden PostgreSQL-kompatiblen Treibern:

• JDBC

• Go (pgx)

• Python (psycopg2 oder psycopg3)

• Node.js (node-postgres)

Ersetzen Sie den folgenden Platzhalter in Ihren Verbindungsstrings:

• PASSWORD: das Passwort für Ihren PostgreSQL-Nutzer.

JDBC

Sie können mit dem PostgreSQL-JDBC-Treiber eine Verbindung zu PGAdapter herstellen, so als würden Sie eine Verbindung zu einer PostgreSQL-Datenbank herstellen. Verwenden Sie den folgenden Beispielcode, um eine Verbindung zu einer Tabelle in einer Spanner Omni-Datenbank herzustellen und eine Abfrage auszuführen:

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)

Sie können mit pgx eine Verbindung zu PGAdapter herstellen, so als würden Sie eine Verbindung zu einer PostgreSQL-Datenbank herstellen. Verwenden Sie den folgenden Beispielcode:

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

Sie können mit psycopg2 oder psycopg3 eine Verbindung zu PGAdapter herstellen, so als würden Sie eine Verbindung zu einer PostgreSQL-Datenbank herstellen. Verwenden Sie den folgenden Beispielcode, um eine Verbindung zu einer Tabelle in einer Spanner Omni-Datenbank herzustellen und eine Abfrage auszuführen:

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

Sie können mit node-postgres eine Verbindung zu PGAdapter herstellen, so als würden Sie eine Verbindung zu einer PostgreSQL-Datenbank herstellen. Verwenden Sie den folgenden Beispielcode, um eine Verbindung zu einer Tabelle in einer Spanner Omni-Datenbank herzustellen und eine Abfrage auszuführen:

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