Menghubungkan menggunakan PGAdapter

Dokumen ini menjelaskan cara terhubung ke Spanner Omni menggunakan PGAdapter. Anda mengonfigurasi PGAdapter untuk membuat koneksi aman. PGAdapter mendukung mode keamanan teks biasa, Transport Layer Security (TLS), dan TLS mutual (mTLS). Mode ini melindungi data Anda selama transmisi dengan memberikan berbagai tingkat enkripsi dan autentikasi. Setiap mode keamanan memerlukan konfigurasi klien tertentu untuk memastikan integritas dan kerahasiaan data.

Anda dapat menjalankan PGAdapter sebagai proses mandiri atau mengintegrasikannya langsung ke dalam aplikasi Anda. Untuk pengelolaan interaktif dan eksekusi kueri manual, hubungkan ke database Anda menggunakan alat PostgreSQL standar seperti psql. Untuk membangun aplikasi otomatis, gunakan driver yang kompatibel dengan PostgreSQL seperti berikut:

Untuk contoh kode yang menggunakan beberapa driver ini, lihat contoh kode dalam dokumen ini.

Mode keamanan

Spanner Omni PGAdapter mendukung tiga mode keamanan, yang menentukan cara komunikasi dienkripsi dan diautentikasi antara PGAdapter dan database. Untuk menggunakan mode ini, konfigurasi opsi klien seperti yang dijelaskan dalam tabel berikut:

Mode keamanan	Deskripsi
Teks biasa	Komunikasi tidak dienkripsi.
TLS	Komunikasi dienkripsi menggunakan Transport Layer Security (TLS). Mode ini mengharuskan Anda menambahkan sertifikat CA Spanner Omni ke truststore Java default.
mTLS	Komunikasi dienkripsi menggunakan TLS timbal balik (mTLS). Mode ini mengharuskan Anda memberikan sertifikat klien dan kunci pribadi klien.

Menjalankan sebagai proses mandiri

Jalankan PGAdapter sebagai proses mandiri untuk aplikasi non-Java dan untuk alat PostgreSQL standar, misalnya, psql, saat Anda memerlukan interaksi database manual. Pendekatan ini memisahkan proxy dari siklus proses aplikasi Anda, yang memungkinkan Anda mengelola dan memperbaruinya secara terpisah. Untuk memulai PGAdapter sebagai proses mandiri, gunakan metode konfigurasi berikut berdasarkan mode keamanan yang Anda pilih.

Menggunakan mode teks biasa

Untuk memulai PGAdapter dalam mode komunikasi teks biasa, jalankan perintah berikut:

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

Ganti kode berikut:

DATABASE_ID: ID database Spanner Omni Anda, misalnya, test-db.
ENDPOINT: endpoint instance Spanner Omni Anda, misalnya, localhost:15000.

Menggunakan mode TLS

Sebelum dapat memulai PGAdapter dalam proses dalam mode TLS dengan aplikasi Java, Anda harus menambahkan sertifikat CA Spanner Omni ke truststore Java default. Untuk menambahkan sertifikat CA yang ada ke truststore Java, jalankan perintah berikut:

sudo keytool -import -trustcacerts -file ~/.spanner/certs/ca.crt -alias spanner-ca -keystore $JAVA_HOME/lib/security/cacerts

Untuk memulai PGAdapter dalam mode TLS, jalankan perintah berikut:

java -Djavax.net.ssl.trustStore=$JAVA_HOME/lib/security/cacerts \
     -Djavax.net.ssl.trustStoreType=JKS \
     -jar pgadapter.jar \
     -d DATABASE_ID \
     -e ENDPOINT \
     -r "isExperimentalHost=true"

Menggunakan mode mTLS

Sebelum dapat memulai PGAdapter dalam mode mTLS, Anda harus memastikan bahwa kunci klien Anda dalam format PKCS#8. Untuk mengonversi kunci yang ada di keystore Anda ke format PKCS#8, jalankan perintah berikut:

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

Atau, saat Anda membuat sertifikat dan kunci klien menggunakan Spanner Omni CLI, berikan parameter --generate-pkcs8-key untuk membuat kunci dalam format PKCS#8.

Untuk memulai PGAdapter dalam mode mTLS, jalankan perintah berikut:

java -Djavax.net.ssl.trustStore=$JAVA_HOME/lib/security/cacerts \
    -Djavax.net.ssl.trustStoreType=JKS \
    -jar pgadapter.jar \
    -d DATABASE_ID \
    -e ENDPOINT \
    -r "isExperimentalHost=true;clientCertificate=PATH_TO_CLIENT_CERT;clientKey=PATH_TO_CLIENT_KEY"

Ganti kode berikut:

PATH_TO_CLIENT_CERT: jalur ke file sertifikat klien Anda.
PATH_TO_CLIENT_KEY: jalur ke file kunci klien Anda.

Terhubung dengan `psql`

Setelah Anda membuat koneksi menggunakan salah satu metode sebelumnya, jalankan psql untuk mengelola database dan menjalankan kueri. Untuk terhubung ke psql, gunakan perintah berikut:

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

Ganti kode berikut:

PG_HOST: nama host atau alamat IP mesin tempat PGAdapter dijalankan. Jika dijalankan secara lokal, gunakan localhost.
PG_PORT: nomor port tempat PGAdapter dijalankan. Jika Anda belum menentukan port kustom, PGAdapter akan menggunakan port 5432 secara default.
USERNAME: nama pengguna PostgreSQL Anda.

Menjalankan dalam proses dengan aplikasi Anda

Anda juga dapat memulai PGAdapter dalam proses dengan aplikasi Anda. Untuk membuat keamanan, konfigurasi objek OptionsMetadata.

Menggunakan mode teks biasa

Untuk komunikasi teks biasa, seperti pengembangan lokal atau pengujian di lingkungan yang aman yang tidak memerlukan overhead enkripsi, gunakan konfigurasi berikut:

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

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

Menggunakan mode TLS

Untuk komunikasi teks biasa yang digunakan di lingkungan seperti pengembangan atau pengujian lokal, gunakan konfigurasi berikut:

sudo keytool -import -trustcacerts -file /.spanner/certs/ca.crt -alias spanner-ca -keystore $JAVA_HOME/lib/security/cacerts

Untuk membuat koneksi TLS dalam proses, gunakan konfigurasi berikut:

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

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

Menggunakan mode mTLS

Sebelum dapat memulai mode dalam proses PGAdapter dengan aplikasi Java, Anda harus memastikan kunci klien Anda dalam format PKCS#8. Untuk mengonversi kunci yang ada di keystore Anda ke format PKCS#8, jalankan perintah berikut:

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

Atau, saat Anda membuat sertifikat dan kunci klien menggunakan Spanner Omni CLI, berikan parameter --generate-pkcs8-key untuk membuat kunci dalam format PKCS#8.

Untuk membuat koneksi mTLS dalam proses, gunakan konfigurasi ini:

OptionsMetadata.Builder builder =
    OptionsMetadata.newBuilder()
    .setEndpoint("ENDPOINT")
    .useClientCert("PATH_TO_CLIENT_CERT", "PATH_TO_CLIENT_KEY");

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

Kode contoh

Bagian ini memberikan contoh kode untuk menghubungkan ke database Spanner Omni menggunakan driver yang kompatibel dengan PostgreSQL berikut:

JDBC
Go (pgx)
Python (psycopg2 atau psycopg3)
Node.js (node-postgres)

Ganti placeholder berikut dalam string koneksi Anda:

PASSWORD: sandi untuk pengguna PostgreSQL Anda.

JDBC

Anda dapat terhubung ke PGAdapter menggunakan driver JDBC PostgreSQL seolah-olah Anda terhubung ke database PostgreSQL. Untuk menghubungkan dan membuat kueri tabel di database Spanner Omni, gunakan contoh kode berikut:

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)

Anda dapat terhubung ke PGAdapter menggunakan pgx seolah-olah Anda terhubung ke database PostgreSQL. Gunakan contoh kode berikut:

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

Anda dapat terhubung ke PGAdapter menggunakan psycopg2 atau psycopg3 seolah-olah Anda terhubung ke database PostgreSQL. Untuk menghubungkan dan membuat kueri tabel di database Spanner Omni, gunakan contoh kode berikut:

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

Anda dapat terhubung ke PGAdapter menggunakan node-postgres seolah-olah Anda terhubung ke database PostgreSQL. Untuk menghubungkan dan membuat kueri tabel di database Spanner Omni, gunakan contoh kode berikut:

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

Menghubungkan menggunakan PGAdapter Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Mode keamanan

Menjalankan sebagai proses mandiri

Menggunakan mode teks biasa

Menggunakan mode TLS

Menggunakan mode mTLS

Terhubung dengan psql

Menjalankan dalam proses dengan aplikasi Anda

Menggunakan mode teks biasa

Menggunakan mode TLS

Menggunakan mode mTLS

Kode contoh

JDBC

Go (pgx)

Python (psycopg2 atau psycopg3)

Node.js (node-postgres)

Menghubungkan menggunakan PGAdapter

Terhubung dengan `psql`