Spanner CLI 快速入門

Spanner CLI 是 gcloud CLI 內的指令列介面 (CLI)，可讓您連線至 Spanner 資料庫並與其互動。舉例來說，您可以使用 Spanner CLI 執行 GoogleSQL 陳述式，以及自動執行工作。本文說明如何設定及使用 Spanner CLI。

Spanner CLI 是以開放原始碼的 spanner-cli 專案為基礎。

如需所有支援的 Spanner CLI 指令清單，請參閱「gcloud spanner cli 指令」。

主要優點

您可以使用 Spanner CLI 執行下列動作：

事前準備

使用 Spanner CLI 前，請確認您具備所需角色，並已安裝 CLI。

必要的角色

如要取得安裝 Spanner 所需的權限，請要求管理員授予您 Spanner 的「Cloud Spanner 管理員」 (roles/spanner.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

安裝 Spanner CLI

Spanner CLI 位於 gcloud CLI 中。首次執行 gcloud spanner cli 指令時，gcloud CLI 會自動安裝 Spanner CLI 元件。

如要手動安裝 Spanner CLI，請執行下列指令：

gcloud components install spanner-cli

如果無法使用 Google Cloud CLI 指令安裝，或在 Shell 環境中無法安裝，Spanner 提供獨立的 Debian (.deb) 和 RPM (.rpm) 套件。您可以使用這些套件，在相容的系統上手動安裝。如要安裝，請執行下列指令：

apt-get install google-cloud-cli-spanner-cli

設定選項

Spanner CLI 支援下列可設定的選項：

  • 專案選項是透過 core/project 屬性擷取；或者，您可以使用 --project 選項指定專案。
  • 執行個體選項是透過 core/instance 屬性擷取；或者，您可以使用 --instance 選項指定執行個體。
  • API 端點是透過 api_endpoint_overrides/spanner 屬性擷取；或者，您也可以使用 --host 和 --port 選項指定端點。如未指定端點，系統會使用預設的 Spanner 端點。

使用 Spanner CLI

  1. 設定 Google Cloud 專案。

  2. 使用 gcloud CLI 設定驗證。

  3. 建立執行個體。

  4. 建立資料庫。

  5. 執行下列指令，啟動 Spanner CLI 並與 Spanner 資料庫互動：

    gcloud spanner cli DATABASE_ID --instance=INSTANCE_ID

    更改下列內容：

    • DATABASE_ID：Spanner 資料庫的 ID。這是您在先前的「建立資料庫」步驟中使用的名稱。您可以使用 gcloud spanner databases list 指令，列出指定執行個體中包含的 Spanner 資料庫。
    • INSTANCE_ID：Spanner 執行個體的 ID。這是您在先前的「建立執行個體」步驟中使用的名稱。您可以使用 gcloud spanner instances list 指令，列出指定專案中包含的 Spanner 執行個體。

執行 SQL

您可以使用 execute 選項，或使用以檔案為基礎的輸入和輸出方法，在 Spanner CLI 中執行 SQL 陳述式。SQL 陳述式可包含 DDL、DML 或 DQL。

使用 execute 旗標

如要使用 execute 旗標執行 SQL，請執行下列 gcloud spanner cli 指令：

gcloud spanner cli DATABASE_ID --instance INSTANCE_ID \
    --execute "SQL"

更改下列內容：

  • DATABASE_ID：要連線的 Spanner 資料庫 ID。
  • INSTANCE_ID：要連線的 Spanner 執行個體 ID。
  • SQL：要執行的 SQL。

舉例來說，如要執行 DDL 陳述式：

gcloud spanner cli test-database --instance test-instance \
    --execute "CREATE TABLE Singers ( \
        SingerId   INT64 NOT NULL, \
        FirstName  STRING(1024), \
        LastName   STRING(1024), \
        SingerInfo STRING(1024), \
        BirthDate  DATE \
      ) PRIMARY KEY(SingerId);"

如要執行 DML 陳述式，請按照下列步驟操作：

gcloud spanner cli test-database --instance test-instance \
    --execute "INSERT INTO Singers (SingerId, FirstName, LastName, SingerInfo) \
        VALUES(1, 'Marc', 'Richards', 'nationality: USA'), \
              (2, 'Catalina', 'Smith', 'nationality: Brazil'), \
              (3, 'Andrew', 'Duneskipper', NULL);"

使用檔案做為輸入和輸出內容

如果您使用檔案型輸入和輸出方法，Spanner 會從檔案讀取輸入內容，並將輸出內容寫入另一個檔案。如要使用檔案式輸入和輸出方法執行 SQL，請執行下列指令：

gcloud spanner cli DATABASE_ID --instance INSTANCE_ID \
    --source INPUT_FILE_PATH --tee OUTPUT_FILE_PATH

您也可以使用檔案型重新導向輸入和輸出方法：

gcloud spanner cli DATABASE_ID --instance INSTANCE_ID \
    < INPUT_FILE_PATH > OUTPUT_FILE_PATH

更改下列內容：

  • DATABASE_ID：要連線的 Spanner 資料庫 ID。
  • INSTANCE_ID：要連線的 Spanner 執行個體 ID。
  • SOURCE_FILE_PATH：包含要執行的 SQL 檔案。
  • OUTPUT_FILE_PATH：要附加 SQL 輸出內容副本的具名檔案。

啟動互動工作階段

您可以啟動互動式 Spanner CLI 工作階段，直接輸入 SQL 陳述式和中繼指令，並在 CLI 中查看結果。如要這麼做，請執行下列指令：

gcloud spanner cli DATABASE_ID --instance=INSTANCE_ID

CLI 與資料庫成功連線後，您會看到提示 (例如 spanner-cli>)，可執行下列操作：

按下 ENTER 鍵後，系統會將陳述式或指令傳送至適當的 Spanner 資料庫。Spanner 隨即會執行陳述式或指令。

在下列範例中，您會在 test-database 中啟動互動式工作階段，然後執行 SELECT 1;：

gcloud spanner cli test-database --instance test-instance

Welcome to Spanner-Cli Client.
Type 'help;' or '\h' for help.
Type 'exit;' or 'quit;' or '\q' to exit.

spanner-cli> SELECT 1;
+---+
|   |
+---+
| 1 |
+---+

1 rows in set (1.11 msecs)

執行 DDL 陳述式

如要執行 DDL 陳述式，請執行下列操作：

spanner-cli> CREATE TABLE Singers (
          ->         SingerId   INT64 NOT NULL,
          ->         FirstName  STRING(1024),
          ->         LastName   STRING(1024),
          ->         SingerInfo STRING(1024),
          ->         BirthDate  DATE
          -> ) PRIMARY KEY(SingerId);

Query OK, 0 rows affected (17.08 sec)

執行 DML 陳述式

如要執行 DML 陳述式，請執行下列操作：

spanner-cli> INSERT INTO Singers (SingerId, FirstName, LastName, SingerInfo)
          -> VALUES(1, 'Marc', 'Richards', 'nationality: USA'),
          -> (2, 'Catalina', 'Smith', 'nationality: Brazil'),
          -> (3, 'Andrew', 'Duneskipper', NULL);

Query OK, 3 rows affected (0.32 sec)

執行分區 DML 陳述式

在 Spanner CLI 中，您可以使用 PARTITIONED 關鍵字搭配 UPDATE 和 DELETE 指令，有效率地執行大規模的分區 DML 陳述式。Spanner CLI 遇到 PARTITIONED UPDATE 或 PARTITIONED DELETE 時，會將其視為分區 DML 作業。這些關鍵字適用於會影響資料表大部分內容的作業，且不會長時間鎖定整個資料表。Spanner 不會將分區 DML 陳述式以不可分割的形式套用到整個資料表。並以不可分割的形式將分區 DML 陳述式套用到各個分區。

如要執行分區 DML 陳述式，請執行下列操作：

-- Update all rows in the 'Products' table by multiplying the price by 2
spanner-cli> PARTITIONED UPDATE Products SET Price = Price * 2 WHERE Price > 100;

-- Delete all rows in the 'Products' table with price less than 500
spanner-cli> PARTITIONED DELETE FROM Products WHERE Price < 500;

支援的中繼指令

Spanner CLI 支援公用程式中繼指令，這些指令會在用戶端 (本例中為 Spanner CLI) 上運作。Spanner CLI 支援下列中繼指令：

指令 語法 說明
? \? 顯示說明資訊。與 \h 相同。
分隔符號 \d 設定陳述式分隔符。預設分隔符號為半形分號。
結束 \q 結束 Spanner CLI。與結束相同。
Go \g 在 Spanner 中傳送及執行 SQL 陳述式。
說明 \h 顯示說明資訊。與 \? 相同。
附註 \t 關閉寫入 \T 設定的輸出檔案集。
提示 \R 將提示變更為使用者提示字串。
結束 \q 結束 Spanner CLI。與結束相同。
來源 \. 從輸入檔案執行 SQL。以 [filename] 做為引數。
System \! 執行系統殼層指令。
Tee \T 將指令輸出內容和標準輸出內容附加至指定的 [檔案名稱]。
使用 \u 連線至其他資料庫。以新資料庫名稱做為引數。

其他支援的指令

Spanner CLI 支援其他指令。詳情請參閱 Spanner CLI 指令。

取得支援

如要回報 Spanner CLI 的問題，請建立新的問題。

後續步驟