목표
이 튜토리얼에서는 PostgreSQL 드라이버용 Spanner PGAdapter 로컬 프록시를 사용하여 다음 단계를 안내합니다.
- Spanner 인스턴스와 데이터베이스 만들기
- 데이터베이스에서 데이터 읽기, 쓰기 및 데이터에서 SQL 쿼리 실행
- 데이터베이스 스키마 업데이트
- 읽기-쓰기 트랜잭션을 사용하여 데이터 업데이트
- 데이터베이스에 보조 색인 추가
- 색인을 사용하여 데이터 읽기 및 데이터에서 SQL 쿼리 실행
- 읽기 전용 트랜잭션을 사용하여 데이터 검색
비용
이 튜토리얼에서는 Google Cloud의 비용 청구 가능한 구성요소인 Spanner를 사용합니다. Spanner 사용 비용에 대한 자세한 내용은 가격 책정을 참조하세요.
시작하기 전에
설정에 설명된 단계를 완료하세요. 기본 Google Cloud 프로젝트 생성, 결제 사용 설정, Cloud Spanner API 사용 설정을 수행하고 Cloud Spanner API 사용에 필요한 사용자 인증 정보를 가져오기 위한 OAuth 2.0 설정을 완료해야 합니다.
특히 gcloud auth
application-default login
을 실행하여 사용자 인증 정보로 로컬 개발 환경을 설정해야 합니다.
로컬 PGAdapter 환경 준비
PostgreSQL 드라이버를 PGAdapter와 함께 사용하여 Spanner에 연결할 수 있습니다. PGAdapter는 PostgreSQL 네트워크 프로토콜을 Spanner gRPC 프로토콜로 변환하는 로컬 프록시입니다.
PGAdapter를 실행하려면 Java 또는 Docker가 필요합니다.
아직 설치되어 있지 않다면 개발 머신에 다음 중 하나를 설치합니다.
샘플 앱 저장소를 로컬 머신에 클론합니다.
git clone https://github.com/GoogleCloudPlatform/pgadapter.git
Spanner 샘플 코드가 있는 디렉터리로 변경합니다.
psql
cd pgadapter/samples/snippets/psql-snippets
자바
cd pgadapter/samples/snippets/java-snippets mvn package -DskipTests
Go
cd pgadapter/samples/snippets/golang-snippets
Node.js
cd pgadapter/samples/snippets/nodejs-snippets npm install
Python
cd pgadapter/samples/snippets/python-snippets python -m venv ./venv pip install -r requirements.txt cd samples
C#
cd pgadapter/samples/snippets/dotnet-snippets
인스턴스 만들기
Spanner를 처음 사용할 때는 인스턴스를 만들어야 합니다. 이 인스턴스는 Spanner 데이터베이스에서 사용하는 리소스를 할당한 것입니다. 인스턴스를 만들 때는 인스턴스 구성을 선택합니다. 이 구성에 따라 데이터 저장 위치와 사용할 노드 수가 결정되고, 또한 노드 수에 따라 인스턴스의 제공 리소스 및 스토리지 리소스 양이 결정됩니다.
us-central1
리전에 1개의 노드로 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.
샘플 파일 살펴보기
샘플 저장소에는 PGAdapter와 함께 Spanner를 사용하는 방법을 보여주는 샘플이 있습니다.
Spanner 사용 방법을 보여주는samples/snippets
폴더를 살펴보세요. 코드는 새 데이터베이스를 만들고 사용하는 방법을 보여줍니다. 데이터는 스키마 및 데이터 모델 페이지에 나와 있는 스키마 예시를 사용합니다.
PGAdapter 시작
로컬 개발 머신에서 PGAdapter를 시작하고 생성한 인스턴스로 가리킵니다.
다음 명령어는 gcloud auth application-default login
을 실행한 것으로 가정합니다.
자바 애플리케이션
wget https://storage.googleapis.com/pgadapter-jar-releases/pgadapter.tar.gz \
&& tar -xzvf pgadapter.tar.gz
java -jar pgadapter.jar -i test-instance
Docker
docker pull gcr.io/cloud-spanner-pg-adapter/pgadapter
docker run \
--name pgadapter \
--rm -d -p 5432:5432 \
-v "$HOME/.config/gcloud":/gcloud:ro \
--env CLOUDSDK_CONFIG=/gcloud \
gcr.io/cloud-spanner-pg-adapter/pgadapter \
-i test-instance -x
에뮬레이터
docker pull gcr.io/cloud-spanner-pg-adapter/pgadapter-emulator
docker run \
--name pgadapter-emulator \
--rm -d \
-p 5432:5432 \
-p 9010:9010 \
-p 9020:9020 \
gcr.io/cloud-spanner-pg-adapter/pgadapter-emulator
그러면 삽입된 Spanner 에뮬레이터로 PGAdapter가 시작됩니다. 이 임베디드 에뮬레이터는 연결할 Spanner 인스턴스 또는 데이터베이스를 자동으로 생성하므로 미리 수동으로 만들 필요가 없습니다.
프로덕션에서는 사이드카 컨테이너 또는 프로세스 내 종속 항목으로 PGAdapter를 실행하는 것이 좋습니다. 프로덕션에 PGAdapter를 배포하는 방법에 관한 자세한 내용은 PGAdapter 실행 메서드 선택을 참고하세요.
데이터베이스 만들기
gcloud spanner databases create example-db --instance=test-instance \
--database-dialect=POSTGRESQL
다음과 같이 표시됩니다.
Creating database...done.
테이블 만들기
다음 코드는 데이터베이스에 테이블 2개를 만듭니다.
psql
자바
Go
Node.js
Python
C#
다음 명령어를 사용하여 샘플을 실행합니다.
psql
PGDATABASE=example-db ./create_tables.sh example-db
자바
java -jar target/pgadapter-snippets/pgadapter-samples.jar createtables example-db
Go
go run sample_runner.go createtables example-db
Node.js
npm start createtables example-db
Python
python create_tables.py example-db
C#
dotnet run createtables example-db
다음 단계는 데이터베이스에 데이터 쓰기입니다.
연결 만들기
읽기 또는 쓰기를 수행하려면 먼저 PGAdapter에 대한 연결을 만들어야 합니다. Spanner와의 모든 상호작용은Connection
을 거쳐야 합니다. 데이터베이스 이름은 연결 문자열에 지정됩니다.
psql
자바
Go
Node.js
Python
C#
다음 명령어를 사용하여 샘플을 실행합니다.
psql
PGDATABASE=example-db ./create_connection.sh
자바
java -jar target/pgadapter-snippets/pgadapter-samples.jar createconnection example-db
Go
go run sample_runner.go createconnection example-db
Node.js
npm start createconnection example-db
Python
python create_connection.py example-db
C#
dotnet run createconnection example-db
DML을 사용하여 데이터 쓰기
읽기-쓰기 트랜잭션에서 데이터 조작 언어(DML)를 사용하여 데이터를 삽입할 수 있습니다.
다음 샘플에서는 PostgreSQL 드라이버를 사용하여 Spanner에서 DML 문을 실행하는 방법을 보여줍니다.
psql
자바
Go
Node.js
Python
C#
다음 명령어를 사용하여 샘플을 실행합니다.
psql
PGDATABASE=example-db ./write_data_with_dml.sh
자바
java -jar target/pgadapter-snippets/pgadapter-samples.jar writeusingdml example-db
Go
go run sample_runner.go writeusingdml example-db
Node.js
npm start writeusingdml example-db
Python
python write_data_with_dml.py example-db
C#
dotnet run writeusingdml example-db
다음과 같은 응답이 표시됩니다.
4 records inserted.
DML 배치로 데이터 쓰기
PGAdapter는 DML 일괄 실행을 지원합니다. 한 번의 일괄 작업으로 여러 DML 문을 보내면 Spanner로의 왕복 횟수가 줄어들고 애플리케이션 성능이 향상됩니다.
psql
자바
Go
Node.js
Python
C#
다음 명령어로 샘플을 실행합니다.
psql
PGDATABASE=example-db ./write_data_with_dml_batch.sh
자바
java -jar target/pgadapter-snippets/pgadapter-samples.jar writeusingdmlbatch example-db
Go
go run sample_runner.go writeusingdmlbatch example-db
Node.js
npm start writeusingdmlbatch example-db
Python
python write_data_with_dml_batch.py example-db
C#
dotnet run writeusingdmlbatch example-db
다음과 같이 표시됩니다.
3 records inserted.
변형을 사용하여 데이터 쓰기
변형을 사용하여 데이터를 삽입할 수도 있습니다.
PGAdapter는 PostgreSQL COPY
명령어를 변형으로 변환합니다. COPY
를 사용하는 것이 Spanner 데이터베이스에 데이터를 빠르게 삽입하는 가장 효율적인 방법입니다.
COPY
작업은 기본적으로 원자적입니다. Spanner의 원자적 작업은 커밋 크기 한도에 의해 제한됩니다.
자세한 내용은 CRUD 한도를 참조하세요.
다음 예는 비원자적 COPY
작업을 실행하는 방법을 보여줍니다. 이를 통해 COPY
작업이 커밋 크기 제한을 초과할 수 있습니다.
psql
자바
Go
Node.js
Python
C#
다음 명령어로 샘플을 실행합니다.
psql
PGDATABASE=example-db ./write_data_with_copy.sh
자바
java -jar target/pgadapter-snippets/pgadapter-samples.jar write example-db
Go
go run sample_runner.go write example-db
Node.js
npm start write example-db
Python
python write_data_with_copy.py example-db
C#
dotnet run write example-db
다음과 같이 표시됩니다.
Copied 5 singers
Copied 5 albums
SQL을 사용하여 데이터 쿼리
Spanner는 데이터 읽기용 SQL 인터페이스를 지원하며, 개발자는 Google Cloud CLI를 사용하여 명령줄에서 액세스하거나 PostgreSQL 드라이버를 사용하여 프로그래매틱 방식으로 액세스할 수 있습니다.
명령줄에서
다음 SQL 문을 실행하여 Albums
테이블에서 모든 열의 값을 읽습니다.
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
PostgreSQL 드라이버 사용
명령줄에서 SQL 문을 실행하는 방법 외에 PostgreSQL 드라이버를 사용하여 프로그래매틱 방식으로 SQL 문을 실행하는 방법도 있습니다.
psql
자바
Go
Node.js
Python
C#
다음 명령어를 사용하여 샘플을 실행합니다.
psql
PGDATABASE=example-db ./query_data.sh
자바
java -jar target/pgadapter-snippets/pgadapter-samples.jar query example-db
Go
go run sample_runner.go query example-db
Node.js
npm start query example-db
Python
python query_data.py example-db
C#
dotnet run query 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
의 특정 값이 포함된 레코드를 쿼리합니다.
psql
자바
Go
Node.js
Python
C#
다음 명령어를 사용하여 샘플을 실행합니다.
psql
PGDATABASE=example-db ./query_data_with_parameter.sh
자바
java -jar target/pgadapter-snippets/pgadapter-samples.jar querywithparameter example-db
Go
go run sample_runner.go querywithparameter example-db
Node.js
npm start querywithparameter example-db
Python
python query_data_with_parameter.py example-db
C#
dotnet run querywithparameter example-db
결과:
12 Melissa Garcia
데이터베이스 스키마 업데이트
Albums
테이블에 MarketingBudget
이라는 새 열을 추가해야 한다고 가정합니다. 기존 테이블에 새 열을 추가하려면 데이터베이스 스키마를 업데이트해야 합니다. Spanner는 데이터베이스에서 트래픽이 계속 처리되는 동안 데이터베이스의 스키마 업데이트를 지원합니다. 스키마 업데이트 시 데이터베이스를 오프라인으로 전환할 필요가 없고 전체 테이블 또는 열을 잠그지 않습니다. 스키마 업데이트 중에도 데이터베이스에 계속 데이터를 쓸 수 있습니다. 스키마 업데이트에서 지원되는 스키마 업데이트와 스키마 변경 성능에 대해 자세히 알아보세요.
열 추가
Google Cloud CLI를 사용하여 명령줄에서 열을 추가하거나 PostgreSQL 드라이버를 사용해서 프로그래매틱 방식으로 열을 추가할 수 있습니다.
명령줄에서
다음과 같은 ALTER TABLE
명령어를 사용하여 테이블에 새 열을 추가합니다.
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE albums ADD COLUMN marketing_budget BIGINT'
다음과 같이 표시됩니다.
Schema updating...done.
PostgreSQL 드라이버 사용
PostgreSQL 드라이버를 사용하여 DDL 문을 실행하여 스키마를 수정합니다.
psql
자바
Go
Node.js
Python
C#
다음 명령어를 사용하여 샘플을 실행합니다.
psql
PGDATABASE=example-db ./add_column.sh
자바
java -jar target/pgadapter-snippets/pgadapter-samples.jar addmarketingbudget example-db
Go
go run sample_runner.go addmarketingbudget example-db
Node.js
npm start addmarketingbudget example-db
Python
python add_column.py example-db
C#
dotnet run addmarketingbudget example-db
다음과 같이 표시됩니다.
Added marketing_budget column
DDL 일괄 실행
여러 스키마 수정을 일괄 실행하는 것이 좋습니다.
PostgreSQL 드라이버의 기본 제공 일괄 처리 기능을 사용하거나, 모든 DDL 문을 세미콜론으로 구분된 하나의 SQL 문자열로 제출하거나, START BATCH DDL
및 RUN BATCH
문을 사용하여 여러 DDL 문을 하나의 일괄 처리로 실행할 수 있습니다.
psql
자바
Go
Node.js
Python
C#
다음 명령어로 샘플을 실행합니다.
psql
PGDATABASE=example-db ./ddl_batch.sh
자바
java -jar target/pgadapter-snippets/pgadapter-samples.jar ddlbatch example-db
Go
go run sample_runner.go ddlbatch example-db
Node.js
npm start ddlbatch example-db
Python
python ddl_batch.py example-db
C#
dotnet run ddlbatch example-db
다음과 같이 표시됩니다.
Added venues and concerts tables
새 열에 데이터 쓰기
다음 코드는 새 열에 데이터를 씁니다. 이 코드는 MarketingBudget
을 Albums(1, 1)
로 키가 지정된 행에서는 100000
으로, Albums(2, 2)
로 키가 지정된 행에서는 500000
으로 설정합니다.
COPY
명령어를 변형으로 변환합니다. COPY
명령어는 기본적으로 Insert
변형으로 변환됩니다.
set spanner.copy_upsert=true
를 실행하여 COPY
명령어를 InsertOrUpdate
변형으로 변환합니다. 이렇게 하면 Spanner의 기존 데이터를 업데이트할 수 있습니다.
psql
자바
Go
Node.js
Python
C#
다음 명령어를 사용하여 샘플을 실행합니다.
psql
PGDATABASE=example-db ./update_data_with_copy.sh
자바
java -jar target/pgadapter-snippets/pgadapter-samples.jar update example-db
Go
go run sample_runner.go update example-db
Node.js
npm start update example-db
Python
python update_data_with_copy.py example-db
C#
dotnet run update example-db
다음과 같이 표시됩니다.
Updated 2 albums
방금 쓴 값을 가져오기 위해 SQL 쿼리를 실행할 수도 있습니다.
다음은 쿼리를 실행하는 코드입니다.
psql
자바
Go
Node.js
Python
C#
다음 명령어를 사용하여 쿼리를 실행합니다.
psql
PGDATABASE=example-db ./query_data_with_new_column.sh
자바
java -jar target/pgadapter-snippets/pgadapter-samples.jar querymarketingbudget example-db
Go
go run sample_runner.go querymarketingbudget example-db
Node.js
npm start querymarketingbudget example-db
Python
python query_data_with_new_column.py example-db
C#
dotnet run querymarketingbudget example-db
다음과 같이 표시됩니다.
1 1 100000
1 2 null
2 1 null
2 2 500000
2 3 null
데이터 업데이트
읽기-쓰기 트랜잭션에서 DML을 사용하여 데이터를 업데이트할 수 있습니다.
psql
자바
Go
Node.js
Python
C#
다음 명령어를 사용하여 샘플을 실행합니다.
psql
PGDATABASE=example-db ./update_data_with_transaction.sh
자바
java -jar target/pgadapter-snippets/pgadapter-samples.jar writewithtransactionusingdml example-db
Go
go run sample_runner.go writewithtransactionusingdml example-db
Node.js
npm start writewithtransactionusingdml example-db
Python
python update_data_with_transaction.py example-db
C#
dotnet run writewithtransactionusingdml example-db
다음과 같이 표시됩니다.
Transferred marketing budget from Album 2 to Album 1
트랜잭션 태그 및 요청 태그
트랜잭션 태그 및 요청 태그를 사용하여 Spanner에서 트랜잭션 및 쿼리를 문제 해결할 수 있습니다. SPANNER.TRANSACTION_TAG
및 SPANNER.STATEMENT_TAG
세션 변수를 사용하여 트랜잭션 태그 및 요청 태그를 설정할 수 있습니다.
psql
자바
Go
Node.js
Python
C#
다음 명령어를 사용하여 샘플을 실행합니다.
psql
PGDATABASE=example-db ./tags.sh
자바
java -jar target/pgadapter-snippets/pgadapter-samples.jar tags example-db
Go
go run sample_runner.go tags example-db
Node.js
npm start tags example-db
Python
python tags.py example-db
C#
dotnet run tags example-db
읽기 전용 트랜잭션을 사용하여 데이터 검색
같은 타임스탬프에서 읽기를 하나 이상 실행한다고 가정해 봅시다. 읽기 전용 트랜잭션은 트랜잭션 커밋 기록의 일관된 프리픽스를 관찰하므로 애플리케이션이 항상 일관된 데이터를 가져옵니다.
연결을 읽기 전용으로 설정하거나 SET TRANSACTION READ ONLY
SQL 문을 사용하여 읽기 전용 트랜잭션을 실행합니다.
다음은 같은 읽기 전용 트랜잭션에서 쿼리를 실행하고 읽기를 수행하는 방법을 보여줍니다.
psql
자바
Go
Node.js
Python
C#
다음 명령어로 샘플을 실행합니다.
psql
PGDATABASE=example-db ./read_only_transaction.sh
자바
java -jar target/pgadapter-snippets/pgadapter-samples.jar readonlytransaction example-db
Go
go run sample_runner.go readonlytransaction example-db
Node.js
npm start readonlytransaction example-db
Python
python read_only_transaction.py example-db
C#
dotnet run readonlytransaction 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보다 지연 시간이 깁니다.
Data Boost를 사용하면 프로비저닝된 Spanner 인스턴스의 기존 워크로드에 거의 영향을 주지 않고 분석 쿼리와 데이터 내보내기를 실행할 수 있습니다. Data Boost는 파티션을 나눈 쿼리만 지원합니다.
psql
자바
Go
Node.js
Python
C#
다음 명령어를 사용하여 샘플을 실행합니다.
psql
PGDATABASE=example-db ./data_boost.sh
자바
java -jar target/pgadapter-snippets/pgadapter-samples.jar databoost example-db
Go
go run sample_runner.go databoost example-db
Node.js
npm start databoost example-db
Python
python data_boost.py example-db
C#
dotnet run databoost example-db
파티션을 나눈 쿼리를 실행하고 PGAdapter에 Data Boost를 사용하는 방법에 대한 자세한 내용은 Data Boost 및 파티션을 나눈 쿼리 문을 참고하세요.
Partitioned DML
Partitioned DML은 다음과 같은 유형의 일괄 업데이트와 삭제를 위해 설계되었습니다.
- 정기적 클린업 및 가비지 컬렉션:
- 새 열을 기본값으로 백필:
psql
자바
Go
Node.js
Python
C#
다음 명령어를 사용하여 샘플을 실행합니다.
psql
PGDATABASE=example-db ./partitioned_dml.sh
자바
java -jar target/pgadapter-snippets/pgadapter-samples.jar partitioneddml example-db
Go
go run sample_runner.go partitioneddml example-db
Node.js
npm start partitioneddml example-db
Python
python partitioned_dml.py example-db
C#
dotnet run datpartitioneddmlboost example-db
삭제
이 튜토리얼에서 사용한 리소스에 대한 추가 비용이 Cloud Billing 계정에 청구되지 않도록 하려면 데이터베이스와 새로 만든 인스턴스를 삭제합니다.
데이터베이스 삭제
인스턴스를 삭제하면 인스턴스 내의 모든 데이터베이스가 자동으로 삭제됩니다. 다음 단계는 인스턴스를 삭제하지 않고 데이터베이스를 삭제하는 방법을 보여줍니다. 인스턴스에 대한 비용은 여전히 발생합니다.
명령줄에서
gcloud spanner databases delete example-db --instance=test-instance
Google Cloud 콘솔 사용
Google Cloud 콘솔에서 Spanner 인스턴스 페이지로 이동합니다.
인스턴스를 클릭합니다.
삭제할 데이터베이스를 클릭합니다.
데이터베이스 세부정보 페이지에서 삭제를 클릭합니다.
데이터베이스 삭제 여부를 확인하고 삭제를 클릭합니다.
인스턴스 삭제
인스턴스를 삭제하면 해당 인스턴스에서 만든 모든 데이터베이스가 자동으로 삭제됩니다.
명령줄에서
gcloud spanner instances delete test-instance
Google Cloud 콘솔 사용
Google Cloud 콘솔에서 Spanner 인스턴스 페이지로 이동합니다.
인스턴스를 클릭합니다.
삭제를 클릭합니다.
인스턴스 삭제 여부를 확인하고 삭제를 클릭합니다.
다음 단계
가상 머신 인스턴스에서 Spanner에 액세스하는 방법을 알아봅니다.
클라이언트 라이브러리를 사용하여 Cloud 서비스에 인증에서 사용자 인증 정보의 승인 및 인증에 대해 알아봅니다.
Spanner 스키마 설계 권장사항에 대해 자세히 알아봅니다.