חיבור באמצעות PGAdapter

במאמר הזה מוסבר איך להתחבר ל-Spanner Omni באמצעות PGAdapter. מגדירים את PGAdapter ליצירת חיבורים מאובטחים. ‫PGAdapter תומך בטקסט רגיל, ב-Transport Layer Security ‏ (TLS), ב-TLS עם פרטי כניסה ובחיבורים של TLS הדדי (mTLS). הגדרות האבטחה האלה מגנות על הנתונים בזמן ההעברה באמצעות רמות שונות של הצפנה ואימות. כל הגדרה דורשת הגדרות לקוח ספציפיות כדי להבטיח את תקינות הנתונים ואת הסודיות שלהם.

אפשר להריץ את PGAdapter כתהליך עצמאי או לשלב אותו ישירות באפליקציה. לניהול אינטראקטיבי ולהרצת שאילתות ידנית, מתחברים למסד הנתונים באמצעות כלים סטנדרטיים של PostgreSQL כמו psql. כדי ליצור אפליקציות אוטומטיות, אפשר להשתמש במנהלי התקנים שתואמים ל-PostgreSQL, כמו:

• Java Database Connectivity ‏ (JDBC)

• ‫pgx ל-Go

• psycopg2

• ‫psycopg3 ל-Python

• ‫node-postgres ל-Node.js

דוגמאות קוד לשימוש בחלק מהדרייברים האלה מופיעות בקטע קוד לדוגמה במסמך הזה.

לפני שמתחילים

כדי להשתמש ב-PGAdapter עם Spanner Omni, צריך להשתמש ב-PGAdapter מגרסה 0.55.2 ואילך.

אם משתמשים ב-Maven בלי Bill of Materials (BOM), צריך להוסיף את הקוד הבא ליחסי התלות בקובץ pom.xml:

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

תצורות אבטחה

‫Spanner Omni PGAdapter תומך בארבע הגדרות אבטחה, שמגדירות איך התקשורת מוצפנת ומאומתת בין PGAdapter לבין מסד הנתונים. כדי להשתמש בהגדרות האלה, צריך להגדיר את אפשרויות הלקוח שמתוארות בטבלה הבאה:

הפעלה כתהליך עצמאי

מריצים את PGAdapter כתהליך עצמאי באפליקציות שאינן Java ובכלים סטנדרטיים של PostgreSQL, לדוגמה, psql, כשצריך אינטראקציה ידנית עם מסד הנתונים. הגישה הזו מפרידה את שרת ה-proxy ממחזור החיים של האפליקציה, ומאפשרת לכם לנהל ולעדכן אותו באופן עצמאי. כדי להפעיל את PGAdapter כתהליך עצמאי, משתמשים בשיטות ההגדרה הבאות בהתאם להגדרת האבטחה שנבחרה:

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"

חיבור באמצעות psql

אחרי שיוצרים קישור באמצעות אחת מהשיטות הקודמות, מריצים את הפקודה psql כדי לנהל את מסד הנתונים ולהריץ שאילתות. כדי להתחבר אל psql, משתמשים בפקודה הבאה:

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

מחליפים את מה שכתוב בשדות הבאים:

• ‫PG_HOST: שם המארח או כתובת ה-IP של המכונה שבה PGAdapter פועל. אם מריצים באופן מקומי, משתמשים ב-localhost.

• ‫PG_PORT: מספר היציאה שבה PGAdapter פועל. אם לא ציינתם יציאה בהתאמה אישית, PGAdapter משתמש ביציאה 5432 כברירת מחדל.

• ‫USERNAME: שם המשתמש שלכם ב-PostgreSQL.

הפעלה בתהליך עם האפליקציה

אפשר גם להפעיל את PGAdapter בתוך התהליך של האפליקציה. כדי להגדיר אבטחה, צריך להגדיר את האובייקט OptionsMetadata לכל הגדרת אבטחה נתמכת:

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

קוד לדוגמה

בקטע הזה מוצג קוד לדוגמה לחיבור למסד נתונים של Spanner Omni באמצעות מנהלי ההתקנים הבאים שתואמים ל-PostgreSQL:

• JDBC

• ‫Go ‏ (pgx)

• ‫Python (psycopg2 או psycopg3)

• ‫Node.js (node-postgres)

מחליפים את הערך הזמני לשמירת מקום במחרוזות החיבור:

• ‫PASSWORD: הסיסמה של משתמש PostgreSQL.

JDBC

אפשר להתחבר ל-PGAdapter באמצעות מנהל ההתקן JDBC של PostgreSQL, כאילו מתחברים למסד נתונים של PostgreSQL. כדי להתחבר לטבלה במסד נתונים של Spanner Omni ולהריץ עליה שאילתה, משתמשים בקוד לדוגמה הבא:

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)

אפשר להתחבר ל-PGAdapter באמצעות pgx כאילו מתחברים למסד נתונים של PostgreSQL. משתמשים בקוד לדוגמה הבא:

// 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 או psycopg3)

אפשר להתחבר ל-PGAdapter באמצעות psycopg2 או psycopg3 כאילו מתחברים למסד נתונים של PostgreSQL. כדי להתחבר לטבלה במסד נתונים של Spanner Omni ולהריץ עליה שאילתה, משתמשים בקוד לדוגמה הבא:

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

אפשר להתחבר ל-PGAdapter באמצעות node-postgres כאילו מתחברים למסד נתונים של PostgreSQL. כדי להתחבר לטבלה במסד נתונים של Spanner Omni ולהריץ עליה שאילתה, משתמשים בקוד לדוגמה הבא:

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