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 sidecar (misalnya, di 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 berjalan. 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:

Memilih metode untuk menjalankan PGAdapter

Anda dapat memulai PGAdapter sebagai proses mandiri, dalam penampung 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 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 dalam format JSON, lihat Membuat akun layanan.

Pastikan Anda memberikan kredensial yang memadai kepada akun layanan untuk mengakses database.

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

gcloud auth application-default login

Untuk informasi selengkapnya, lihat Menyiapkan autentikasi dan otorisasi.

-s port
Port yang diproses PGAdapter. Setelan defaultnya adalah 5432 (port PostgreSQL default).
-v version_number

Nomor versi PostgreSQL yang akan ditampilkan 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. Lihat Driver dan Klien untuk mengetahui daftar lengkap klien yang didukung.

-x

Mengaktifkan koneksi dari host selain localhost. Jangan gunakan saat memulai PGAdapter dalam mode mandiri. Hanya gunakan saat memulai dalam penampung Docker.

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

Contoh sederhana berikut memulai PGAdapter dalam mode mandiri di 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 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 cocok dengan cara PGAdapter dikonfigurasi di dalam penampung. Nilai defaultnya adalah 5432. HOST-PORT adalah port yang harus diproses Docker di luar penampung untuk permintaan koneksi. Port ini harus selalu tersedia di localhost.

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

-v CREDENTIALS_FILE_PATH:in_container_mount_point

Opsi Docker ini mengikat pemasangan volume bersama. Tindakan ini memetakan jalur host di luar penampung ke volume (titik pemasangan) di dalam penampung. Jalur host dan penampung dipisahkan dengan titik dua (:).

Opsi ini memungkinkan PGAdapter mengakses file kredensial JSON yang berada di luar penampung. Pada contoh sebelumnya, opsi -c mereferensikan titik pemasangan dalam penampung. Contoh ini memberi nama titik pemasangan dalam penampung /acct_credentials.json. Anda dapat memberinya nama apa pun.

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

-x

Mengaktifkan koneksi dari host selain localhost. Hal ini diperlukan karena port di dalam penampung yang dipetakan ke port host tidak muncul di PGAdapter sebagai localhost.

Opsi berikut bersifat opsional:

-r databaseRole=database_role
Peran database yang akan digunakan untuk sesi. Untuk informasi selengkapnya, lihat Otorisasi dengan PGAdapter.

Dalam 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 Anda dapat men-deploy-nya sebagai proxy sidecar.

Sebaiknya jalankan PGAdapter dalam pola sidecar daripada menjalankannya sebagai layanan terpisah karena alasan berikut:
  • Mencegah titik tunggal kegagalan. Akses setiap aplikasi ke database Anda independen dari yang lain, sehingga lebih tangguh.
  • Jumlah instance PGAdapter secara otomatis diskalakan secara linear dengan jumlah instance aplikasi.

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

File konfigurasi berikut menunjukkan cara menambahkan PGAdapter sebagai proxy sidecar 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 Sidecar

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

Sebaiknya jalankan PGAdapter dalam pola sidecar, bukan menjalankannya sebagai layanan terpisah karena alasan berikut:

  • Mencegah titik tunggal kegagalan. Akses setiap aplikasi ke database Anda independen dari yang lain, sehingga lebih tangguh.
  • Karena PGAdapter menggunakan resource dalam hubungan linear dengan penggunaan, pola ini memungkinkan Anda menentukan cakupan dan meminta resource secara lebih akurat agar sesuai dengan aplikasi Anda saat diskalakan.

File konfigurasi berikut menunjukkan cara menambahkan PGAdapter sebagai proxy sidecar 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 menyertakan petunjuk untuk menggunakan Workload Identity Federation for GKE dengan PGAdapter.

Java In-process

Buat dan mulai instance PGAdapter dengan kode Java Anda. Ini adalah penyiapan yang direkomendasikan untuk aplikasi Java.

Jika Anda menggunakan akun layanan untuk autentikasi, pastikan 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. 
    2. <dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-spanner-pgadapter</artifactId>
  <version>0.41.0</version>
</dependency>
  • Build 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