目標
本教學課程會使用 Spanner JDBC 驅動程式,逐步引導您完成下列步驟:
- 建立 Spanner 執行個體和資料庫。
- 對資料庫中的資料進行寫入和讀取,以及執行 SQL 查詢。
- 更新資料庫結構定義。
- 使用讀取/寫入交易來更新資料。
- 將次要索引新增至資料庫。
- 使用索引對資料執行讀取作業和 SQL 查詢。
- 使用唯讀交易擷取資料。
費用
本教學課程使用 Spanner,這是Google Cloud的計費元件。如需使用 Spanner 的費用資訊,請參閱定價一文。
事前準備
完成「設定」一文中說明的步驟,包括建立及設定預設 Google Cloud 專案、啟用計費功能、啟用 Cloud Spanner API,以及設定 OAuth 2.0 以取得驗證憑證,進而使用 Cloud Spanner API。
特別提醒您,請務必執行 gcloud auth
application-default login
,使用驗證憑證設定本機開發環境。
準備本機 JDBC 環境
請在您的開發機器上安裝下列項目:
將應用程式存放區範例複製到本機電腦中:
git clone https://github.com/googleapis/java-spanner-jdbc.git
變更為包含 Spanner 範例程式碼的目錄:
cd java-spanner-jdbc/samples/snippets
建立執行個體
初次使用 Spanner 時,必須建立執行個體,這是 Spanner 資料庫會使用的資源分配單位。建立執行個體時,請選擇「執行個體設定」以決定資料儲存的位置,再選擇要使用的節點數量以決定執行個體的服務和儲存空間資源量。
執行下列指令,使用 1 個節點在 us-central1
地區建立 Spanner 執行個體:
gcloud spanner instances create test-instance --config=regional-us-central1 \
--description="Test Instance" --nodes=1
請注意,如此將建立具備下列特性的執行個體:
- 執行個體 ID
test-instance
- 顯示名稱
Test Instance
- 執行個體設定
regional-us-central1
(地區設定會將資料儲存在一個地區,而多地區設定則會讓資料散佈在多個地區。詳情請參閱「關於執行個體」一文。) - 節點數量 1 (
node_count
與執行個體中的資料庫可用的服務和儲存空間資源數量相對應。詳情請參閱「節點和處理單元」一節)。
畫面上會顯示下列訊息:
Creating instance...done.
瀏覽範例檔案
範例存放區中有一項範例說明如何使用 Spanner 搭配 JDBC。
pom.xml
會將 Spanner JDBC 驅動程式新增至專案的依附元件,並設定組件外掛程式,以使用本教學課程中定義的 Java 類別建構可執行的 JAR 檔案。
mvn package -DskipTests
建立資料庫
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
畫面上會顯示下列訊息:
Created database [projects/my-project/instances/test-instance/databases/example-db]
GoogleSQL
PostgreSQL
下一個步驟是將資料寫入資料庫。
建立 JDBC 連線
您必須先建立Connection
,才能執行讀取或寫入作業。您與 Spanner 的所有互動都必須透過 Connection
。資料庫名稱和其他屬性會在 JDBC 連線網址和 java.util.Properties
集中指定。
GoogleSQL
PostgreSQL
如需完整的支援屬性清單,請參閱「連線網址屬性」。
每個 Connection
都會使用資源,因此建議您在不再需要連線時關閉連線,或使用連線集區在整個應用程式中重複使用連線。
詳情請參閱 Connection
Javadoc 參考資料。
將 JDBC 驅動程式連線至模擬器
您可以透過兩種方式將 JDBC 驅動程式連線至 Spanner 模擬器:
- 設定
SPANNER_EMULATOR_HOST
環境變數:這會指示 JDBC 驅動程式連線至模擬器。JDBC 連線網址中的 Spanner 執行個體和資料庫必須已存在於模擬器中。 - 在連線網址中加入
autoConfigEmulator=true
:這會指示 JDBC 驅動程式連線至模擬器,並在 JDBC 連線網址中自動建立 Spanner 執行個體和資料庫 (如果不存在)。
這個範例說明如何使用 autoConfigEmulator=true
連線網址選項。
GoogleSQL
PostgreSQL
使用 DML 寫入資料
您可以使用資料操縱語言 (DML) 在讀寫交易中插入資料。
請使用 PreparedStatement.executeUpdate()
方法執行 DML 陳述式。
GoogleSQL
PostgreSQL
使用下列指令執行範例:
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
畫面上會顯示下列訊息:
4 records inserted.
使用 DML 批次寫入資料
您可以使用PreparedStatement#addBatch()
和 PreparedStatement#executeBatch()
方法,在一個批次中執行多個 DML 陳述式。
GoogleSQL
PostgreSQL
使用下列指令執行範例:
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
畫面上會顯示下列訊息:
3 records inserted.
使用變異寫入資料
您也可以使用變異來插入資料。
您可以使用 Mutation
物件寫入資料。Mutation
物件是變異作業的容器。Mutation
代表一系列的插入、更新和刪除作業,Spanner 會以不可分割的形式,將這些作業套用至 Spanner 資料庫中不同的資料列和資料表。
Mutation
類別中的 newInsertBuilder()
方法會建構 INSERT
變異,在資料表中插入新的資料列。如果該資料列已存在,寫入就會失敗。或者,您可以使用 newInsertOrUpdateBuilder
方法建構 INSERT_OR_UPDATE
變異,在有資料列的情況下,這個方法會更新資料欄的值。
CloudSpannerJdbcConnection
介面中的 write()
方法會寫入異動事件,系統會以不可分割的形式套用單一批次中的所有變異。
您可以從 Spanner JDBC Connection
解除包裝 CloudSpannerJdbcConnection
介面。
此程式碼顯示如何使用變異寫入資料:
GoogleSQL
PostgreSQL
使用下列指令執行範例:
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
畫面上會顯示下列訊息:
Inserted 10 rows.
使用 SQL 查詢資料
Spanner 支援用於讀取資料的 SQL 介面。您可以透過 Google Cloud CLI 在指令列上存取介面,也可以透過程式輔助方式使用 Spanner JDBC 驅動程式存取介面。
使用指令列
執行下列 SQL 陳述式,從 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'
結果應為:
SingerId AlbumId AlbumTitle
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
使用 Spanner JDBC 驅動程式
除了在指令列上執行 SQL 陳述式外,您還可以使用 Spanner JDBC 驅動程式,透過程式輔助方式發出相同的 SQL 陳述式。
您可以使用下列方法和類別來執行 SQL 查詢:Connection
介面中的createStatement()
方法:使用這個方法建立新的陳述式物件,以執行 SQL 陳述式。Statement
類別的executeQuery(String)
方法:使用這個方法,即可執行資料庫查詢。Statement
類別:使用這個類別執行 SQL 字串。ResultSet
類別:使用這個類別,即可存取 SQL 陳述式傳回的資料。
下面說明如何發出查詢和存取資料:
GoogleSQL
PostgreSQL
使用下列指令執行範例:
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
畫面上應會顯示下列結果:
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
使用 SQL 參數查詢
如果應用程式經常執行查詢,您可以將查詢參數化,藉此提升效能。系統可快取並重新使用產生的參數查詢,減少編譯的成本。詳情請參閱「使用查詢參數,針對經常執行的查詢加快速度」。
以下範例說明如何在 WHERE
子句中使用參數,查詢包含特定 LastName
值的記錄。
使用 java.sql.PreparedStatement
執行含參數的查詢。
GoogleSQL
PostgreSQL
使用下列指令執行範例:
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
畫面上應會顯示下列結果:
12 Melissa Garcia
更新資料庫結構定義
假設您需要新增名稱為 MarketingBudget
的新資料欄到 Albums
資料表,必須先更新資料庫結構定義,才能新增新資料欄到現有的資料表。Spanner 可在資料庫持續處理流量時,支援資料庫的結構定義更新作業。結構定義更新作業不需要讓資料庫離線,也不會鎖定整個資料表或資料欄;您可以在結構定義更新期間持續將資料寫入資料庫。詳情請參閱「進行結構定義更新」一文,瞭解支援的結構定義更新和結構定義變更效能。
新增資料欄
您可以使用 Google Cloud CLI 在指令列上新增資料欄,或使用 Spanner JDBC 驅動程式透過程式輔助方式新增資料欄。
使用指令列
使用下列 ALTER TABLE
指令,在資料表中新增資料欄:
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'
畫面上會顯示下列訊息:
Schema updating...done.
使用 Spanner JDBC 驅動程式
使用java.sql.Statement
類別的 execute(String)
方法修改結構定義:
GoogleSQL
PostgreSQL
使用下列指令執行範例:
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
畫面上會顯示下列訊息:
Added MarketingBudget column.
執行 DDL 批次
建議您一次批次執行多項結構定義修改作業。使用 java.sql.Statement
的
addBatch(String)
方法,將多個 DDL 陳述式新增至批次。
GoogleSQL
PostgreSQL
使用下列指令執行範例:
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
畫面上會顯示下列訊息:
Added Venues and Concerts tables.
寫入資料到新資料欄
以下程式碼會將資料寫入新資料欄,並在 Albums(1, 1)
和 Albums(2, 2)
這兩個索引鍵表示的資料列中將 MarketingBudget
一欄分別設為 100000
和 500000
。
GoogleSQL
PostgreSQL
使用下列指令執行範例:
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
畫面會顯示類似以下的輸出:
Updated albums
您也可以執行 SQL 查詢或讀取呼叫,以擷取剛寫入的值。
以下是執行查詢的程式碼:
GoogleSQL
PostgreSQL
如要執行這項查詢,請執行下列指令:
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
結果會顯示:
1 1 100000
1 2 null
2 1 null
2 2 500000
2 3 null
更新資料
您可以在讀寫交易中使用 DML 來更新資料。
設定 AutoCommit=false
,在 JDBC 中執行讀寫交易。
GoogleSQL
PostgreSQL
使用下列指令執行範例:
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
交易代碼和要求代碼
使用交易標記和要求標記,排解 Spanner 中的交易和查詢問題。您可以在 JDBC 中使用 TRANSACTION_TAG
和 STATEMENT_TAG
工作階段變數,設定交易代碼和要求代碼。
GoogleSQL
PostgreSQL
使用下列指令執行範例:
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
使用唯讀交易擷取資料
假設您想要在相同時間戳記執行一次以上的讀取作業。唯讀交易會觀察出交易修訂記錄中一致的前置字串,讓應用程式取得的資料始終保持一致。
在 java.sql.Connection
上設定 ReadOnly=true
和 AutoCommit=false
,或使用 SET TRANSACTION READ ONLY
SQL 陳述式,即可執行唯讀交易。
以下顯示如何執行查詢,並在同一個唯讀交易中執行讀取作業:
GoogleSQL
PostgreSQL
使用下列指令執行範例:
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
畫面會顯示類似以下的輸出:
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
分區查詢和 Data Boost
partitionQuery
API 會將查詢分成較小的片段 (稱為「分區」),並使用多部機器平行擷取分區。每個分割區都會以分割區權杖識別。PartitionQuery API 的延遲時間比標準查詢 API 長,因為這個 API 僅適用於大量作業,例如匯出或掃描整個資料庫。
Data Boost 可讓您執行分析查詢和資料匯出作業,對已佈建 Spanner 執行個體的現有工作負載幾乎沒有影響。Data Boost 僅支援分區查詢。
GoogleSQL
PostgreSQL
使用下列指令執行範例:
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
如要進一步瞭解如何執行分區查詢,以及如何搭配使用 JDBC 驅動程式與 Data Boost,請參閱:
分區 DML
分區資料操縱語言 (DML) 專為下列類型的批次更新和刪除作業而設計:
- 定期清理和垃圾收集。
- 對具有預設值的新資料欄進行補充作業。
PostgreSQL
使用下列指令執行範例:
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
如要進一步瞭解 AUTOCOMMIT_DML_MODE
,請參閱:
清除所用資源
如要避免系統向您的 Cloud 帳單帳戶收取您在本教學課程中所用資源的相關費用,請捨棄資料庫並刪除您建立的執行個體。
刪除資料庫
您刪除執行個體時,也會自動刪除其中所有資料庫。 以下步驟將示範如何在保留執行個體的情況下刪除資料庫 (您仍須支付執行個體費用)。
使用指令列
gcloud spanner databases delete example-db --instance=test-instance
使用 Google Cloud 控制台
前往 Google Cloud 控制台的「Spanner Instances」(Spanner 執行個體) 頁面。
點選執行個體。
點選您要刪除的資料庫。
在「Database details」(資料庫詳細資料) 頁面,按一下 [Delete] (刪除)。
確認您要刪除資料庫,然後按一下 [Delete] (刪除)。
刪除執行個體
您刪除執行個體時,也會自動捨棄您在其中建立的所有資料庫。
使用指令列
gcloud spanner instances delete test-instance
使用 Google Cloud 控制台
前往 Google Cloud 控制台的「Spanner Instances」(Spanner 執行個體) 頁面。
點選執行個體。
按一下 [Delete] (刪除)。
確認您要刪除執行個體,然後按一下 [Delete] (刪除)。
後續步驟
- 瞭解如何將 Spanner 與 Spring Data JPA (GoogleSQL 方言) 整合。
- 瞭解如何將 Spanner 與 Spring Data JPA (PostgreSQL 方言) 整合。
- 瞭解如何將 Spanner 與 Hibernate ORM (GoogleSQL 方言) 整合。
- 瞭解如何將 Spanner 與 Hibernate ORM (PostgreSQL 方言) 整合。
- 進一步瞭解 JDBC 工作階段管理指令 (GoogleSQL)。
- 進一步瞭解 JDBC 工作階段管理指令 (PostgreSQL)。
瞭解如何透過虛擬機器執行個體存取 Spanner。
請參閱「使用用戶端程式庫向 Cloud 服務進行驗證」,瞭解授權和驗證憑證。
進一步瞭解 Spanner 結構定義設計最佳做法。