Spanner CLI 빠른 시작

이 페이지에서는 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는 다음과 같은 구성 옵션을 지원합니다.

project 옵션은 core/project 속성을 통해 가져오며, 또는 --project 옵션을 사용하여 프로젝트를 지정할 수 있습니다.
instance 옵션은 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에서 execute 옵션을 사용하거나 파일 기반 입출력 방식을 사용하여 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>와 같은 프롬프트가 표시되며, 다음 작업을 수행할 수 있습니다.

GoogleSQL 문을 직접 입력합니다.
트랜잭션을 실행합니다.
지원되는 메타 명령어를 사용합니다.

ENTER 키를 누르면 명령어나 SQL 문이 해당 Spanner 데이터베이스로 전송됩니다. 그러면 Spanner가 해당 명령어나 SQL 문을 실행합니다.

다음 예시에서는 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`와 동일합니다.
Delimiter	`\d`	문 구분자를 설정합니다. 기본 구분자는 세미콜론입니다.
종료	`\q`	Spanner CLI를 종료합니다. quit와 동일합니다.
Go	`\g`	SQL 문을 Spanner에 전송하고 실행합니다.
Help	`\h`	도움말 정보를 표시합니다. `\?`와 동일합니다.
Notee	`\t`	`\T`로 설정된 출력 파일에 쓰기를 중지합니다.
프롬프트	`\R`	사용자 프롬프트 문자열을 변경합니다.
종료	`\q`	Spanner CLI를 종료합니다. exit와 동일합니다.
Source	`\.`	입력 파일에 포함된 SQL을 실행합니다. [filename]을 인수로 사용합니다.
시스템	`\!`	시스템 셸 명령어를 실행합니다.
Tee	`\T`	표준 출력과 함께 지정된 [filename]에 명령어 출력을 추가합니다.
Use	`\u`	다른 데이터베이스에 연결합니다. 새 데이터베이스 이름을 인수로 사용합니다.

추가 지원 명령어

Spanner CLI는 이 외에도 추가 명령어를 지원합니다. 자세한 내용은 Spanner CLI 명령어를 참조하세요.

지원 받기

Spanner CLI 관련 문제를 보고하려면 새 이슈를 생성하세요.

다음 단계

지원되는 모든 Spanner CLI 명령어 목록을 확인합니다.
지원되는 모든 gcloud spanner cli 명령어 목록을 확인합니다.