Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

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 im Nur-Text-Modus, Transport Layer Security (TLS), TLS mit Anmeldedaten und gegenseitiges TLS (mTLS). Diese Sicherheitskonfigurationen schützen Ihre Daten bei der Übertragung durch unterschiedliche Verschlüsselungs- und Authentifizierungsverfahren. Für jede Konfiguration sind bestimmte Clienteinstellungen erforderlich, um die 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:

Beispielcode für einige dieser Treiber finden Sie in diesem Dokument.

Hinweis

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

Wenn Sie Maven ohne die Materialliste (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. Um diese Konfigurationen zu verwenden, legen Sie die in der folgenden Tabelle beschriebenen Clientoptionen fest:

Sicherheitskonfiguration	Beschreibung
Nur-Text	Die Kommunikation ist nicht verschlüsselt.
TLS	Die Kommunikation wird mit Transport Layer Security (TLS) verschlüsselt. Bei dieser Konfiguration müssen Sie das Spanner Omni CA-Zertifikat dem Java-Truststore hinzufügen, wie unter Java-Truststore konfigurieren beschrieben.
TLS mit Anmeldedaten	Die Kommunikation wird mit TLS verschlüsselt und die Authentifizierung erfolgt mit einem Nutzernamen und einem Passwort.
mTLS	Die Kommunikation wird mit gegenseitigem TLS (mTLS) verschlüsselt. Für diese Konfiguration müssen Sie sowohl ein Clientzertifikat als auch einen privaten Clientschlüssel angeben.

Als eigenständiger 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 eine manuelle Datenbankinteraktion benötigen. Durch diesen Ansatz wird der Proxy vom Lebenszyklus Ihrer Anwendung entkoppelt, sodass Sie ihn unabhängig verwalten und aktualisieren können. Wenn Sie PGAdapter als eigenständigen Prozess starten möchten, verwenden Sie die folgenden Konfigurationsmethoden, die von der ausgewählten Sicherheitskonfiguration abhängen:

Nur-Text

Führen Sie den folgenden Befehl aus, um PGAdapter mit Klartextkommunikation zu starten:

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

Ersetzen Sie Folgendes:

DATABASE_ID: die ID Ihrer Spanner Omni-Datenbank, z. B. test-db.
ENDPOINT: Der Endpunkt Ihrer Spanner Omni-Instanz, z. B. localhost:15000.

TLS

Wenn Sie eine PGAdapter-Verbindung mit TLS konfigurieren möchten, müssen Sie das Spanner Omni-CA-Zertifikat dem Java-Truststore hinzufügen, wie unter Java-Truststore konfigurieren beschrieben.

Führen Sie den folgenden Befehl aus, um PGAdapter mit TLS zu starten:

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 mit Anmeldedaten

Wenn Sie eine TLS-Verbindung mit Nutzername und Passwort herstellen möchten, verwenden Sie den Parameter -r, um username und password anzugeben:

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"

Ersetzen Sie Folgendes:

USERNAME: der Nutzername für Ihren Spanner Omni-Nutzer.
PASSWORD: das Passwort für Ihren Spanner Omni-Nutzer.

mTLS

Bevor Sie PGAdapter mit mTLS starten können, muss Ihr Clientschlüssel im PKCS#8-Format vorliegen. Führen Sie den folgenden Befehl aus, um einen vorhandenen Schlüssel in das PKCS#8-Format zu konvertieren:

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

Alternativ können Sie beim Erstellen des Clientzertifikats und des Schlüssels mit der Spanner Omni-Befehlszeile den Parameter --generate-pkcs8-key angeben, um den Schlüssel im PKCS#8-Format zu generieren.

Führen Sie den folgenden Befehl aus, um PGAdapter mit mTLS zu starten:

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"

Ersetzen Sie Folgendes:

PATH_TO_CLIENT_CERT: Pfad zu Ihrer Clientzertifikatsdatei.
PATH_TO_CLIENT_KEY: der Pfad zu Ihrer Clientschlüsseldatei.

Mit `psql` verbinden

Nachdem Sie eine Verbindung mit einer der oben genannten Methoden 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 die Funktion lokal ausführen, 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.

In-Process mit Ihrer Anwendung ausführen

Sie können PGAdapter auch im Prozess mit Ihrer Anwendung starten. Um die Sicherheit zu gewährleisten, konfigurieren Sie das OptionsMetadata-Objekt für jede unterstützte Sicherheitskonfiguration:

Nur-Text

Verwenden Sie für die Nur-Text-Kommunikation in Umgebungen wie der lokalen Entwicklung oder beim Testen die folgende Konfiguration:

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

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

TLS

Um eine TLS-Verbindung herzustellen, fügen Sie das CA-Zertifikat Ihrem Java-Truststore hinzu, wie unter Java-Truststore konfigurieren beschrieben. Verwenden Sie die folgende Konfiguration:

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

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

TLS mit Anmeldedaten

Wenn Sie eine TLS-Verbindung mit Nutzername und Passwort herstellen möchten, verwenden Sie setProperties(), um den Nutzernamen und das Passwort anzugeben:

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

Wenn Sie PGAdapter in-process mit Ihrer Java-Anwendung mit mTLS starten möchten, muss Ihr Clientschlüssel das PKCS#8-Format verwenden.

Verwenden Sie diese Konfiguration, um eine In-Process-mTLS-Verbindung herzustellen:

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 eine Verbindung zu PGAdapter mit dem PostgreSQL-Treiber JDBC herstellen, als ob Sie eine Verbindung zu einer PostgreSQL-Datenbank herstellen würden. Verwenden Sie den folgenden Beispielcode, um eine Verbindung zu einer Tabelle in einer Spanner Omni-Datenbank herzustellen und sie abzufragen:

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, als ob Sie eine Verbindung zu einer PostgreSQL-Datenbank herstellen würden. 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, als ob Sie eine Verbindung zu einer PostgreSQL-Datenbank herstellen würden. Verwenden Sie den folgenden Beispielcode, um eine Verbindung zu einer Tabelle in einer Spanner Omni-Datenbank herzustellen und sie abzufragen:

# 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 eine Verbindung zu PGAdapter mit node-postgres herstellen, als ob Sie eine Verbindung zu einer PostgreSQL-Datenbank herstellen würden. Verwenden Sie den folgenden Beispielcode, um eine Verbindung zu einer Tabelle in einer Spanner Omni-Datenbank herzustellen und sie abzufragen:

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

Verbindung über PGAdapter herstellen Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Hinweis

Sicherheitskonfigurationen

Als eigenständiger Prozess ausführen

Nur-Text

TLS

TLS mit Anmeldedaten

mTLS

Mit psql verbinden

In-Process mit Ihrer Anwendung ausführen

Nur-Text

TLS

TLS mit Anmeldedaten

mTLS

Beispielcode

JDBC

Go (pgx)

Python (psycopg2 oder psycopg3)

Node.js (node-postgres)

Verbindung über PGAdapter herstellen

Mit `psql` verbinden