목표
이 튜토리얼에서는 Spanner JDBC 드라이버를 사용하여 다음 단계를 안내합니다.
- Spanner 인스턴스와 데이터베이스 만들기
- 데이터베이스에서 데이터 읽기, 쓰기 및 데이터에서 SQL 쿼리 실행
- 데이터베이스 스키마 업데이트
- 읽기-쓰기 트랜잭션을 사용하여 데이터 업데이트
- 데이터베이스에 보조 색인 추가
- 색인을 사용하여 데이터 읽기 및 데이터에서 SQL 쿼리 실행
- 읽기 전용 트랜잭션을 사용하여 데이터 검색
비용
이 튜토리얼에서는 Google Cloud의 비용 청구 가능한 구성요소인 Spanner를 사용합니다. Spanner 사용 비용에 대한 자세한 내용은 가격 책정을 참조하세요.
시작하기 전에
설정에 설명된 단계를 완료하세요. 기본 Google Cloud 프로젝트 생성, 결제 사용 설정, Cloud Spanner API 사용 설정을 수행하고 Cloud Spanner API 사용에 필요한 사용자 인증 정보를 가져오기 위한 OAuth 2.0 설정을 완료해야 합니다.
특히 gcloud auth
application-default login
을 실행하여 사용자 인증 정보로 로컬 개발 환경을 설정해야 합니다.
로컬 JDBC 환경 준비
개발 머신에 아직 설치되어 있지 않다면 다음을 설치합니다.
샘플 앱 저장소를 로컬 머신에 클론합니다.
git clone https://github.com/googleapis/java-spanner-jdbc.git
Spanner 샘플 코드가 있는 디렉터리로 변경합니다.
cd java-spanner-jdbc/samples/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.
샘플 파일 살펴보기
샘플 저장소에는 JDBC와 함께 Spanner를 사용하는 방법을 보여주는 샘플이 있습니다.
pom.xml
은 프로젝트의 종속 항목에 Spanner JDBC 드라이버를 추가하고 이 튜토리얼에서 정의하는 자바 클래스로 실행 가능한 JAR 파일을 빌드하도록 어셈블리 플러그인을 구성합니다.
samples/snippets
디렉터리에서 샘플을 빌드합니다.
mvn package -DskipTests
데이터베이스 만들기
명령줄에서 다음을 실행하여 test-instance
라는 인스턴스에 example-db
라는 데이터베이스를 만듭니다.
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
createdatabase test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
createpgdatabase test-instance example-db
다음과 같이 표시됩니다.
Created database [projects/my-project/instances/test-instance/databases/example-db]
다음 코드에서는 데이터베이스와 데이터베이스에 테이블 두 개를 만듭니다.
GoogleSQL
PostgreSQL
다음 단계는 데이터베이스에 데이터 쓰기입니다.
JDBC 연결 만들기
읽기 또는 쓰기를 수행하려면 먼저Connection
를 만들어야 합니다. Spanner와의 모든 상호작용은 Connection
을 거쳐야 합니다. 데이터베이스 이름 및 기타 속성은 JDBC 연결 URL 및 java.util.Properties
집합에 지정됩니다.
GoogleSQL
PostgreSQL
지원되는 속성의 전체 목록은 연결 URL 속성을 참조하세요.
각 Connection
은 리소스를 사용하므로 더 이상 필요하지 않을 때 연결을 닫거나 연결 풀을 사용하여 애플리케이션 전체에서 연결을 재사용하는 것이 좋습니다.
Connection
Javadoc 참조 자료에서 자세히 알아보세요.
에뮬레이터에 JDBC 드라이버 연결
Spanner 에뮬레이터에 JDBC 드라이버를 연결하는 방법은 다음 두 가지입니다.
SPANNER_EMULATOR_HOST
환경 변수 설정: JDBC 드라이버를 에뮬레이터에 연결하도록 지시합니다. Spanner 인스턴스와 JDBC 연결 URL의 데이터베이스가 이미 에뮬레이터에 있어야 합니다.- 연결 URL에
autoConfigEmulator=true
추가: 이렇게 하면 JDBC 드라이버가 에뮬레이터에 연결하고, JDBC 연결 URL에 Spanner 인스턴스와 데이터베이스가 없는 경우 이를 자동으로 생성하도록 지시합니다.
이 예시에서는 autoConfigEmulator=true
연결 URL 옵션을 사용하는 방법을 보여줍니다.
GoogleSQL
PostgreSQL
DML을 사용하여 데이터 쓰기
읽기-쓰기 트랜잭션에서 데이터 조작 언어(DML)를 사용하여 데이터를 삽입할 수 있습니다.
PreparedStatement.executeUpdate()
메서드를 사용하여 DML 문을 실행합니다.
GoogleSQL
PostgreSQL
다음 명령어로 샘플을 실행합니다.
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writeusingdml test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writeusingdmlpg test-instance example-db
다음과 같이 표시됩니다.
4 records inserted.
DML 배치로 데이터 쓰기
PreparedStatement#addBatch()
및 PreparedStatement#executeBatch()
메서드를 사용하여 여러 DML 문을 일괄 실행합니다.
GoogleSQL
PostgreSQL
다음 명령어로 샘플을 실행합니다.
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writeusingdmlbatch test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writeusingdmlbatchpg test-instance example-db
다음과 같이 표시됩니다.
3 records inserted.
변형을 사용하여 데이터 쓰기
변형을 사용하여 데이터를 삽입할 수도 있습니다.
Mutation
객체를 사용하여 데이터를 작성할 수 있습니다.
Mutation
객체는 변형 작업의 컨테이너입니다. Mutation
은 Spanner가 Spanner 데이터베이스의 여러 행과 테이블에 원자적으로 적용할 수 있는 일련의 삽입, 업데이트, 삭제를 나타냅니다.
Mutation
클래스의 newInsertBuilder()
메서드는 테이블에 새 행을 삽입하는 INSERT
변형을 생성합니다. 행이 이미 존재할 경우 쓰기가 실패합니다. 또는 newInsertOrUpdateBuilder
메서드를 사용하여 INSERT_OR_UPDATE
변형을 생성할 수도 있습니다. 이 변형은 행이 이미 있으면 열 값을 업데이트합니다.
CloudSpannerJdbcConnection
인터페이스의 write()
메서드는 변형을 씁니다. 단일 배치의 모든 변형은 원자적으로 적용됩니다.
Spanner JDBC Connection
에서 CloudSpannerJdbcConnection
인터페이스를 래핑 해제할 수 있습니다.
다음 코드는 변형을 사용하여 데이터를 쓰는 방법을 보여줍니다.
GoogleSQL
PostgreSQL
다음 명령어로 샘플을 실행합니다.
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
write test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writepg test-instance example-db
다음과 같이 표시됩니다.
Inserted 10 rows.
SQL을 사용하여 데이터 쿼리
Spanner는 데이터 읽기용 SQL 인터페이스를 지원하며, 개발자는 Google Cloud CLI를 사용하여 명령줄에서 액세스하거나 Spanner JDBC 드라이버를 사용하여 프로그래매틱 방식으로 액세스할 수 있습니다.
명령줄에서
다음 SQL 문을 실행하여 Albums
테이블에서 모든 열의 값을 읽습니다.
GoogleSQL
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'
PostgreSQL
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
Spanner JDBC 드라이버 사용
명령줄에서 SQL 문을 실행하는 것 외에도 Spanner JDBC 드라이버를 사용하여 동일한 SQL 문을 프로그래매틱 방식으로 실행할 수 있습니다.
다음과 같은 메서드와 클래스가 SQL 쿼리 실행에 사용됩니다.Connection
인터페이스의createStatement()
메서드: SQL 문을 실행하기 위한 새 문 객체를 만들려면 이 메서드를 사용합니다.Statement
클래스의executeQuery(String)
메서드: 데이터베이스에 쿼리를 실행하려면 이 메서드를 사용합니다.Statement
클래스: SQL 문자열을 실행할 때 사용합니다.ResultSet
클래스: SQL 문으로 반환된 데이터에 액세스하려면 사용합니다.
다음은 쿼리를 실행하고 데이터에 액세스하는 방법입니다.
GoogleSQL
PostgreSQL
다음 명령어로 샘플을 실행합니다.
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
query test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querypg test-instance 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
의 특정 값이 포함된 레코드를 쿼리합니다.
파라미터와 함께 쿼리를 실행하려면 java.sql.PreparedStatement
를 사용합니다.
GoogleSQL
PostgreSQL
다음 명령어로 샘플을 실행합니다.
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querywithparameter test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querywithparameterpg test-instance example-db
결과:
12 Melissa Garcia
데이터베이스 스키마 업데이트
Albums
테이블에 MarketingBudget
이라는 새 열을 추가해야 한다고 가정합니다. 기존 테이블에 새 열을 추가하려면 데이터베이스 스키마를 업데이트해야 합니다. Spanner는 데이터베이스에서 트래픽이 계속 처리되는 동안 데이터베이스의 스키마 업데이트를 지원합니다. 스키마 업데이트 시 데이터베이스를 오프라인으로 전환할 필요가 없고 전체 테이블 또는 열을 잠그지 않습니다. 스키마 업데이트 중에도 데이터베이스에 계속 데이터를 쓸 수 있습니다. 스키마 업데이트에서 지원되는 스키마 업데이트와 스키마 변경 성능에 대해 자세히 알아보세요.
열 추가
Google Cloud CLI를 사용하여 명령줄에서 열을 추가하거나 Spanner JDBC 드라이버를 사용해서 프로그래매틱 방식으로 열을 추가할 수 있습니다.
명령줄에서
다음과 같은 ALTER TABLE
명령어를 사용하여 테이블에 새 열을 추가합니다.
GoogleSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget INT64'
PostgreSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE albums ADD COLUMN marketing_budget BIGINT'
다음과 같이 표시됩니다.
Schema updating...done.
Spanner JDBC 드라이버 사용
java.sql.Statement
클래스의 execute(String)
메서드를 사용하여 스키마를 수정합니다.
GoogleSQL
PostgreSQL
다음 명령어로 샘플을 실행합니다.
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
addmarketingbudget test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
addmarketingbudgetpg test-instance example-db
다음과 같이 표시됩니다.
Added MarketingBudget column.
DDL 일괄 실행
여러 스키마 수정을 일괄 실행하는 것이 좋습니다. java.sql.Statement
의 addBatch(String)
메서드를 사용하여 여러 DDL 문을 배치에 추가합니다.
GoogleSQL
PostgreSQL
다음 명령어로 샘플을 실행합니다.
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
ddlbatch test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
ddlbatchpg test-instance example-db
다음과 같이 표시됩니다.
Added Venues and Concerts tables.
새 열에 데이터 쓰기
다음 코드는 새 열에 데이터를 씁니다. 이 코드는 MarketingBudget
을 Albums(1, 1)
로 키가 지정된 행에서는 100000
으로, Albums(2, 2)
로 키가 지정된 행에서는 500000
으로 설정합니다.
GoogleSQL
PostgreSQL
다음 명령어로 샘플을 실행합니다.
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
update test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
updatepg test-instance example-db
다음과 비슷한 출력이 표시됩니다.
Updated albums
방금 쓴 값을 가져오기 위해 SQL 쿼리 또는 읽기 호출을 실행할 수도 있습니다.
다음은 쿼리를 실행하는 코드입니다.
GoogleSQL
PostgreSQL
이 쿼리를 실행하려면 다음 명령어를 실행합니다.
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querymarketingbudget test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querymarketingbudgetpg test-instance example-db
다음과 같이 표시됩니다.
1 1 100000
1 2 null
2 1 null
2 2 500000
2 3 null
데이터 업데이트
읽기-쓰기 트랜잭션에서 DML을 사용하여 데이터를 업데이트할 수 있습니다.
JDBC에서 읽기-쓰기 트랜잭션을 실행하려면 AutoCommit=false
를 설정합니다.
GoogleSQL
PostgreSQL
다음 명령어로 샘플을 실행합니다.
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writewithtransactionusingdml test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writewithtransactionusingdmlpg test-instance example-db
트랜잭션 태그 및 요청 태그
트랜잭션 태그 및 요청 태그를 사용하여 Spanner에서 트랜잭션 및 쿼리를 문제 해결할 수 있습니다. TRANSACTION_TAG
및 STATEMENT_TAG
세션 변수를 사용하여 JDBC에서 트랜잭션 태그 및 요청 태그를 설정할 수 있습니다.
GoogleSQL
PostgreSQL
다음 명령어로 샘플을 실행합니다.
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
tags test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
tagspg test-instance example-db
읽기 전용 트랜잭션을 사용하여 데이터 검색
같은 타임스탬프에서 읽기를 하나 이상 실행한다고 가정해 봅시다. 읽기 전용 트랜잭션은 트랜잭션 커밋 기록의 일관된 프리픽스를 관찰하므로 애플리케이션이 항상 일관된 데이터를 가져옵니다.
java.sql.Connection
에서 ReadOnly=true
및 AutoCommit=false
를 설정하거나 SET TRANSACTION READ ONLY
SQL 문을 사용하여 읽기 전용 트랜잭션을 실행합니다.
다음은 같은 읽기 전용 트랜잭션에서 쿼리를 실행하고 읽기를 수행하는 방법을 보여줍니다.
GoogleSQL
PostgreSQL
다음 명령어로 샘플을 실행합니다.
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
readonlytransaction test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
readonlytransactionpg test-instance 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는 파티션을 나눈 쿼리만 지원합니다.
GoogleSQL
PostgreSQL
다음 명령어로 샘플을 실행합니다.
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
databoost test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
databoostpg test-instance example-db
파티션을 나눈 쿼리를 실행하고 JDBC 드라이버에 Data Boost를 사용하는 방법에 대한 자세한 내용은 다음을 참조하세요.
Partitioned DML
Partitioned DML은 다음과 같은 유형의 일괄 업데이트와 삭제를 위해 설계되었습니다.
- 정기적 클린업 및 가비지 컬렉션:
- 새 열을 기본값으로 백필:
PostgreSQL
다음 명령어로 샘플을 실행합니다.
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
pdml test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
pdmlpg test-instance example-db
AUTOCOMMIT_DML_MODE
에 대한 자세한 내용은 다음을 참조하세요.
삭제
이 튜토리얼에서 사용한 리소스에 대한 추가 비용이 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를 Spring Data JPA(GoogleSQL 언어)와 통합하는 방법 알아보기
- Spanner를 Spring Data JPA(PostgreSQL 언어)와 통합하는 방법 알아보기
- Spanner를 Hibernate ORM(GoogleSQL 언어)과 통합하는 방법(GoogleSQL 언어) 알아보기
- Spanner를 Hibernate ORM과 통합하는 방법(PostgreSQL 언어) 알아보기
- JDBC 세션 관리 명령어(GoogleSQL)에 대해 자세히 알아보기
- JDBC 세션 관리 명령어(PostgreSQL)에 대해 자세히 알아보기
가상 머신 인스턴스에서 Spanner에 액세스하는 방법을 알아봅니다.
클라이언트 라이브러리를 사용하여 Cloud 서비스에 인증에서 사용자 인증 정보의 승인 및 인증에 대해 알아봅니다.
Spanner 스키마 설계 권장사항에 대해 자세히 알아봅니다.