gcloud CLI를 사용하여 데이터베이스 만들기 및 쿼리

목표

이 튜토리얼에서는 gcloud 명령줄 도구를 사용하는 다음 단계를 안내합니다.

  • Spanner 인스턴스, 데이터베이스, 스키마 만들기
  • 데이터베이스에 데이터를 쓰고 데이터에 SQL 쿼리 실행
  • 데이터베이스와 인스턴스를 삭제하여 정리

전체 gcloud spanner 참조는 gcloud spanner를 참조하세요.

가격 책정

이 튜토리얼에서는 Google Cloud의 비용 청구 가능한 구성요소인 Spanner를 사용합니다. Spanner 사용 비용에 대한 자세한 내용은 가격 책정을 참조하세요.

시작하기 전에

  1. 기본 Google Cloud 프로젝트 생성 및 설정, 결제 사용 설정, Cloud Spanner API 사용 설정, OAuth 2.0 설정을 다루는 gcloud CLI 설치 및 Cloud Spanner API 설정에 설명된 단계를 완료하여 Cloud Spanner API를 사용할 사용자 인증 정보를 가져옵니다.

특히 gcloud auth application-default login을 실행하여 사용자 인증 정보로 로컬 개발 환경을 설정해야 합니다.

기본 프로젝트 설정

아직 설정하지 않았으면 Google Cloud 프로젝트의 ID를 Google Cloud CLI의 기본 프로젝트로 설정합니다.

gcloud config set project PROJECT_ID

기본 프로젝트를 설정하지 않은 경우 --project PROJECT_ID를 gcloud spanner에 대한 첫 번째 인수로 각 명령어에 전달해야 합니다. 예를 들면 다음과 같습니다.

gcloud spanner --project=PROJECT_ID instance-configs list

인스턴스

Spanner를 처음 사용할 때는 인스턴스를 만들어야 합니다. 이 인스턴스는 Spanner 데이터베이스에서 사용하는 리소스를 할당한 것입니다. 인스턴스를 만들 때 데이터가 저장되는 위치와 인스턴스의 컴퓨팅 용량을 선택합니다.

인스턴스 및 인스턴스 구성

인스턴스를 만들려면 인스턴스 구성을 선택해야 합니다. 이는 Spanner 데이터의 지리적 위치와 복제를 정의하는 인스턴스의 청사진과 같은 것입니다.

인스턴스 구성 나열

인스턴스를 만들 때 해당 인스턴스에 있는 데이터베이스의 지리적 위치와 복제를 정의하는 인스턴스 구성을 지정합니다. 한 리전에 데이터를 저장하는 리전 구성, 동일한 국가의 두 리전에 데이터를 저장하는 이중 리전 또는 여러 리전에 데이터를 분산하는 멀티 리전 구성을 선택할 수 있습니다. 자세한 내용은 인스턴스 개요를 참조하세요.

프로젝트에 사용할 수 있는 인스턴스 구성 세트를 보려면 다음 명령어를 사용합니다.

gcloud spanner instance-configs list

리전, 이중 리전, 멀티 리전 구성 목록이 표시됩니다.

인스턴스 만들기

노드가 1개인 리전 인스턴스 구성 regional-us-central1을 사용하여 표시 이름이 My Instance인 test-instance라고 하는 인스턴스를 만들려면 다음을 실행합니다.

gcloud spanner instances create test-instance --config=regional-us-central1 \
    --description="My Instance" --nodes=1

위 명령어에서 인스턴스 이름은 test-instance로 설정되고 --description은 인스턴스의 표시 이름을 설정합니다. 이 두 값은 모두 Google Cloud Platform 프로젝트 내에서 고유해야 합니다.

기본 인스턴스 설정

명령어에 인스턴스를 지정하지 않은 경우 Spanner가 사용하는 기본 인스턴스를 설정할 수 있습니다. 기본 인스턴스를 설정하려면 다음을 사용하세요.

gcloud config set spanner/instance test-instance

데이터베이스 만들기

example-db라는 데이터베이스를 만듭니다. 데이터베이스 언어는 기본적으로 GoogleSQL입니다.

GoogleSQL 

gcloud spanner databases create example-db

PostgreSQL 

gcloud spanner databases create example-db --database-dialect=POSTGRESQL

스키마 업데이트

Spanner의 데이터 정의 언어(DDL)를 사용하여 테이블을 만들거나 변경하거나 삭제하고 색인을 만들거나 삭제합니다.

테이블 두 개를 만들겠습니다.

GoogleSQL 

gcloud spanner databases ddl update example-db \
--ddl='CREATE TABLE Singers ( SingerId INT64 NOT NULL, FirstName STRING(1024), LastName STRING(1024), SingerInfo BYTES(MAX) ) PRIMARY KEY (SingerId)'

gcloud spanner databases ddl update example-db \
--ddl='CREATE TABLE Albums ( SingerId INT64 NOT NULL, AlbumId INT64 NOT NULL, AlbumTitle STRING(MAX)) PRIMARY KEY (SingerId, AlbumId), INTERLEAVE IN PARENT Singers ON DELETE CASCADE'

PostgreSQL 

gcloud spanner databases ddl update example-db \
--ddl='CREATE TABLE Singers ( SingerId bigint NOT NULL, FirstName varchar(1024), LastName varchar(1024), SingerInfo bytea, PRIMARY KEY (SingerId) )'

gcloud spanner databases ddl update example-db \
--ddl='CREATE TABLE Albums ( SingerId bigint NOT NULL, AlbumId bigint NOT NULL, AlbumTitle varchar, PRIMARY KEY (SingerId, AlbumId) ) INTERLEAVE IN PARENT Singers ON DELETE CASCADE'

작업 진행 상황을 확인하려면 gcloud spanner operations describe를 사용합니다. 이 명령어를 사용하려면 작업 ID가 필요합니다.

작업 ID를 가져옵니다.

gcloud spanner operations list --instance="test-instance" \
--database=DATABASE-NAME --type=DATABASE_UPDATE_DDL

DATABASE-NAME를 데이터베이스 이름으로 바꿉니다.

gcloud spanner operations describe를 실행합니다.

gcloud spanner operations describe \
  --instance="test-instance" \
  --database="example-db" \
  projects/PROJECT-NAME/instances/test-instance/databases/example-db/operations/OPERATION-ID

다음을 바꿉니다.

  • PROJECT-NAME: 프로젝트 이름
  • OPERATION-ID: 확인할 작업의 작업 ID

결과는 다음과 유사합니다.

done: true
metadata:
...
progress:
- endTime: '2022-03-01T00:28:06.691403Z'
  progressPercent: 100
  startTime: '2022-03-01T00:28:04.221401Z'
- endTime: '2022-03-01T00:28:17.624588Z'
  startTime: '2022-03-01T00:28:06.691403Z'
  progressPercent: 100
...

데이터 쓰기

Google 데이터베이스에 샘플 데이터를 추가하겠습니다.

GoogleSQL 

gcloud spanner rows insert --database=example-db \
  --table=Singers \
  --data=SingerId=1,FirstName=Marc,LastName=Richards

gcloud spanner rows insert --database=example-db \
  --table=Singers \
  --data=SingerId=2,FirstName=Catalina,LastName=Smith

gcloud spanner rows insert --database=example-db \
  --table=Singers \
  --data=SingerId=3,FirstName=Alice,LastName=Trentor

gcloud spanner rows insert --database=example-db \
  --table=Albums \
  --data=SingerId=1,AlbumId=1,AlbumTitle="Total Junk"

gcloud spanner rows insert --database=example-db \
  --table=Albums \
  --data=SingerId=2,AlbumId=1,AlbumTitle="Green"

gcloud spanner rows insert --database=example-db \
  --table=Albums \
  --data=^:^SingerId=2:AlbumId=2:AlbumTitle="Go, Go, Go"

기본적으로 쉼표가 목록에서 항목을 구분하는 데 사용됩니다. 마지막 삽입 명령어에서 앨범 제목에 쉼표를 사용할 수 있도록 콜론(^:^)을 구분자로 지정했습니다.

PostgreSQL 

gcloud spanner databases execute-sql example-db \
  --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (1, 'Marc', 'Richards')"

gcloud spanner databases execute-sql example-db \
  --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (2, 'Catalina', 'Smith')"

gcloud spanner databases execute-sql example-db   \
  --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (3, 'Alice', 'Trentor')"

gcloud spanner databases execute-sql example-db   \
  --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (1, 1, 'Total Junk')"

gcloud spanner databases execute-sql example-db   \
  --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (2, 1, 'Green')"

gcloud spanner databases execute-sql example-db   \
  --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (2, 2, 'Go, Go, Go')"

SQL을 사용하여 데이터 쿼리

명령줄에서 쿼리를 실행합니다.

gcloud spanner databases execute-sql example-db \
    --sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'

Spanner SQL 참조에 대해서는 GoogleSQL 쿼리 문법 또는 PostgreSQL 쿼리 문법을 참조하세요.

execute-sql 명령어를 사용할 수 있는 플래그의 목록을 확인하려면 gcloud spanner databases execute-sql을 참조하세요.

삭제

이 튜토리얼에서 사용한 리소스에 대한 추가 비용이 Google Cloud 계정에 청구되지 않도록 하려면 데이터베이스와 새로 만든 인스턴스를 삭제합니다.

데이터베이스 삭제

기존 인스턴스를 삭제하려면 다음을 사용하세요.

gcloud spanner databases delete example-db

인스턴스 삭제

기존 인스턴스를 삭제하려면 다음을 사용하세요.

gcloud spanner instances delete test-instance

인스턴스를 삭제하면 해당 인스턴스의 모든 데이터베이스도 삭제됩니다. 인스턴스를 삭제하고 나면 되돌릴 수 없습니다.