Memulai PGAdapter

Halaman ini menjelaskan cara memulai PGAdapter di Spanner. Untuk mempelajari PGAdapter, lihat Tentang PGAdapter. Untuk mendapatkan biner PGAdapter, lihat Mendapatkan PGAdapter.

Anda dapat memulai PGAdapter dengan cara berikut:

• Sebagai proses mandiri
• Dalam container Docker
• Di Cloud Run
• Menggunakan PGAdapter sebagai proxy file bantuan (misalnya, dalam cluster Kubernetes)
• Dalam proses dengan aplikasi Java Anda

Sebelum memulai

Sebelum memulai PGAdapter, pastikan Anda telah melakukan autentikasi dengan akun pengguna atau akun layanan di komputer tempat PGAdapter akan dijalankan. Jika menggunakan akun layanan, Anda harus mengetahui lokasi file kunci JSON (file kredensial). Kemudian, Anda dapat menentukan jalur kredensial dengan opsi -c PGAdapter, atau dengan menetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS.

Untuk informasi selengkapnya, lihat:

• Ringkasan autentikasi
• Memberi otorisasi gcloud CLI

Memilih metode untuk menjalankan PGAdapter

Anda dapat memulai PGAdapter sebagai proses mandiri, dalam container Docker, di Cloud Run, atau dalam proses dengan aplikasi Java Anda. Saat memulai PGAdapter, Anda menentukan project, instance Spanner, dan database yang akan dihubungkan. Anda juga dapat menentukan jalur untuk file kredensial berformat JSON (file kunci).

Mandiri

Download PGAdapter dengan perintah berikut.

wget https://storage.googleapis.com/pgadapter-jar-releases/pgadapter.tar.gz \
  && tar -xzvf pgadapter.tar.gz

Mulai PGAdapter dengan perintah berikut.

java -jar pgadapter.jar -p PROJECT_NAME -i INSTANCE_NAME -d DATABASE_NAME \
  -c CREDENTIALS_FILE_PATH \
  ADDITIONAL_OPTIONS

Opsi berikut diperlukan:

-p project_name

Nama project tempat database Spanner berjalan.

-i instance_name

Nama instance Spanner.

-d database_name

Nama database yang akan dihubungkan.

Opsi berikut bersifat opsional:

-r databaseRole=database_role

Peran database yang akan digunakan untuk sesi. Untuk mengetahui informasi selengkapnya, lihat Otorisasi dengan PGAdapter.

-c credentials_file_path

Jalur lengkap untuk file kunci yang berisi kredensial akun layanan dalam format JSON. Jika opsi ini tidak ditetapkan, kredensial akan dibaca dari jalur yang ditentukan oleh variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS.

Untuk mempelajari cara membuat akun layanan dan mendownload file kunci berformat JSON, lihat Membuat akun layanan.

Pastikan Anda memberi akun layanan kredensial yang memadai untuk mengakses database.

Anda dapat menghilangkan opsi ini jika Anda terlebih dahulu melakukan autentikasi dengan Google Cloud CLI menggunakan perintah berikut:

gcloud auth application-default login

Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi dan otorisasi.

-s port

Port

yang menjadi tempat pemrosesan PGAdapter. Default-nya adalah 5432 (port PostgreSQL default).

-v version_number

Nomor versi PostgreSQL yang akan diekspos ke klien selama koneksi. Nilai defaultnya adalah 14,1

Beberapa aplikasi dan driver PostgreSQL mengaktifkan fitur tambahan bergantung pada nomor versi ini. Spanner mungkin tidak mendukung fitur ini. Baca Driver dan Klien untuk mengetahui daftar lengkap klien yang didukung.

-x

Mengaktifkan koneksi dari {i>host<i} selain {i>localhost<i}. Jangan gunakan saat memulai PGAdapter dalam mode mandiri. Hanya gunakan ketika memulai dari dalam container Docker.

Secara default, sebagai langkah keamanan, PGAdapter hanya menerima koneksi dari localhost.

Contoh sederhana berikut memulai PGAdapter dalam mode mandiri pada port 5432 menggunakan kredensial aplikasi default.

java -jar pgadapter.jar \
  -p my-project \
  -i my-instance \
  -d my-database \
  -s 5432
            

Docker

Mulai PGAdapter dengan perintah berikut.

docker run -d -p HOST-PORT:DOCKER-PORT \
    -v CREDENTIALS_FILE_PATH:/acct_credentials.json \
    gcr.io/cloud-spanner-pg-adapter/pgadapter:latest \
    -p PROJECT_NAME -i INSTANCE_NAME -d DATABASE_NAME  \
    -c /acct_credentials.json -x OTHER_PGAdapter_OPTIONS

Selain opsi PGAdapter untuk menentukan project, instance, database, dan kredensial, opsi berikut juga diperlukan:

-p 127.0.0.1:HOST-PORT:DOCKER-PORT

Opsi Docker ini memetakan port DOCKER-PORT di dalam container Docker ke port HOST-PORT di luar container. DOCKER-PORT harus sesuai dengan cara PGAdapter dikonfigurasi di dalam container. Nilai defaultnya adalah 5432. HOST-PORT adalah port yang harus dipantau Docker di luar container untuk permintaan koneksi. Alamat ini harus selalu menjadi porta yang tersedia di localhost.

Untuk mengetahui informasi selengkapnya, lihat Memublikasikan atau mengekspos port (-p, --expose) dalam dokumentasi Docker.

-v CREDENTIALS_FILE_PATH:in_container_mount_point

Opsi Docker ini memasang volume bersama. Fungsi ini memetakan jalur host di luar container ke volume (titik pemasangan) di dalam container. Jalur host dan container dipisahkan dengan titik dua (:).

Opsi ini memungkinkan PGAdapter mengakses file kredensial JSON yang berada di luar container. Dalam contoh sebelumnya, opsi -c merujuk ke titik pemasangan dalam container. Contoh ini menamai direktori pemasangan dalam container /acct_credentials.json. Anda dapat menamainya sesuai keinginan Anda.

Untuk informasi selengkapnya, lihat VOLUME (sistem file bersama) di dokumentasi Docker.

-x

Mengaktifkan koneksi dari {i>host<i} selain {i>localhost<i}. Hal ini diperlukan karena orang dalam port dalam container yang dipetakan ke port host tidak tampak di PGAdapter sebagai localhost.

Opsi berikut bersifat opsional:

-r databaseRole=database_role

Peran database yang akan digunakan untuk sesi. Untuk mengetahui informasi selengkapnya, lihat Otorisasi dengan PGAdapter.

Pada contoh berikut, port Docker dan port host ditetapkan ke port default layanan database PostgreSQL 5432.

docker run -d -p 127.0.0.1:5432:5432 \
    -v /tmp/credentials.json:/acct_credentials.json \
    gcr.io/cloud-spanner-pg-adapter/pgadapter:latest \
    -p my_project -i my_instance -d my_database \
    -c /acct_credentials.json -x

Cloud Run

Anda tidak dapat men-deploy PGAdapter sebagai layanan mandiri di Cloud Run, tetapi dapat men-deploy-nya sebagai proxy file bantuan.

Menjalankan PGAdapter dalam pola file bantuan lebih direkomendasikan daripada menjalankannya sebagai layanan terpisah karena alasan berikut:

• Mencegah satu titik kegagalan. Akses setiap aplikasi ke database Anda bersifat independen, sehingga membuatnya lebih tangguh.
• Jumlah instance PGAdapter secara otomatis diskalakan secara linear dengan jumlah instance aplikasi.

Repositori GitHub PGAdapter berisi beberapa aplikasi contoh berfungsi yang menggunakan Cloud Run dan PGAdapter sebagai proxy file bantuan untuk berbagai bahasa pemrograman.

File konfigurasi berikut menunjukkan cara menambahkan PGAdapter sebagai proxy file bantuan ke Cloud Run:

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  annotations:
    # This example uses an in-memory volume for Unix domain sockets.
    # This is a Cloud Run beta feature.
    run.googleapis.com/launch-stage: BETA
  name: pgadapter-sidecar-example
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/execution-environment: gen1
        # This registers 'pgadapter' as a dependency of 'app' and ensures that pgadapter starts
        # before the app container.
        run.googleapis.com/container-dependencies: '{"app":["pgadapter"]}'
    spec:
      # Create an in-memory volume that can be used for Unix domain sockets.
      volumes:
        - name: sockets-dir
          emptyDir:
            # This directory contains the virtual socket files that are used to
            # communicate between your application and PGAdapter.
            sizeLimit: 50Mi
            medium: Memory
      containers:
        # This is the main application container.
        - name: app
          # Example: europe-north1-docker.pkg.dev/my-test-project/cloud-run-source-deploy/pgadapter-sidecar-example
          image: MY-REGION.pkg.dev/MY-PROJECT/cloud-run-source-deploy/pgadapter-sidecar-example
          # The PGADAPTER_HOST variable is set to point to /sockets, which is the shared in-memory
          # volume that is used for Unix domain sockets.
          env:
            - name: SPANNER_PROJECT
              value: my-project
            - name: SPANNER_INSTANCE
              value: my-instance
            - name: SPANNER_DATABASE
              value: my-database
            - name: PGADAPTER_HOST
              value: /sockets
            - name: PGADAPTER_PORT
              value: "5432"
          ports:
            - containerPort: 8080
          volumeMounts:
            - mountPath: /sockets
              name: sockets-dir
        # This is the PGAdapter sidecar container.
        - name: pgadapter
          image: gcr.io/cloud-spanner-pg-adapter/pgadapter
          volumeMounts:
            - mountPath: /sockets
              name: sockets-dir
          args:
            - -dir /sockets
            - -x
          # Add a startup probe that checks that PGAdapter is listening on port 5432.
          startupProbe:
            initialDelaySeconds: 10
            timeoutSeconds: 10
            periodSeconds: 10
            failureThreshold: 3
            tcpSocket:
              port: 5432
          

Proxy File Bantuan

Anda dapat menggunakan PGAdapter sebagai proxy file bantuan di, misalnya, cluster Kubernetes. Container file bantuan Kubernetes berjalan secara paralel dengan container utama dalam pod.

Menjalankan PGAdapter dalam pola bantuan lebih direkomendasikan daripada menjalankannya sebagai layanan terpisah karena alasan berikut:

• Mencegah satu titik kegagalan. Akses setiap aplikasi ke database Anda bersifat independen dari yang lain, sehingga membuatnya lebih tangguh.
• Karena PGAdapter menggunakan resource dalam kaitannya dengan penggunaan yang linear, pola ini memungkinkan Anda membuat cakupan dan meminta resource secara lebih akurat agar sesuai dengan aplikasi Anda seiring penskalaannya.

File konfigurasi berikut menunjukkan cara menambahkan PGAdapter sebagai proxy bantuan ke cluster Kubernetes Anda:

containers:
- name: pgadapter
  image: gcr.io/cloud-spanner-pg-adapter/pgadapter
  ports:
    - containerPort: 5432
  args:
    - "-p my-project"
    - "-i my-instance"
    - "-d my-database"
    - "-x"
  resources:
    requests:
      # PGAdapter's memory use scales linearly with the number of active
      # connections. Fewer open connections will use less memory. Adjust
      # this value based on your application's requirements.
      memory: "512Mi"
      # PGAdapter's CPU use scales linearly with the amount of IO between
      # the database and the application. Adjust this value based on your
      # application's requirements.
      cpu: "1"

Repositori GitHub PGAdapter berisi panduan langkah demi langkah dan aplikasi contoh. Contoh ini mencakup petunjuk untuk menggunakan Workload Identity dengan PGAdapter.

Dalam Proses Java

Membuat dan memulai instance PGAdapter dengan kode Java Anda. Ini adalah penyiapan yang disarankan untuk aplikasi Java.

Jika Anda menggunakan akun layanan untuk autentikasi, pastikan bahwa variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ditetapkan ke jalur file kredensial.

1. Tambahkan google-cloud-spanner-pgadapter sebagai dependensi ke project Anda. Untuk mengetahui detailnya, lihat Mendapatkan PGAdapter.

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

2. Bangun server menggunakan class com.google.cloud.spanner.pgadapter.ProxyServer.

/**
  * Starts PGAdapter in-process and returns a reference to the server. Use this reference to
  * gracefully shut down the server when your application shuts down.
  *
  * @param project the Google Cloud project that PGAdapter should connect to
  * @param instance the Spanner instance that PGAdapter should connect to
  * @param credentialsFile the full path of a credentials file that PGAdapter should use, or 
  *     null if PGAdapter should use the application default credentials
  */
static Server startPGAdapter(String project, String instance, String credentialsFile) {
  OptionsMetadata.Builder builder =
      OptionsMetadata.newBuilder()
          .setProject(project)
          .setInstance(instance)
          // Start PGAdapter on any available port.
          .setPort(0);
  if (credentialsFile != null) {
    builder.setCredentialsFile(credentialsFile);
  }
  ProxyServer server = new ProxyServer(builder.build());
  server.startServer();
  server.awaitRunning();

  return new PGAdapter(server);
}
              

Repositori GitHub PGAdapter berisi aplikasi contoh lengkap.

Langkah selanjutnya

• Menghubungkan psql ke database PostgreSQL
• Menghubungkan JDBC ke database PostgreSQL
• Menghubungkan pgx ke database PostgreSQL
• Menghubungkan psycopg2 ke database PostgreSQL
• Menghubungkan psycopg3 ke database PostgreSQL
• Menghubungkan node-postgres ke database PostgreSQL