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:
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 portHOST-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.
-
Tambahkan
google-cloud-spanner-pgadapter
sebagai dependensi ke project Anda. Untuk mengetahui detailnya, lihat Mendapatkan PGAdapter. - 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