Menghubungkan menggunakan PGAdapter

Pratinjau

Produk atau fitur ini adalah penawaran pratinjau yang tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum di Persyaratan Khusus Layanan, dan hanya dapat digunakan untuk tujuan pengembangan, pengujian, pembuatan prototipe, dan demonstrasi program software. API ini tidak dapat digunakan untuk pemrosesan data atau tujuan komersial apa pun. Produk dan fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Dokumen ini menjelaskan cara terhubung ke Spanner Omni menggunakan PGAdapter. Anda mengonfigurasi PGAdapter untuk membuat koneksi aman. PGAdapter mendukung teks biasa, Transport Layer Security (TLS), TLS dengan kredensial, dan koneksi TLS mutual (mTLS). Konfigurasi keamanan ini melindungi data Anda selama transmisi dengan menyediakan berbagai tingkat enkripsi dan autentikasi. Setiap konfigurasi memerlukan setelan 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:

• Java Database Connectivity (JDBC)

• pgx untuk Go

• psycopg2

• psycopg3 untuk Python

• node-postgres untuk Node.js

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

Sebelum memulai

Untuk menggunakan PGAdapter dengan Spanner Omni, gunakan PGAdapter versi 0.55.2 atau yang lebih baru.

Jika Anda menggunakan Maven tanpa Bill of Materials (BOM), tambahkan kode berikut ke dependensi file pom.xml:

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

Konfigurasi keamanan

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

Konfigurasi keamanan	Deskripsi
Teks biasa	Komunikasi tidak dienkripsi.
TLS	Komunikasi dienkripsi menggunakan Transport Layer Security (TLS). Konfigurasi ini mengharuskan Anda menambahkan sertifikat CA Spanner Omni ke truststore Java, seperti yang dijelaskan dalam Mengonfigurasi truststore Java.
TLS dengan kredensial	Komunikasi dienkripsi menggunakan TLS, dan autentikasi dilakukan menggunakan nama pengguna dan sandi.
mTLS	Komunikasi dienkripsi menggunakan TLS timbal balik (mTLS). Konfigurasi ini memerlukan Anda untuk 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 konfigurasi keamanan yang Anda pilih:

Teks biasa

Untuk memulai PGAdapter dengan komunikasi teks biasa, jalankan perintah berikut:

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

Ganti kode berikut:

• DATABASE_ID: ID database Spanner Omni Anda, misalnya, test-db.

• ENDPOINT: endpoint instance Spanner Omni Anda, misalnya, localhost:15000.

TLS

Untuk mengonfigurasi koneksi PGAdapter menggunakan TLS, Anda harus menambahkan sertifikat CA Spanner Omni ke truststore Java, seperti yang dijelaskan dalam Mengonfigurasi truststore Java.

Untuk memulai PGAdapter menggunakan 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 "type=omni"

TLS dengan kredensial

Untuk membuat koneksi TLS dengan autentikasi nama pengguna dan sandi, gunakan parameter -r untuk menentukan username dan 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"

Ganti kode berikut:

• USERNAME: nama pengguna untuk pengguna Spanner Omni Anda.

• PASSWORD: sandi untuk pengguna Spanner Omni Anda.

mTLS

Sebelum dapat memulai PGAdapter menggunakan mTLS, Anda harus memastikan bahwa kunci klien Anda dalam format PKCS#8. Untuk mengonversi kunci yang ada 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 menggunakan 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 "type=omni;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 di atas, 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 menetapkan keamanan, konfigurasikan objek OptionsMetadata untuk setiap konfigurasi keamanan yang didukung:

Teks biasa

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

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

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

TLS

Untuk membuat koneksi TLS, tambahkan sertifikat CA ke truststore Java Anda seperti yang dijelaskan dalam Mengonfigurasi truststore Java, dan gunakan konfigurasi berikut:

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

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

TLS dengan kredensial

Untuk membuat koneksi TLS dengan autentikasi nama pengguna dan sandi, gunakan setProperties() untuk menentukan nama pengguna dan sandi:

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

Untuk memulai PGAdapter dalam proses dengan aplikasi Java menggunakan mTLS, kunci klien Anda harus menggunakan format PKCS#8.

Untuk membuat koneksi mTLS dalam proses, gunakan konfigurasi ini:

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

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