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 portHOST-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.
-
Tambahkan
google-cloud-spanner-pgadapter
sebagai dependensi ke project Anda. Untuk mengetahui detailnya, lihat Mendapatkan PGAdapter. - Build server menggunakan class
com.google.cloud.spanner.pgadapter.ProxyServer
. - 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
/**
* 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
Kecuali dinyatakan lain, konten di halaman ini dilisensikan berdasarkan Lisensi Creative Commons Attribution 4.0, sedangkan contoh kode dilisensikan berdasarkan Lisensi Apache 2.0. Untuk mengetahui informasi selengkapnya, lihat Kebijakan Situs Google Developers. Java adalah merek dagang terdaftar dari Oracle dan/atau afiliasinya.
Terakhir diperbarui pada 2024-11-28 UTC.