Tujuan
Tutorial ini memandu Anda melakukan langkah-langkah berikut menggunakan proxy lokal Spanner PGAdapter untuk driver PostgreSQL:
- Membuat instance dan database Spanner.
- Menulis, membaca, dan mengeksekusi kueri SQL pada data dalam {i>database<i}.
- Perbarui skema database.
- Memperbarui data menggunakan transaksi baca-tulis.
- Tambahkan indeks sekunder ke database.
- Menggunakan indeks untuk membaca dan mengeksekusi kueri SQL pada data.
- Mengambil data menggunakan transaksi hanya baca.
Biaya
Tutorial ini menggunakan Spanner, yang merupakan komponen Google Cloud yang dapat ditagih. Untuk mengetahui informasi tentang biaya penggunaan Spanner, lihat Harga.
Sebelum memulai
Selesaikan langkah-langkah yang dijelaskan dalam Penyiapan, yang mencakup pembuatan dan penetapan project Google Cloud default, mengaktifkan penagihan, mengaktifkan Cloud Spanner API, dan menyiapkan OAuth 2.0 untuk mendapatkan kredensial autentikasi agar dapat menggunakan Cloud Spanner API.
Secara khusus, pastikan Anda menjalankan gcloud auth
application-default login
untuk menyiapkan lingkungan pengembangan lokal dengan kredensial
autentikasi.
Menyiapkan lingkungan PGAdapter lokal
Anda dapat menggunakan driver PostgreSQL bersama dengan PGAdapter untuk terhubung ke Spanner. PGAdapter adalah proxy lokal yang menerjemahkan protokol jaringan PostgreSQL ke protokol gRPC Spanner.
PGAdapter memerlukan Java atau Docker agar dapat berjalan.
Instal salah satu dari aplikasi berikut di mesin pengembangan jika tidak ada yang terinstal:
Clone repositori aplikasi contoh ke komputer lokal Anda:
git clone https://github.com/GoogleCloudPlatform/pgadapter.git
Ubah ke direktori yang berisi kode contoh Spanner:
{i>psql<i}
cd pgadapter/samples/snippets/psql-snippets
Java
cd pgadapter/samples/snippets/java-snippets mvn package -DskipTests
Go
cd pgadapter/samples/snippets/golang-snippets
Node.js
cd pgadapter/samples/snippets/nodejs-snippets npm install
Python
cd pgadapter/samples/snippets/python-snippets python -m venv ./venv pip install -r requirements.txt cd samples
C#
cd pgadapter/samples/snippets/dotnet-snippets
Membuat instance
Saat pertama kali menggunakan Spanner, Anda harus membuat instance, yang merupakan alokasi resource yang digunakan oleh database Spanner. Saat membuat instance, Anda memilih konfigurasi instance, yang menentukan tempat data disimpan, dan juga jumlah node yang akan digunakan, yang menentukan jumlah penayangan dan resource penyimpanan dalam instance Anda.
Jalankan perintah berikut untuk membuat instance Spanner di region us-central1
dengan 1 node:
gcloud spanner instances create test-instance --config=regional-us-central1 \
--description="Test Instance" --nodes=1
Perhatikan bahwa tindakan ini akan membuat instance dengan karakteristik berikut:
- ID Instance
test-instance
- Nama tampilan
Test Instance
- Konfigurasi instance
regional-us-central1
(Konfigurasi regional menyimpan data di satu region, sedangkan konfigurasi multi-region mendistribusikan data di beberapa region. Untuk mengetahui informasi lebih lanjut, lihat artikel Tentang instance.) - Jumlah node 1 (
node_count
sesuai dengan jumlah resource penyajian dan penyimpanan yang tersedia untuk database dalam instance. Pelajari lebih lanjut di Node dan unit pemrosesan.)
Anda akan melihat:
Creating instance...done.
Mencari contoh file
Repositori contoh berisi contoh yang menunjukkan cara menggunakan Spanner dengan PGAdapter.
Periksa foldersamples/snippets
, yang menunjukkan cara menggunakan
Spanner. Kode ini menunjukkan cara membuat dan menggunakan database baru. Data menggunakan skema contoh yang ditampilkan di halaman Model data dan skema.
Memulai PGAdapter
Mulai PGAdapter pada mesin pengembangan lokal Anda dan arahkan ke instance yang Anda buat.
Perintah berikut mengasumsikan bahwa Anda telah menjalankan
gcloud auth application-default login
.
Aplikasi Java
wget https://storage.googleapis.com/pgadapter-jar-releases/pgadapter.tar.gz \
&& tar -xzvf pgadapter.tar.gz
java -jar pgadapter.jar -i test-instance
Docker
docker pull gcr.io/cloud-spanner-pg-adapter/pgadapter
docker run \
--name pgadapter \
--rm -d -p 5432:5432 \
-v "$HOME/.config/gcloud":/gcloud:ro \
--env CLOUDSDK_CONFIG=/gcloud \
gcr.io/cloud-spanner-pg-adapter/pgadapter \
-i test-instance -x
Emulator
docker pull gcr.io/cloud-spanner-pg-adapter/pgadapter-emulator
docker run \
--name pgadapter-emulator \
--rm -d \
-p 5432:5432 \
-p 9010:9010 \
-p 9020:9020 \
gcr.io/cloud-spanner-pg-adapter/pgadapter-emulator
Tindakan ini akan memulai PGAdapter dengan emulator Spanner yang tersemat. Emulator tersemat ini otomatis membuat instance atau database Spanner yang Anda hubungkan tanpa perlu membuatnya secara manual terlebih dahulu.
Sebaiknya jalankan PGAdapter dalam produksi sebagai container side-car atau sebagai dependensi dalam proses. Untuk mengetahui informasi selengkapnya mengenai deployment PGAdapter dalam lingkungan production, lihat Memilih metode untuk menjalankan PGAdapter.
Buat database
Buat database yang disebut example-db
dalam instance bernama test-instance
dengan
menjalankan baris berikut di command line.
gcloud spanner databases create example-db --instance=test-instance \
--database-dialect=POSTGRESQL
Anda akan melihat:
Creating database...done.
Membuat tabel
Kode berikut membuat dua tabel dalam {i>database<i}.
{i>psql<i}
Java
Go
Node.js
Python
C#
Jalankan contoh dengan perintah berikut:
{i>psql<i}
PGDATABASE=example-db ./create_tables.sh example-db
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar createtables example-db
Go
go run sample_runner.go createtables example-db
Node.js
npm start createtables example-db
Python
python create_tables.py example-db
C#
dotnet run createtables example-db
Langkah selanjutnya adalah menulis data ke database Anda.
Membuat koneksi
Sebelum dapat melakukan pembacaan atau penulisan, Anda harus membuat koneksi ke PGAdapter. Semua interaksi Anda dengan Spanner harus melaluiConnection
. Nama database ditentukan dalam string koneksi.
{i>psql<i}
Java
Go
Node.js
Python
C#
Jalankan contoh dengan perintah berikut:
{i>psql<i}
PGDATABASE=example-db ./create_connection.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar createconnection example-db
Go
go run sample_runner.go createconnection example-db
Node.js
npm start createconnection example-db
Python
python create_connection.py example-db
C#
dotnet run createconnection example-db
Menulis data dengan DML
Anda dapat menyisipkan data menggunakan Data Manipulation Language (DML) dalam transaksi baca-tulis.
Contoh ini menunjukkan cara mengeksekusi pernyataan DML di Spanner menggunakan driver PostgreSQL.
{i>psql<i}
Java
Go
Node.js
Python
C#
Jalankan contoh dengan perintah berikut:
{i>psql<i}
PGDATABASE=example-db ./write_data_with_dml.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar writeusingdml example-db
Go
go run sample_runner.go writeusingdml example-db
Node.js
npm start writeusingdml example-db
Python
python write_data_with_dml.py example-db
C#
dotnet run writeusingdml example-db
Anda akan melihat respons berikut:
4 records inserted.
Menulis data dengan batch DML
PGAdapter mendukung eksekusi batch DML. Mengirim beberapa pernyataan DML dalam satu batch akan mengurangi jumlah perjalanan bolak-balik ke Spanner dan meningkatkan performa aplikasi Anda.
{i>psql<i}
Java
Go
Node.js
Python
C#
Jalankan contoh dengan perintah berikut:
{i>psql<i}
PGDATABASE=example-db ./write_data_with_dml_batch.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar writeusingdmlbatch example-db
Go
go run sample_runner.go writeusingdmlbatch example-db
Node.js
npm start writeusingdmlbatch example-db
Python
python write_data_with_dml_batch.py example-db
C#
dotnet run writeusingdmlbatch example-db
Anda akan melihat:
3 records inserted.
Menulis data dengan mutasi
Anda juga dapat menyisipkan data menggunakan mutasi.
PGAdapter menerjemahkan perintah COPY
PostgreSQL menjadi
mutasi. Menggunakan COPY
adalah cara paling efisien untuk menyisipkan data dengan cepat di
database Spanner Anda.
Operasi COPY
bersifat atomik secara default. Operasi atomik di
Spanner dibatasi oleh batas ukuran commit.
Lihat batas CRUD untuk informasi selengkapnya.
Contoh ini menunjukkan cara mengeksekusi operasi COPY
non-atomik. Hal ini memungkinkan operasi COPY
melebihi batas ukuran commit.
{i>psql<i}
Java
Go
Node.js
Python
C#
Jalankan contoh dengan perintah berikut:
{i>psql<i}
PGDATABASE=example-db ./write_data_with_copy.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar write example-db
Go
go run sample_runner.go write example-db
Node.js
npm start write example-db
Python
python write_data_with_copy.py example-db
C#
dotnet run write example-db
Anda akan melihat:
Copied 5 singers
Copied 5 albums
Membuat kueri data menggunakan SQL
Spanner mendukung antarmuka SQL untuk membaca data, yang dapat Anda akses dari command line menggunakan Google Cloud CLI atau secara terprogram menggunakan driver PostgreSQL.
Pada command line
Jalankan pernyataan SQL berikut untuk membaca nilai semua kolom dari
tabel Albums
:
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='SELECT singer_id, album_id, album_title FROM albums'
Hasilnya seharusnya:
SingerId AlbumId AlbumTitle
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
Menggunakan driver PostgreSQL
Selain mengeksekusi pernyataan SQL di command line, Anda dapat mengeluarkan pernyataan SQL yang sama secara terprogram menggunakan driver PostgreSQL.
{i>psql<i}
Java
Go
Node.js
Python
C#
Jalankan contoh dengan perintah berikut:
{i>psql<i}
PGDATABASE=example-db ./query_data.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar query example-db
Go
go run sample_runner.go query example-db
Node.js
npm start query example-db
Python
python query_data.py example-db
C#
dotnet run query example-db
Anda akan melihat hasil berikut:
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
Kueri menggunakan parameter SQL
Jika aplikasi Anda memiliki kueri yang sering dijalankan, Anda dapat meningkatkan performanya dengan membuat parameter pada kueri tersebut. Kueri parametrik yang dihasilkan dapat disimpan dalam cache dan digunakan kembali, sehingga mengurangi biaya kompilasi. Untuk informasi selengkapnya, lihat Menggunakan parameter kueri untuk mempercepat kueri yang sering dijalankan.
Berikut adalah contoh penggunaan parameter dalam klausa WHERE
untuk
mengueri data yang berisi nilai tertentu untuk LastName
.
{i>psql<i}
Java
Go
Node.js
Python
C#
Jalankan contoh dengan perintah berikut:
{i>psql<i}
PGDATABASE=example-db ./query_data_with_parameter.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar querywithparameter example-db
Go
go run sample_runner.go querywithparameter example-db
Node.js
npm start querywithparameter example-db
Python
python query_data_with_parameter.py example-db
C#
dotnet run querywithparameter example-db
Anda akan melihat hasil berikut:
12 Melissa Garcia
Memperbarui skema database
Asumsikan Anda perlu menambahkan kolom baru bernama MarketingBudget
ke tabel
Albums
. Untuk menambahkan kolom baru ke tabel yang ada, skema database Anda harus diperbarui. Spanner mendukung pembaruan skema pada database sementara database terus menyalurkan traffic. Pembaruan skema tidak memerlukan pembuatan database
secara offline dan pembaruan tersebut tidak mengunci seluruh tabel atau kolom. Anda dapat terus
menulis data ke database selama pembaruan skema. Baca selengkapnya tentang update skema yang didukung dan performa perubahan skema di Membuat pembaruan skema.
Menambahkan kolom
Anda dapat menambahkan kolom pada command line menggunakan Google Cloud CLI atau secara terprogram menggunakan driver PostgreSQL.
Pada command line
Gunakan perintah ALTER TABLE
berikut untuk
menambahkan kolom baru ke tabel:
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE albums ADD COLUMN marketing_budget BIGINT'
Anda akan melihat:
Schema updating...done.
Menggunakan driver PostgreSQL
Jalankan pernyataan DDL menggunakan driver PostgreSQL untuk mengubah skema:
{i>psql<i}
Java
Go
Node.js
Python
C#
Jalankan contoh dengan perintah berikut:
{i>psql<i}
PGDATABASE=example-db ./add_column.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar addmarketingbudget example-db
Go
go run sample_runner.go addmarketingbudget example-db
Node.js
npm start addmarketingbudget example-db
Python
python add_column.py example-db
C#
dotnet run addmarketingbudget example-db
Anda akan melihat:
Added marketing_budget column
Menjalankan batch DDL
Sebaiknya jalankan beberapa modifikasi skema dalam satu batch.
Anda dapat mengeksekusi beberapa pernyataan DDL dalam satu batch menggunakan fitur
pengelompokan bawaan dari driver PostgreSQL, dengan mengirimkan semua pernyataan
DDL sebagai satu string SQL yang dipisahkan oleh titik koma, atau dengan menggunakan
pernyataan START BATCH DDL
dan RUN BATCH
.
{i>psql<i}
Java
Go
Node.js
Python
C#
Jalankan contoh dengan perintah berikut:
{i>psql<i}
PGDATABASE=example-db ./ddl_batch.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar ddlbatch example-db
Go
go run sample_runner.go ddlbatch example-db
Node.js
npm start ddlbatch example-db
Python
python ddl_batch.py example-db
C#
dotnet run ddlbatch example-db
Anda akan melihat:
Added venues and concerts tables
Menulis data ke kolom baru
Kode berikut menulis data ke kolom baru. Fungsi ini menetapkan MarketingBudget
ke
100000
untuk baris yang dikunci oleh Albums(1, 1)
dan ke 500000
untuk baris yang dikunci
oleh Albums(2, 2)
.
COPY
PostgreSQL menjadi
mutasi. Perintah COPY
secara default diterjemahkan ke mutasi Insert
.
Jalankan set spanner.copy_upsert=true
untuk menerjemahkan perintah COPY
menjadi
mutasi InsertOrUpdate
. Metode ini dapat digunakan untuk memperbarui data yang ada di
Spanner.
{i>psql<i}
Java
Go
Node.js
Python
C#
Jalankan contoh dengan perintah berikut:
{i>psql<i}
PGDATABASE=example-db ./update_data_with_copy.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar update example-db
Go
go run sample_runner.go update example-db
Node.js
npm start update example-db
Python
python update_data_with_copy.py example-db
C#
dotnet run update example-db
Anda akan melihat:
Updated 2 albums
Anda juga dapat menjalankan kueri SQL untuk mengambil nilai yang baru saja ditulis.
Berikut adalah kode untuk mengeksekusi kueri:
{i>psql<i}
Java
Go
Node.js
Python
C#
Jalankan kueri dengan perintah ini:
{i>psql<i}
PGDATABASE=example-db ./query_data_with_new_column.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar querymarketingbudget example-db
Go
go run sample_runner.go querymarketingbudget example-db
Node.js
npm start querymarketingbudget example-db
Python
python query_data_with_new_column.py example-db
C#
dotnet run querymarketingbudget example-db
Anda akan melihat:
1 1 100000
1 2 null
2 1 null
2 2 500000
2 3 null
Memperbarui data
Anda dapat memperbarui data menggunakan DML dalam transaksi baca-tulis.
{i>psql<i}
Java
Go
Node.js
Python
C#
Jalankan contoh dengan perintah berikut:
{i>psql<i}
PGDATABASE=example-db ./update_data_with_transaction.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar writewithtransactionusingdml example-db
Go
go run sample_runner.go writewithtransactionusingdml example-db
Node.js
npm start writewithtransactionusingdml example-db
Python
python update_data_with_transaction.py example-db
C#
dotnet run writewithtransactionusingdml example-db
Anda akan melihat:
Transferred marketing budget from Album 2 to Album 1
Tag transaksi dan tag permintaan
Gunakan tag transaksi dan tag permintaan
untuk memecahkan masalah transaksi dan kueri di Spanner. Anda dapat menetapkan tag transaksi dan meminta tag dengan variabel sesi SPANNER.TRANSACTION_TAG
dan SPANNER.STATEMENT_TAG
.
{i>psql<i}
Java
Go
Node.js
Python
C#
Jalankan contoh dengan perintah berikut:
{i>psql<i}
PGDATABASE=example-db ./tags.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar tags example-db
Go
go run sample_runner.go tags example-db
Node.js
npm start tags example-db
Python
python tags.py example-db
C#
dotnet run tags example-db
Mengambil data menggunakan transaksi hanya baca
Misalnya Anda ingin mengeksekusi lebih dari satu pembacaan pada stempel waktu yang sama. Transaksi hanya baca mengamati awalan yang konsisten dari histori commit transaksi, sehingga aplikasi Anda selalu mendapatkan data yang konsisten.
Setel koneksi ke hanya-baca atau gunakan pernyataan SQL SET TRANSACTION READ ONLY
untuk mengeksekusi transaksi hanya baca.
Berikut ini cara menjalankan kueri dan melakukan pembacaan dalam transaksi hanya baca yang sama:
{i>psql<i}
Java
Go
Node.js
Python
C#
Jalankan contoh dengan perintah berikut:
{i>psql<i}
PGDATABASE=example-db ./read_only_transaction.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar readonlytransaction example-db
Go
go run sample_runner.go readonlytransaction example-db
Node.js
npm start readonlytransaction example-db
Python
python read_only_transaction.py example-db
C#
dotnet run readonlytransaction example-db
Anda akan melihat output yang mirip dengan:
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
2 2 Forever Hold Your Peace
1 2 Go, Go, Go
2 1 Green
2 3 Terrified
1 1 Total Junk
Kueri yang dipartisi dan Data Boost
partitionQuery
API membagi kueri menjadi bagian yang lebih kecil, atau partisi, dan menggunakan beberapa
mesin untuk mengambil partisi secara paralel. Setiap partisi diidentifikasi oleh token partisi. PartitionQuery API memiliki latensi yang lebih tinggi daripada API kueri standar, karena hanya ditujukan untuk operasi massal seperti mengekspor atau memindai seluruh database.
Peningkatan Data memungkinkan Anda menjalankan kueri analisis dan ekspor data dengan dampak nyaris nol terhadap beban kerja yang ada pada instance Spanner yang disediakan. Data Boost hanya mendukung kueri yang dipartisi.
{i>psql<i}
Java
Go
Node.js
Python
C#
Jalankan contoh dengan perintah berikut:
{i>psql<i}
PGDATABASE=example-db ./data_boost.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar databoost example-db
Go
go run sample_runner.go databoost example-db
Node.js
npm start databoost example-db
Python
python data_boost.py example-db
C#
dotnet run databoost example-db
Untuk informasi selengkapnya tentang menjalankan kueri yang dipartisi dan menggunakan Data Boost dengan PGAdapter, lihat: Pernyataan kueri yang dipartisi dan Peningkatan Data
DML yang dipartisi
Partitioned Data Manipulation Language (DML) dirancang untuk jenis update dan penghapusan massal berikut:
- Pembersihan berkala dan pembersihan sampah memori.
- Mengisi ulang kolom baru dengan nilai default.
{i>psql<i}
Java
Go
Node.js
Python
C#
Jalankan contoh dengan perintah berikut:
{i>psql<i}
PGDATABASE=example-db ./partitioned_dml.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar partitioneddml example-db
Go
go run sample_runner.go partitioneddml example-db
Node.js
npm start partitioneddml example-db
Python
python partitioned_dml.py example-db
C#
dotnet run datpartitioneddmlboost example-db
Pembersihan
Agar tidak menimbulkan biaya tambahan pada akun Penagihan Cloud Anda untuk resource yang digunakan dalam tutorial ini, hapus database dan hapus instance yang Anda buat.
Menghapus database
Jika instance dihapus, semua database di dalamnya akan dihapus secara otomatis. Langkah ini menunjukkan cara menghapus database tanpa menghapus instance (Anda masih akan dikenai biaya untuk instance tersebut).
Pada command line
gcloud spanner databases delete example-db --instance=test-instance
Menggunakan Konsol Google Cloud
Buka halaman Spanner Instances di konsol Google Cloud.
Klik instance.
Klik database yang ingin dihapus.
Di halaman Database details, klik Delete.
Konfirmasi bahwa Anda ingin menghapus database, lalu klik Delete.
Menghapus instance
Jika sebuah instance dihapus, semua database yang dibuat dalam instance tersebut akan otomatis dihapus.
Pada command line
gcloud spanner instances delete test-instance
Menggunakan Konsol Google Cloud
Buka halaman Spanner Instances di konsol Google Cloud.
Klik instance Anda.
Klik Delete.
Konfirmasi bahwa Anda ingin menghapus instance, lalu klik Hapus.
Langkah selanjutnya
Pelajari cara mengakses Spanner dengan instance virtual machine.
Pelajari kredensial autentikasi dan autentikasi di Melakukan autentikasi ke layanan Cloud menggunakan library klien.
Pelajari Praktik terbaik desain skema Spanner lebih lanjut.