Tujuan
Tutorial ini akan memandu Anda melalui langkah-langkah berikut menggunakan library klien Spanner untuk C++:
- Buat instance dan database Spanner.
- Menulis, membaca, dan menjalankan kueri SQL pada data di database.
- Perbarui skema database.
- Perbarui data menggunakan transaksi baca-tulis.
- Tambahkan indeks sekunder ke database.
- Gunakan indeks untuk membaca dan menjalankan kueri SQL pada data.
- Mengambil data menggunakan transaksi hanya baca.
Biaya
Tutorial ini menggunakan Spanner, yang merupakan komponenGoogle Cloudyang dapat ditagih. Untuk mengetahui informasi tentang biaya penggunaan Spanner, lihat Harga.
Sebelum memulai
Selesaikan langkah-langkah yang dijelaskan dalam Menyiapkan, yang mencakup pembuatan dan penetapan project Google Cloud default, pengaktifan penagihan, pengaktifan Cloud Spanner API, dan penyiapan OAuth 2.0 untuk mendapatkan kredensial autentikasi guna menggunakan Cloud Spanner API.
Khususnya, pastikan Anda menjalankan gcloud auth
application-default login
untuk menyiapkan lingkungan pengembangan lokal dengan kredensial
autentikasi.
Menyiapkan lingkungan C++ lokal Anda
Clone repositori aplikasi contoh ke komputer lokal Anda:
git clone https://github.com/googleapis/google-cloud-cpp $HOME/google-cloud-cpp
Instal Bazel untuk Linux menggunakan petunjuk ini.
Ubah ke direktori yang berisi kode contoh Spanner:
cd $HOME/google-cloud-cpp
Bangun sampel dengan perintah ini:
bazel build //google/cloud/spanner/samples:samples
Siapkan autentikasi dan otorisasi untuk project
google-cloud-cpp
.gcloud auth application-default login
Buat variabel lingkungan bernama
GCLOUD_PROJECT
. Ganti [MY_PROJECT_ID] dengan Google Cloud project ID Anda. Anda dapat menemukan ID ini di halaman Selamat Datang project Anda.export GCLOUD_PROJECT=[MY_PROJECT_ID]
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 penyimpanan data Anda, dan juga jumlah node yang akan digunakan, yang menentukan jumlah resource penayangan dan penyimpanan di 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 perintah ini 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, sementara konfigurasi multi-region mendistribusikan data di beberapa region. Untuk mengetahui informasi selengkapnya, lihat Tentang instance.) - Jumlah node 1 (
node_count
sesuai dengan jumlah resource serving dan penyimpanan yang tersedia untuk database di instance. Pelajari lebih lanjut di Node dan unit pemrosesan.)
Anda akan melihat:
Creating instance...done.
Melihat-lihat file contoh
Repositori contoh berisi contoh yang menunjukkan cara menggunakan Spanner dengan C++.
Lihat file google/cloud/spanner/samples/samples.cc
, yang menunjukkan cara membuat database dan mengubah skema database. Data menggunakan contoh skema yang ditampilkan di halaman Skema dan model data.
Buat database
GoogleSQL
bazel run //google/cloud/spanner/samples:samples -- \
create-database $GCLOUD_PROJECT test-instance example-db
PostgreSQL
bazel run //google/cloud/spanner/samples:postgresql_samples -- \
create-database $GCLOUD_PROJECT test-instance example-db
bazel run //google/cloud/spanner/samples:postgresql_samples -- \
interleaved-table $GCLOUD_PROJECT test-instance example-db
Anda akan melihat:
Created database [projects/${GCLOUD_PROJECT}/instances/test-instance/databases/example-db]
GoogleSQL
PostgreSQL
Dalam dialek PostgreSQL, database harus dibuat sebelum mengirimkan permintaan DDL untuk membuat tabel.
Contoh berikut membuat database:
Contoh berikut membuat dua tabel dalam database:
Langkah berikutnya adalah menulis data ke database Anda.
Membuat klien database
Sebelum dapat melakukan pembacaan atau penulisan, Anda harus membuat Client
:
Client
memungkinkan Anda membaca, menulis, membuat kueri, dan menjalankan transaksi di database Spanner. Biasanya Anda membuat
Client
saat aplikasi Anda dimulai, lalu Anda menggunakan kembali Client
tersebut untuk
membaca, menulis, dan mengeksekusi transaksi. Setiap klien menggunakan resource di
Spanner. Destruktor Client
akan otomatis membersihkan resource
Client
, termasuk koneksi jaringan.
Baca selengkapnya tentang Client
di
Google Cloud Referensi C++ Spanner.
Menulis data dengan DML
Anda dapat menyisipkan data menggunakan Bahasa Pengolahan Data (DML) dalam transaksi baca-tulis.
Anda menggunakan fungsi Client::ExecuteDml()
untuk mengeksekusi pernyataan DML.
Jalankan sampel menggunakan argumen getting-started-insert
.
bazel run //google/cloud/spanner/samples:samples -- \
getting-started-insert $GCLOUD_PROJECT test-instance example-db
Anda akan melihat:
Insert was successful [spanner_dml_getting_started_insert]
Menulis data dengan mutasi
Anda juga dapat menyisipkan data menggunakan mutasi.
Anda menulis data menggunakan objek Client
. Fungsi Client::Commit()
membuat dan meng-commit transaksi untuk penulisan yang dieksekusi secara atomik
pada satu titik waktu logis di seluruh kolom, baris, dan tabel dalam
database.
Kode ini menunjukkan cara menulis data menggunakan mutasi:
Jalankan sampel menggunakan argumen insert-data
.
bazel run //google/cloud/spanner/samples:samples -- \
insert-data $GCLOUD_PROJECT test-instance example-db
Anda akan melihat:
Insert was successful [spanner_insert_data]
Membuat kueri data menggunakan SQL
Spanner mendukung antarmuka SQL untuk membaca data, yang dapat Anda akses di command line menggunakan Google Cloud CLI atau secara terprogram menggunakan library klien Spanner untuk C++.
Di 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 SingerId, AlbumId, AlbumTitle FROM Albums'
Hasilnya adalah:
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 library klien Spanner untuk C++
Selain menjalankan pernyataan SQL di command line, Anda dapat mengeluarkan pernyataan SQL yang sama secara terprogram menggunakan library klien Spanner untuk C++.
Anda menggunakan fungsi Client::ExecuteQuery()
untuk menjalankan kueri SQL.
Berikut cara mengeluarkan kueri dan mengakses data:
Jalankan sampel menggunakan argumen query_data
.
bazel run //google/cloud/spanner/samples:samples -- \
query-data $GCLOUD_PROJECT test-instance example-db
Anda akan melihat hasil berikut:
SingerId: 1 LastName: Richards
SingerId: 2 LastName: Smith
SingerId: 3 LastName: Trentor
SingerId: 4 LastName: Martin
SingerId: 5 LastName: Lomond
SingerId: 12 LastName: Garcia
SingerId: 13 LastName: Morales
SingerId: 14 LastName: Long
SingerId: 15 LastName: Shaw
Membuat kueri menggunakan parameter SQL
Jika aplikasi Anda memiliki kueri yang sering dijalankan, Anda dapat meningkatkan performanya dengan memparameterisasinya. Kueri parametrik yang dihasilkan dapat di-cache dan digunakan kembali, yang mengurangi biaya kompilasi. Untuk mengetahui informasi selengkapnya, lihat Menggunakan parameter kueri untuk mempercepat kueri yang sering dijalankan.
Berikut adalah contoh penggunaan parameter dalam klausa WHERE
untuk
mengkueri data yang berisi nilai tertentu untuk LastName
.
Jalankan sampel menggunakan perintah query-with-parameter.
bazel run //google/cloud/spanner/samples:samples -- \
query-with-parameter $GCLOUD_PROJECT test-instance example-db
Anda akan melihat hasil berikut:
SingerId: 12 FirstName: Melissa LastName: Garcia
Membaca data menggunakan read API
Selain antarmuka SQL Spanner, Spanner juga mendukung antarmuka baca.
Anda menggunakan fungsi Client::Read()
untuk membaca baris dari database. Gunakan objek KeySet
untuk menentukan kumpulan kunci dan rentang kunci yang akan dibaca.
Berikut cara membaca data:
Jalankan sampel menggunakan argumen read-data
.
bazel run //google/cloud/spanner/samples:samples -- \
read-data $GCLOUD_PROJECT test-instance example-db
Anda akan melihat output yang mirip dengan:
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold Your Peace
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
Memperbarui skema database
Misalkan Anda perlu menambahkan kolom baru bernama MarketingBudget
ke tabel Albums
. Menambahkan kolom baru ke tabel yang sudah ada memerlukan pembaruan pada
skema database Anda. Spanner mendukung update skema ke database saat
database terus melayani traffic. Pembaruan skema tidak memerlukan database
offline dan tidak mengunci seluruh tabel atau kolom; Anda dapat terus
menulis data ke database selama pembaruan skema. Baca selengkapnya tentang pembaruan skema yang didukung dan performa perubahan skema di Melakukan pembaruan skema.
Menambahkan kolom
Anda dapat menambahkan kolom di command line menggunakan Google Cloud CLI atau secara terprogram menggunakan library klien Spanner untuk C++.
Di command line
Gunakan perintah ALTER TABLE
berikut untuk menambahkan kolom baru ke tabel:
GoogleSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget INT64'
PostgreSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget BIGINT'
Anda akan melihat:
Schema updating...done.
Menggunakan library klien Spanner untuk C++
Gunakan fungsi DatabaseAdminClient::UpdateDatabase()
untuk mengubah skema.
Jalankan sampel menggunakan perintah add-column
.
bazel run //google/cloud/spanner/samples:samples -- \
add-column $GCLOUD_PROJECT test-instance example-db
Anda akan melihat:
Added MarketingBudget column
Menulis data ke kolom baru
Kode berikut menulis data ke kolom baru. Tindakan ini menetapkan MarketingBudget
ke
100000
untuk baris yang dikunci oleh Albums(1, 1)
dan ke 500000
untuk baris yang dikunci
oleh Albums(2, 2)
.
Jalankan sampel menggunakan argumen update-data
.
bazel run //google/cloud/spanner/samples:samples -- \
update-data $GCLOUD_PROJECT test-instance example-db
Anda juga dapat menjalankan kueri SQL atau panggilan baca untuk mengambil nilai yang baru saja Anda tulis.
Berikut kode untuk menjalankan kueri:
Untuk menjalankan kueri ini, jalankan sampel menggunakan argumen query-new-column
.
bazel run //google/cloud/spanner/samples:samples -- \
query-new-column $GCLOUD_PROJECT test-instance example-db
Anda akan melihat:
SingerId: 1 AlbumId: 1 MarketingBudget: 100000
SingerId: 1 AlbumId: 2 MarketingBudget: NULL
SingerId: 2 AlbumId: 1 MarketingBudget: NULL
SingerId: 2 AlbumId: 2 MarketingBudget: 500000
SingerId: 2 AlbumId: 3 MarketingBudget: NULL
Memperbarui data
Anda dapat memperbarui data menggunakan DML dalam transaksi baca-tulis.
Anda menggunakan fungsi Client::ExecuteDml()
untuk mengeksekusi pernyataan DML.
Jalankan sampel menggunakan argumen getting-started-update
.
bazel run //google/cloud/spanner/samples:samples -- \
getting-started-update $GCLOUD_PROJECT test-instance example-db
Anda akan melihat:
Update was successful [spanner_dml_getting_started_update]
Menggunakan indeks sekunder
Misalnya, Anda ingin mengambil semua baris Albums
yang memiliki nilai AlbumTitle
dalam rentang tertentu. Anda dapat membaca semua nilai dari kolom AlbumTitle
menggunakan
pernyataan SQL atau panggilan baca, lalu menghapus baris yang tidak memenuhi
kriteria, tetapi pemindaian tabel lengkap ini mahal, terutama untuk tabel
dengan banyak baris. Sebagai gantinya, Anda dapat mempercepat pengambilan baris saat
mencari menurut kolom non-kunci primer dengan membuat
indeks sekunder pada tabel.
Menambahkan indeks sekunder ke tabel yang ada memerlukan pembaruan skema. Seperti update skema lainnya, Spanner mendukung penambahan indeks saat database terus melayani traffic. Spanner akan otomatis mengisi ulang indeks dengan data yang ada. Pengisian ulang mungkin memerlukan waktu beberapa menit untuk selesai, tetapi Anda tidak perlu menghentikan database atau menghindari penulisan ke tabel yang diindeks selama proses ini. Untuk mengetahui detail selengkapnya, lihat Menambahkan indeks sekunder.
Setelah Anda menambahkan indeks sekunder, Spanner akan otomatis menggunakannya untuk kueri SQL yang kemungkinan akan berjalan lebih cepat dengan indeks tersebut. Jika menggunakan antarmuka baca, Anda harus menentukan indeks yang ingin digunakan.
Menambahkan indeks sekunder
Anda dapat menambahkan indeks di command line menggunakan gcloud CLI atau secara terprogram menggunakan library klien Spanner untuk C++.
Di command line
Gunakan perintah CREATE INDEX
berikut
untuk menambahkan indeks ke database:
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)'
Anda akan melihat:
Schema updating...done.
Menggunakan library klien Spanner untuk C++
Anda menggunakan fungsi DatabaseAdminClient::UpdateDatabase()
untuk menambahkan indeks:
Jalankan sampel menggunakan argumen add-index
.
bazel run //google/cloud/spanner/samples:samples -- \
add-index $GCLOUD_PROJECT test-instance example-db
Menambahkan indeks dapat memerlukan waktu beberapa menit. Setelah indeks ditambahkan, Anda akan melihat output yang mirip dengan ini:
`AlbumsByAlbumTitle` Index successfully added, new DDL:
database: "projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db"
statements: "CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)"
commit_timestamps {
seconds: 1581011550
nanos: 531102000
}
Membaca menggunakan indeks
Untuk kueri SQL, Spanner otomatis menggunakan indeks yang sesuai. Di antarmuka baca, Anda harus menentukan indeks dalam permintaan.
Untuk menggunakan indeks di antarmuka baca, gunakan fungsi Client::Read()
,
yang membaca nol atau lebih baris dari database menggunakan indeks.
Kode berikut mengambil semua kolom AlbumId
dan AlbumTitle
dari indeks AlbumsByAlbumTitle
.
Jalankan sampel menggunakan argumen read-data-with-index
.
bazel run //google/cloud/spanner/samples:samples -- \
read-data-with-index $GCLOUD_PROJECT test-instance example-db
Anda akan melihat:
AlbumId: 2 AlbumTitle: Forever Hold Your Peace
AlbumId: 2 AlbumTitle: Go, Go, Go
AlbumId: 1 AlbumTitle: Green
AlbumId: 3 AlbumTitle: Terrified
AlbumId: 1 AlbumTitle: Total Junk
Menambahkan indeks untuk pembacaan khusus indeks
Anda mungkin telah memperhatikan bahwa contoh baca sebelumnya tidak menyertakan pembacaan
kolom MarketingBudget
. Hal ini karena antarmuka baca Spanner
tidak mendukung kemampuan untuk menggabungkan indeks dengan tabel data guna mencari nilai
yang tidak disimpan dalam indeks.
Buat definisi alternatif AlbumsByAlbumTitle
yang menyimpan salinan
MarketingBudget
dalam indeks.
Di command line
GoogleSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)
PostgreSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) INCLUDE (MarketingBudget)
Menambahkan indeks dapat memerlukan waktu beberapa menit. Setelah indeks ditambahkan, Anda akan melihat:
Schema updating...done.
Menggunakan library klien Spanner untuk C++
Anda menggunakan fungsi DatabaseAdminClient::UpdateDatabase()
untuk menambahkan indeks
dengan klausa STORING
untuk :
Jalankan sampel menggunakan argumen add-storing-index
.
bazel run //google/cloud/spanner/samples:samples -- \
add-storing-index $GCLOUD_PROJECT test-instance example-db
Anda akan melihat output yang serupa dengan ini:
`AlbumsByAlbumTitle2` Index successfully added, new DDL:
database: "projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db"
statements: "CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)"
commit_timestamps {
seconds: 1581012328
nanos: 416682000
}
Sekarang Anda dapat menjalankan operasi baca yang mengambil semua kolom AlbumId
, AlbumTitle
, dan MarketingBudget
dari indeks AlbumsByAlbumTitle2
:
Membaca data menggunakan indeks penyimpanan yang Anda buat dengan menjalankan kueri yang secara eksplisit menentukan indeks:
Jalankan sampel menggunakan argumen read-data-with-storing-index
.
bazel run //google/cloud/spanner/samples:samples -- \
read-data-with-storing-index $GCLOUD_PROJECT test-instance example-db
Anda akan melihat output yang mirip dengan:
AlbumId: 2 AlbumTitle: Forever Hold Your Peace MarketingBudget: 520000
AlbumId: 2 AlbumTitle: Go, Go, Go MarketingBudget: NULL
AlbumId: 1 AlbumTitle: Green MarketingBudget: NULL
AlbumId: 3 AlbumTitle: Terrified MarketingBudget: NULL
AlbumId: 1 AlbumTitle: Total Junk MarketingBudget: 80000
Mengambil data menggunakan transaksi hanya baca
Misalkan Anda ingin menjalankan 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.
Jenis Transaction
digunakan untuk merepresentasikan semua jenis transaksi.
Gunakan fungsi factory MakeReadOnlyTransaction()
untuk membuat transaksi hanya baca.
Berikut cara menjalankan kueri dan melakukan pembacaan dalam transaksi hanya baca yang sama:
Jalankan sampel menggunakan argumen read-only-transaction
.
bazel run //google/cloud/spanner/samples:samples -- \
read-only-transaction $GCLOUD_PROJECT test-instance example-db
Anda akan melihat output yang mirip dengan:
Read 1 results
SingerId: 2 AlbumId: 2 AlbumTitle: Forever Hold Your Peace
SingerId: 1 AlbumId: 2 AlbumTitle: Go, Go, Go
SingerId: 2 AlbumId: 1 AlbumTitle: Green
SingerId: 2 AlbumId: 3 AlbumTitle: Terrified
SingerId: 1 AlbumId: 1 AlbumTitle: Total Junk
Read 2 results
SingerId: 2 AlbumId: 2 AlbumTitle: Forever Hold Your Peace
SingerId: 1 AlbumId: 2 AlbumTitle: Go, Go, Go
SingerId: 2 AlbumId: 1 AlbumTitle: Green
SingerId: 2 AlbumId: 3 AlbumTitle: Terrified
SingerId: 1 AlbumId: 1 AlbumTitle: Total Junk
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 Anda menghapus instance, semua database di dalamnya akan otomatis dihapus. Langkah ini menunjukkan cara menghapus database tanpa menghapus instance (Anda tetap dikenai biaya untuk instance tersebut).
Di command line
gcloud spanner databases delete example-db --instance=test-instance
Menggunakan Google Cloud console
Buka halaman Spanner Instances di konsol Google Cloud .
Klik instance.
Klik database yang ingin Anda hapus.
Di halaman Database details, klik Delete.
Konfirmasi bahwa Anda ingin menghapus database, lalu klik Hapus.
Menghapus instance
Menghapus instance akan otomatis menghapus semua database yang dibuat di instance tersebut.
Di command line
gcloud spanner instances delete test-instance
Menggunakan Google Cloud console
Buka halaman Spanner Instances di konsol Google Cloud .
Klik instance Anda.
Klik Hapus.
Konfirmasi bahwa Anda ingin menghapus instance, lalu klik Hapus.
Langkah berikutnya
Pelajari cara mengakses Spanner dengan instance virtual machine.
Pelajari kredensial otorisasi dan autentikasi di Mengautentikasi ke layanan Cloud menggunakan library klien.
Pelajari lebih lanjut Praktik terbaik desain skema Spanner.