Tujuan
Tutorial ini akan memandu Anda melalui langkah-langkah berikut menggunakan library klien Spanner untuk Java:
- 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.
Siapkan lingkungan Java lokal Anda
Instal komponen berikut di mesin pengembangan Anda jika belum diinstal:
Clone repositori aplikasi contoh ke komputer lokal Anda:
git clone https://github.com/googleapis/java-spanner.git
Ubah ke direktori yang berisi kode contoh Spanner:
cd java-spanner/samples/snippets
Buat file JAR sampel:
mvn clean package
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 Java.
Buat database
GoogleSQL
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
createdatabase test-instance example-db
PostgreSQL
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
createpgdatabase test-instance example-db
Anda akan melihat:
Created database [example-db]
GoogleSQL
PostgreSQL
Langkah berikutnya adalah menulis data ke database Anda.
Membuat klien database
Sebelum dapat melakukan operasi baca atau tulis, Anda harus membuatDatabaseClient
.
Anda dapat menganggap DatabaseClient
sebagai koneksi database: semua
interaksi Anda dengan Spanner harus melalui DatabaseClient
. Biasanya, Anda membuat DatabaseClient
saat aplikasi dimulai, lalu menggunakan kembali DatabaseClient
tersebut untuk membaca, menulis, dan mengeksekusi transaksi.
Setiap klien menggunakan resource di Spanner, jadi sebaiknya tutup klien yang tidak diperlukan dengan memanggil close()
.
Baca selengkapnya di referensi Javadoc DatabaseClient
.
Menulis data dengan DML
Anda dapat menyisipkan data menggunakan Bahasa Pengolahan Data (DML) dalam transaksi baca-tulis.
Anda menggunakan metode executeUpdate()
untuk menjalankan pernyataan DML.
Jalankan sampel menggunakan argumen writeusingdml
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
writeusingdml test-instance example-db
Anda akan melihat:
4 records inserted.
Menulis data dengan mutasi
Anda juga dapat menyisipkan data menggunakan mutasi.
Anda dapat menulis data menggunakan
objek Mutation
.
Objek Mutation
adalah penampung untuk operasi mutasi. Mutation
mewakili urutan penyisipan, pembaruan, dan penghapusan yang diterapkan Spanner
secara atomik ke baris dan tabel yang berbeda dalam database Spanner.
Metode newInsertBuilder()
di class Mutation
membuat mutasi INSERT
, yang menyisipkan
baris baru dalam tabel. Jika baris sudah ada, penulisan akan gagal. Atau,
Anda dapat menggunakan metode newInsertOrUpdateBuilder
untuk membuat mutasi INSERT_OR_UPDATE
, yang memperbarui nilai kolom
jika baris sudah ada.
write()
di class DatabaseClient
menulis mutasi. Semua mutasi dalam
satu batch diterapkan secara atomik.
Kode ini menunjukkan cara menulis data menggunakan mutasi:
Jalankan sampel menggunakan argumen write
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
write test-instance example-db
Anda akan melihat perintah berhasil dijalankan.
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 Java.
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 Java
Selain menjalankan pernyataan SQL di command line, Anda dapat mengeluarkan pernyataan SQL yang sama secara terprogram menggunakan library klien Spanner untuk Java.
Metode dan class berikut digunakan untuk menjalankan kueri SQL:- Metode
singleUse()
di classDatabaseClient
: gunakan ini untuk membaca nilai satu atau beberapa kolom dari satu atau beberapa baris dalam tabel Spanner.singleUse()
menampilkan objekReadContext
, yang digunakan untuk menjalankan pernyataan SQL atau baca. - Metode
executeQuery()
dari classReadContext
: gunakan metode ini untuk menjalankan kueri terhadap database. - Class
Statement
: gunakan class ini untuk membuat string SQL. - Class
ResultSet
: gunakan class ini untuk mengakses data yang ditampilkan oleh pernyataan SQL atau panggilan baca.
Berikut cara mengeluarkan kueri dan mengakses data:
Jalankan sampel menggunakan argumen query
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
query test-instance 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
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
.
GoogleSQL
PostgreSQL
Jalankan contoh menggunakan argumen queryWithParameter.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
querywithparameter test-instance example-db
Anda akan melihat hasil berikut:
12 Melissa Garcia
Membaca data menggunakan read API
Selain antarmuka SQL Spanner, Spanner juga mendukung antarmuka baca.
Gunakan metoderead()
dari class ReadContext
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
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
read test-instance 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
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 Java.
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 Java
Gunakan metodeupdateDatabaseDdl()
dari class DatabaseAdminClient
untuk mengubah skema:
GoogleSQL
PostgreSQL
Jalankan sampel menggunakan argumen addmarketingbudget
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
addmarketingbudget 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
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
update 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:
GoogleSQL
PostgreSQL
Untuk menjalankan kueri ini, jalankan sampel menggunakan argumen querymarketingbudget
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
querymarketingbudget test-instance 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.
Anda menggunakan metode executeUpdate()
untuk menjalankan pernyataan DML.
GoogleSQL
PostgreSQL
Jalankan sampel menggunakan argumen writewithtransactionusingdml
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
writewithtransactionusingdml test-instance example-db
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 Java.
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 Java
Gunakan metodeupdateDatabaseDdl()
dari class DatabaseAdminClient
untuk menambahkan indeks:
Jalankan sampel menggunakan argumen addindex
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
addindex test-instance example-db
Menambahkan indeks dapat memerlukan waktu beberapa menit. Setelah indeks ditambahkan, Anda akan melihat:
Added the AlbumsByAlbumTitle index.
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 metode
readUsingIndex()
dari class ReadContext
.
Kode berikut mengambil semua kolom AlbumId
dan AlbumTitle
dari indeks AlbumsByAlbumTitle
.
Jalankan sampel menggunakan argumen readindex
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
readindex test-instance example-db
Anda akan melihat:
2 Forever Hold Your Peace
2 Go, Go, Go
1 Green
3 Terrified
1 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 Java
Gunakan metode updateDatabaseDdl()
kelas DatabaseAdminClient
untuk menambahkan indeks dengan klausul STORING
untuk GoogleSQL dan klausul INCLUDE
untuk PostgreSQL:
GoogleSQL
PostgreSQL
Jalankan sampel menggunakan argumen addstoringindex
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
addstoringindex test-instance example-db
Menambahkan indeks dapat memerlukan waktu beberapa menit. Setelah indeks ditambahkan, Anda akan melihat:
Added AlbumsByAlbumTitle2 index
Sekarang Anda dapat menjalankan operasi baca yang mengambil semua kolom AlbumId
, AlbumTitle
, dan MarketingBudget
dari indeks AlbumsByAlbumTitle2
:
Jalankan sampel menggunakan argumen readstoringindex
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
readstoringindex test-instance example-db
Anda akan melihat output yang mirip dengan:
2 Forever Hold Your Peace 300000
2 Go, Go, Go NULL
1 Green NULL
3 Terrified NULL
1 Total Junk 300000
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.
Gunakan objek ReadOnlyTransaction
untuk menjalankan transaksi hanya baca. Gunakan metode readOnlyTransaction()
dari class DatabaseClient
untuk mendapatkan objek ReadOnlyTransaction
.
Berikut cara menjalankan kueri dan melakukan pembacaan dalam transaksi hanya baca yang sama:
Jalankan sampel menggunakan argumen readonlytransaction
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
readonlytransaction test-instance example-db
Anda akan melihat output yang mirip dengan:
2 2 Forever Hold Your Peace
1 2 Go, Go, Go
2 1 Green
2 3 Terrified
1 1 Total Junk
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
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.