このページは Cloud Translation API によって翻訳されました。

Spanner CLI クイックスタート

このページでは、Spanner CLI とその使用方法について説明します。

Spanner CLI は、Spanner データベースに接続して操作できるコマンドラインインターフェース（CLI）です。これは、Spanner とのインターフェースをとるために Google Cloud CLI（gcloud CLI）に組み込まれています。Spanner CLI を使用して、Spanner データベースで GoogleSQL ステートメントを直接実行できます。ステートメントは、データ定義言語（DDL）、データ操作言語（DML）、データクエリ言語（DQL）のステートメントで構成できます。Spanner CLI を使用して、SQL コマンドスクリプトを実行し、タスクを自動化できます。

これは、オープンソースの spanner-cli プロジェクトに基づいています。

詳細については、サポートされているすべての gcloud spanner cli コマンドの一覧をご覧ください。

主なメリット

Spanner を使用して、次の操作を行うことができます。

DDL、DML、DQL の SQL コマンドを実行します。
複数行にわたって SQL ステートメントを記述して実行します。
メタコマンドを使用して、システムシェルコマンドの実行やファイルからの SQL の実行などのシステムタスクを支援します。
スクリプトファイルに一連の SQL ステートメントを記述し、Spanner CLI にスクリプトの実行を指示することで、SQL の実行を自動化します。また、出力を出力ファイルにリダイレクトすることもできます。
インタラクティブな Spanner CLI セッションを開始すると、SQL ステートメントとメタコマンドを直接入力して、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 コマンドを使用したインストールが失敗した場合や、シェル環境で実行できない場合は、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 を使用する

Google Cloud プロジェクトを設定する。
gcloud CLI を使用して認証を設定する。
インスタンスを作成する。
データベースを作成する。
次のコマンドを実行して 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 を実行する

Spanner CLI で SQL ステートメントを実行するには、execute オプションを使用するか、ファイルベースの入出力メソッドを使用します。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> など）が表示され、次の操作を行うことができます。

次の GoogleSQL ステートメントを直接入力する:
トランザクションを実行する
サポート対象のメタコマンドを使用する

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 では、UPDATE コマンドと DELETE コマンドで PARTITIONED キーワードを使用して、効率的な大規模パーティション化 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 を終了します。quit と同一です。
Go	`\g`	Spanner で SQL ステートメントを送信して実行します。
ヘルプ	`\h`	ヘルプ情報を表示します。`\?` と同一です。
Notee	`\t`	`\T` で設定された出力ファイルへの書き込みをオフにします。
プロンプト	`\R`	プロンプトをユーザープロンプト文字列に変更します。
終了	`\q`	Spanner CLI を終了します。exit と同一です。
ソース	`\.`	入力ファイルから SQL を実行します。[filename] を引数として受け取ります。
システム	`\!`	システムシェルコマンドを実行します。
Tee	`\T`	コマンド出力を標準出力とともに指定された [filename] に追加します。
使用	`\u`	別のデータベースに接続します。新しいデータベース名を引数として受け取ります。

サポートされているその他のコマンド

Spanner CLI は、追加のコマンドをサポートしています。詳細については、Spanner CLI コマンドをご覧ください。

サポートを受ける

Spanner CLI の問題を報告するには、新しい問題を作成します。

次のステップ

サポートされているすべての Spanner CLI コマンドの一覧を確認する。
サポートされているすべての gcloud spanner cli コマンドの一覧を確認する。