PGAdapter を使用して接続する

このドキュメントでは、PGAdapter を使用して Spanner Omni に接続する方法について説明します。安全な接続を確立するように PGAdapter を構成します。PGAdapter は、プレーン テキスト、Transport Layer Security（TLS）、認証情報付きの TLS、相互 TLS（mTLS）接続をサポートしています。これらのセキュリティ構成は、さまざまなレベルの暗号化と認証を提供することで、送信中のデータを保護します。各構成では、データの完全性と機密性を確保するために、特定のクライアント設定が必要です。

PGAdapter は、スタンドアロン プロセスとして実行することも、アプリケーションに直接統合することもできます。インタラクティブな管理と手動クエリの実行を行うには、psql などの標準の PostgreSQL ツールを使用してデータベースに接続します。自動化されたアプリケーションを構築するには、次のような PostgreSQL 互換ドライバを使用します。

これらのドライバの一部を使用するコードサンプルについては、このドキュメントのコードサンプルをご覧ください。

始める前に

Spanner Omni で PGAdapter を使用するには、PGAdapter バージョン 0.55.2 以降を使用します。

部品構成表（BOM）なしで Maven を使用する場合は、pom.xml ファイルの依存関係に以下を追加します。

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

セキュリティ構成

Spanner Omni PGAdapter は、PGAdapter とデータベース間の通信の暗号化と認証の方法を定義する 4 つのセキュリティ構成をサポートしています。これらの構成を使用するには、次の表に示すクライアント オプションを設定します。

セキュリティの構成 説明
書式なしテキスト 通信は暗号化されません。
TLS 通信は Transport Layer Security（TLS）を使用して暗号化されます。この構成では、Java トラストストアを構成するで説明されているように、Spanner Omni CA 証明書を Java トラストストアに追加する必要があります。
認証情報を使用した TLS 通信は TLS で暗号化され、認証はユーザー名とパスワードを使用して行われます。
mTLS 通信は相互 TLS（mTLS）を使用して暗号化されます。この構成では、クライアント証明書とクライアント秘密鍵の両方を指定する必要があります。

スタンドアロン プロセスとして実行する

手動でデータベースを操作する必要がある場合は、Java 以外のアプリケーションや標準の PostgreSQL ツール（psql など）で PGAdapter をスタンドアロン プロセスとして実行します。このアプローチでは、プロキシがアプリケーション ライフサイクルから切り離されるため、個別に管理および更新できます。PGAdapter をスタンドアロン プロセスとして起動するには、選択したセキュリティ構成に基づいて次の構成方法を使用します。

書式なしテキスト

プレーン テキスト通信で PGAdapter を起動するには、次のコマンドを実行します。

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

次のように置き換えます。

  • DATABASE_ID: Spanner Omni データベースの ID（例: test-db）。

  • ENDPOINT: Spanner Omni インスタンスのエンドポイント（例: localhost:15000）。

TLS

TLS を使用して PGAdapter 接続を構成するには、Java トラストストアを構成するで説明されているように、Spanner Omni CA 証明書を Java トラストストアに追加する必要があります。

TLS を使用して PGAdapter を起動するには、次のコマンドを実行します。

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

mTLS を使用して PGAdapter を起動する前に、クライアント鍵が 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 形式で鍵を生成します。

mTLS を使用して PGAdapter を起動するには、次のコマンドを実行します。

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: PGAdapter が実行されているマシンのホスト名または IP アドレス。ローカルで実行している場合は、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 接続を確立するには、Java トラストストアを構成するの説明に従って CA 証明書を 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

mTLS を使用して Java アプリケーションで PGAdapter をプロセス内で起動するには、クライアント鍵に 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();

サンプルコード

このセクションでは、次の PostgreSQL 互換ドライバを使用して Spanner Omni データベースに接続するためのサンプルコードを示します。

接続文字列の次のプレースホルダを置き換えます。

  • PASSWORD: PostgreSQL ユーザーのパスワード。

JDBC

PostgreSQL JDBC ドライバを使用して、PostgreSQL データベースに接続するのと同じように PGAdapter に接続できます。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）

pgx を使用して、PostgreSQL データベースに接続するのと同じように PGAdapter に接続できます。次のサンプルコードを使用します。

// 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）

PostgreSQL データベースに接続する場合と同様に、psycopg2 または psycopg3 を使用して PGAdapter に接続できます。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）

PostgreSQL データベースに接続する場合と同様に、node-postgres を使用して PGAdapter に接続できます。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();