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

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

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

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

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

כדי להשתמש ב-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 לבין מסד הנתונים. כדי להשתמש בהגדרות האלה, צריך להגדיר את אפשרויות הלקוח שמתוארות בטבלה הבאה:

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

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

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

טקסט פשוט

כדי להפעיל את PGAdapter עם תקשורת בטקסט רגיל, מריצים את הפקודה הבאה:

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

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

  • ‫DATABASE_ID: המזהה של מסד הנתונים של Spanner Omni, לדוגמה, test-db.

  • ‫ENDPOINT: נקודת הקצה של מופע Spanner Omni, לדוגמה, localhost:15000.

TLS

כדי להגדיר חיבור PGAdapter באמצעות TLS, צריך להוסיף את אישור ה-CA של Spanner Omni למאגר האישורים המהימנים של Java, כמו שמתואר במאמר הגדרת מאגר האישורים המהימנים של Java.

כדי להפעיל את PGAdapter באמצעות TLS, מריצים את הפקודה הבאה:

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 עם פרטי כניסה

כדי ליצור חיבור TLS עם אימות של שם משתמש וסיסמה, משתמשים בפרמטר -r כדי לציין את username ואת password:

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"

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

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

  • ‫PASSWORD: הסיסמה של המשתמש ב-Spanner Omni.

mTLS

כדי להפעיל את PGAdapter באמצעות mTLS, צריך לוודא שמפתח הלקוח הוא בפורמט PKCS#8. כדי להמיר מפתח קיים לפורמט PKCS#8, מריצים את הפקודה הבאה:

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

לחלופין, כשיוצרים את אישור הלקוח והמפתח באמצעות Spanner Omni CLI, אפשר לספק את הפרמטר --generate-pkcs8-key כדי ליצור את המפתח בפורמט PKCS#8.

כדי להפעיל את PGAdapter באמצעות mTLS, מריצים את הפקודה הבאה:

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"

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

  • ‫PATH_TO_CLIENT_CERT: הנתיב לקובץ אישור הלקוח.

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

TLS

כדי ליצור חיבור TLS, צריך להוסיף את אישור ה-CA למאגר האישורים המהימנים של Java, כמו שמתואר במאמר הגדרת מאגר האישורים המהימנים של Java, ולהשתמש בהגדרה הבאה:

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

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

TLS עם פרטי כניסה

כדי ליצור חיבור TLS עם אימות באמצעות שם משתמש וסיסמה, משתמשים ב-setProperties() כדי לציין את שם המשתמש והסיסמה:

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

כדי להפעיל את PGAdapter בתהליך עם אפליקציית Java באמצעות mTLS, המפתח של הלקוח צריך להיות בפורמט PKCS#8.

כדי ליצור חיבור mTLS בתהליך, משתמשים בהגדרה הזו:

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:

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

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