Tujuan
Tutorial ini memandu Anda melalui langkah-langkah berikut menggunakan driver JDBC Spanner:
- 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 JDBC lokal
Instal yang berikut ini pada mesin pengembangan Anda jika belum terinstal:
Clone repositori aplikasi contoh ke komputer lokal Anda:
git clone https://github.com/googleapis/java-spanner-jdbc.git
Ubah ke direktori yang berisi kode contoh Spanner:
cd java-spanner-jdbc/samples/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 sampel berisi contoh yang menunjukkan cara menggunakan Spanner dengan JDBC.
pom.xml
menambahkan driver JDBC Spanner ke dependensi project dan mengonfigurasi plugin assembly untuk mem-build file JAR yang dapat dieksekusi dengan class Java yang ditentukan dalam tutorial ini.
Buat contoh dari
direktori samples/snippets
:
mvn package -DskipTests
Buat database
Buat database yang disebut example-db
dalam instance bernama test-instance
dengan
menjalankan baris berikut di command line.
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
createdatabase test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
createpgdatabase test-instance example-db
Anda akan melihat:
Created database [projects/my-project/instances/test-instance/databases/example-db]
Kode berikut membuat database dan dua tabel dalam database.
GoogleSQL
PostgreSQL
Langkah selanjutnya adalah menulis data ke database Anda.
Membuat koneksi JDBC
Sebelum dapat melakukan pembacaan atau penulisan, Anda harus membuatConnection
. Semua interaksi Anda
dengan Spanner harus melalui Connection
. Nama database dan properti lainnya ditentukan dalam URL koneksi JDBC dan java.util.Properties
yang ditetapkan.
GoogleSQL
PostgreSQL
Untuk mengetahui daftar lengkap properti yang didukung, lihat Properti URL Koneksi.
Setiap Connection
menggunakan resource, jadi sebaiknya tutup
koneksi saat tidak diperlukan lagi, atau gunakan kumpulan koneksi untuk
menggunakan kembali koneksi di seluruh aplikasi Anda.
Baca selengkapnya dalam referensi Javadoc Connection
.
Menghubungkan driver JDBC ke emulator
Anda dapat menghubungkan driver JDBC ke emulator Spanner dengan dua cara:
- Tetapkan variabel lingkungan
SPANNER_EMULATOR_HOST
: Variabel ini menginstruksikan driver JDBC untuk terhubung ke emulator. Instance dan database Spanner di URL koneksi JDBC harus sudah ada di emulator. - Tambahkan
autoConfigEmulator=true
ke URL koneksi: Tindakan ini akan menginstruksikan driver JDBC untuk terhubung ke emulator, dan untuk otomatis membuat instance dan database Spanner di URL koneksi JDBC jika tidak ada.
Contoh ini menunjukkan cara menggunakan opsi URL koneksi
autoConfigEmulator=true
.
GoogleSQL
PostgreSQL
Menulis data dengan DML
Anda dapat menyisipkan data menggunakan Data Manipulation Language (DML) dalam transaksi baca-tulis.
Anda menggunakan metode PreparedStatement.executeUpdate()
untuk mengeksekusi pernyataan DML.
GoogleSQL
PostgreSQL
Jalankan contoh dengan perintah ini:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writeusingdml test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writeusingdmlpg test-instance example-db
Anda akan melihat:
4 records inserted.
Menulis data dengan batch DML
Anda menggunakan metode PreparedStatement#addBatch()
dan
PreparedStatement#executeBatch()
untuk mengeksekusi beberapa pernyataan DML dalam
satu batch.
GoogleSQL
PostgreSQL
Jalankan contoh dengan perintah ini:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writeusingdmlbatch test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writeusingdmlbatchpg test-instance example-db
Anda akan melihat:
3 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
oleh Spanner secara atomik ke berbagai baris dan tabel di 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 tersebut sudah ada.
write()
di antarmuka CloudSpannerJdbcConnection
menulis mutasi. Semua mutasi dalam satu batch diterapkan secara atomik.
Anda dapat membuka antarmuka CloudSpannerJdbcConnection
dari Connection
Spanner
JDBC.
Kode ini menunjukkan cara menulis data menggunakan mutasi:
GoogleSQL
PostgreSQL
Jalankan contoh dengan perintah ini:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
write test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writepg test-instance example-db
Anda akan melihat:
Inserted 10 rows.
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 JDBC Spanner.
Pada command line
Jalankan pernyataan SQL berikut untuk membaca nilai semua kolom dari
tabel Albums
:
GoogleSQL
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'
PostgreSQL
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 JDBC Spanner
Selain menjalankan pernyataan SQL di command line, Anda dapat mengeluarkan pernyataan SQL yang sama secara terprogram menggunakan driver JDBC Spanner.
Metode dan class berikut digunakan untuk menjalankan kueri SQL:- Metode
createStatement()
di antarmukaConnection
: gunakan ini untuk membuat objek pernyataan baru untuk menjalankan pernyataan SQL. - Metode
executeQuery(String)
dari classStatement
: gunakan metode ini untuk mengeksekusi kueri terhadap database. - Class
Statement
: gunakan class ini untuk mengeksekusi string SQL. - Class
ResultSet
: gunakan class ini untuk mengakses data yang ditampilkan oleh pernyataan SQL.
Berikut cara mengeluarkan kueri dan mengakses data:
GoogleSQL
PostgreSQL
Jalankan contoh dengan perintah ini:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
query test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querypg 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
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
.
Gunakan java.sql.PreparedStatement
untuk menjalankan kueri dengan parameter.
GoogleSQL
PostgreSQL
Jalankan contoh dengan perintah ini:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querywithparameter test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querywithparameterpg test-instance 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 di command line menggunakan Google Cloud CLI atau secara terprogram menggunakan library klien Spanner untuk JDBC.
Pada 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 marketing_budget BIGINT'
Anda akan melihat:
Schema updating...done.
Menggunakan driver JDBC Spanner
Gunakan metodeexecute(String)
dari class java.sql.Statement
untuk mengubah skema:
GoogleSQL
PostgreSQL
Jalankan contoh dengan perintah ini:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
addmarketingbudget test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
addmarketingbudgetpg test-instance example-db
Anda akan melihat:
Added MarketingBudget column.
Menjalankan batch DDL
Sebaiknya jalankan beberapa modifikasi skema dalam satu batch. Gunakan metode
addBatch(String)
dari java.sql.Statement
untuk menambahkan beberapa pernyataan DDL ke dalam batch.
GoogleSQL
PostgreSQL
Jalankan contoh dengan perintah ini:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
ddlbatch test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
ddlbatchpg test-instance 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)
.
GoogleSQL
PostgreSQL
Jalankan contoh dengan perintah ini:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
update test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
updatepg test-instance example-db
Anda akan melihat output yang serupa dengan ini:
Updated albums
Anda juga dapat menjalankan kueri SQL atau panggilan baca untuk mengambil nilai yang baru saja Anda tulis.
Berikut adalah kode untuk mengeksekusi kueri:
GoogleSQL
PostgreSQL
Untuk menjalankan kueri ini, jalankan perintah berikut:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querymarketingbudget test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querymarketingbudgetpg 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.
Tetapkan AutoCommit=false
untuk menjalankan transaksi baca-tulis di JDBC.
GoogleSQL
PostgreSQL
Jalankan contoh dengan perintah ini:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writewithtransactionusingdml test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writewithtransactionusingdmlpg test-instance example-db
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 di JDBC dengan variabel sesi TRANSACTION_TAG
dan STATEMENT_TAG
.
GoogleSQL
PostgreSQL
Jalankan contoh dengan perintah ini:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
tags test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
tagspg test-instance 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.
Tetapkan ReadOnly=true
dan AutoCommit=false
pada java.sql.Connection
, atau gunakan
pernyataan SQL SET TRANSACTION READ ONLY
, untuk menjalankan transaksi
hanya baca.
Berikut ini cara menjalankan kueri dan melakukan pembacaan dalam transaksi hanya baca yang sama:
GoogleSQL
PostgreSQL
Jalankan contoh dengan perintah ini:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
readonlytransaction test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
readonlytransactionpg 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
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.
GoogleSQL
PostgreSQL
Jalankan contoh dengan perintah ini:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
databoost test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
databoostpg test-instance example-db
Untuk informasi selengkapnya tentang menjalankan kueri yang dipartisi dan menggunakan Data Boost dengan driver JDBC, lihat:
- GoogleSQL: Peningkatan Data dan pernyataan kueri terpartisi
- PostgreSQL: Peningkatan Data dan pernyataan kueri terpartisi
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.
GoogleSQL
PostgreSQL
Jalankan contoh dengan perintah ini:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
pdml test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
pdmlpg test-instance example-db
Untuk informasi selengkapnya tentang AUTOCOMMIT_DML_MODE
, lihat:
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 Mengintegrasikan Spanner dengan Spring Data JPA (dialek GoogleSQL).
- Pelajari cara Mengintegrasikan Spanner dengan Spring Data JPA (dialek PostgreSQL).
- Pelajari cara Mengintegrasikan Spanner dengan Hibernate ORM (dialek GoogleSQL).
- Pelajari cara Mengintegrasikan Spanner dengan Hibernate ORM (dialek PostgreSQL).
- Pelajari perintah pengelolaan sesi JDBC (GoogleSQL) lebih lanjut.
- Pelajari perintah pengelolaan sesi JDBC (PostgreSQL) lebih lanjut.
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.