PGAdapter를 사용하여 연결

이 문서에서는 PGAdapter를 사용하여 Spanner Omni에 연결하는 방법을 설명합니다. PGAdapter를 구성하여 보안 연결을 설정합니다. PGAdapter는 일반 텍스트, 전송 계층 보안 (TLS), 사용자 인증 정보가 있는 TLS, 및 상호 TLS (mTLS) 연결을 지원합니다. 이러한 보안 구성은 다양한 수준의 암호화 및 인증을 제공하여 전송 중에 데이터를 보호합니다. 각 구성에는 데이터 무결성 및 기밀성을 보장하기 위한 특정 클라이언트 설정이 필요합니다.

PGAdapter를 독립형 프로세스로 실행하거나 애플리케이션에 직접 통합할 수 있습니다. 대화형 관리 및 수동 쿼리 실행의 경우 psql과 같은 표준 PostgreSQL 도구를 사용하여 데이터베이스에 연결합니다. 자동화된 애플리케이션을 빌드하려면 다음과 같은 PostgreSQL 호환 드라이버를 사용하세요.

이러한 드라이버 중 일부를 사용하는 코드 샘플은 이 문서의 샘플 코드를 참조하세요.

시작하기 전에

Spanner Omni에서 PGAdapter를 사용하려면 PGAdapter 버전 0.55.2 이상을 사용하세요.

BOM (Bill of Materials) 없이 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 통신은 전송 계층 보안 (TLS)을 사용하여 암호화됩니다. 이 구성을 사용하려면 Java truststore 구성에 설명된 대로 Spanner Omni CA 인증서를 Java truststore에 추가해야 합니다.
사용자 인증 정보가 있는 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 연결을 구성하려면 Spanner Omni CA 인증서를 Java truststore에 추가해야 합니다. 자세한 내용은 Java truststore 구성을 참고하세요.

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 사용자 이름

애플리케이션을 사용한 In-process 실행

애플리케이션을 사용한 In-process로 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 truststore 구성에 설명된 대로 CA 인증서를 Java truststore에 추가하고 다음 구성을 사용합니다.

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 애플리케이션을 사용한 In-process로 PGAdapter를 시작하려면 클라이언트 키가 PKCS#8 형식을 사용해야 합니다.

In-process로 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 데이터베이스에 연결하는 것처럼 PostgreSQL JDBC 드라이버를 사용하여 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)

PostgreSQL 데이터베이스에 연결하는 것처럼 pgx를 사용하여 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();