Spanner와 Liquibase와 통합

이 페이지에서는 Liquibase를 사용하여 Spanner 데이터베이스 스키마 변경사항을 관리하는 방법을 설명합니다.

Liquibase는 데이터베이스 스키마 변경사항의 추적, 관리, 적용을 위한 데이터베이스에 종속된 오픈소스 라이브러리입니다. 또한 XML, YAML, JSON과 같은 선언적 형식은 물론 SQL을 지원합니다.

Liquibase는 Spanner 데이터베이스를 타겟팅할 수 있습니다. 모든 Spanner 기능을 지원하지만 몇 가지 제한사항이 있습니다.

일반적인 제한사항을 보려면 제한사항을 참조하세요.
Liquibase 요구사항, 지원되는 변경 유형, 제한사항 등 PostgreSQL 언어 데이터베이스에 관한 자세한 내용은 PGAdapter 및 Liquibase를 참고하세요.

Liquibase 설치

GoogleSQL 언어 데이터베이스에서 Liquibase를 사용하려면 Spanner Liquibase 확장 프로그램을 설치해야 합니다. PostgreSQL 언어 데이터베이스의 경우 Liquibase는 PGAdapter와 함께 기본 제공되는 PostgreSQL 지원을 사용할 수 있습니다.

GoogleSQL

Liquibase 문서의 안내에 따라 Liquibase를 설치 및 구성하고 데이터베이스의 스냅샷을 찍습니다. liquibase.properties 구성 파일에서 url 속성을 다음과 같이 설정합니다.
```
jdbc:cloudspanner:/projects/PROJECT/instances/INSTANCE/databases/DATABASE
```
liquibase.properties 구성 파일에는 이 속성만 포함할 수 있습니다. 다른 속성은 선택사항입니다.
GitHub에서 Spanner Liquibase 확장 프로그램 출시 버전 페이지로 이동하고 최신 출시 버전을 선택합니다.
liquibase-spanner-x.y.z-all.jar이라는 JAR 파일을 선택하고 다운로드합니다. 여기서 x.y.z는 확장 프로그램 버전 번호를 나타냅니다. 예를 들면 liquibase-spanner-4.17.0-all.jar입니다.
다운로드한 JAR 파일을 Liquibase lib 디렉터리에 저장합니다. JAR 파일에는 확장 프로그램, Spanner SDK, Spanner JDBC 드라이버가 포함되어 있습니다.

PostgreSQL

PGAdapter가 Liquibase를 설치할 머신에서 시작되고 실행되는지 확인합니다. 자세한 내용은 PGAdapter 시작을 참조하세요.
Liquibase 문서의 안내에 따라 Liquibase를 설치 및 구성하고 데이터베이스의 스냅샷을 찍습니다. liquibase.properties 구성 파일에서 url 속성을 다음과 같이 설정합니다.
```
jdbc:postgresql://localhost:5432/DATABASE_NAME?options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction
```
liquibase.properties 구성 파일에는 이 속성만 포함할 수 있습니다. 다른 속성은 선택사항입니다.

Spanner는 DDL 트랜잭션을 지원하지 않으므로 url 문자열에 options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction이 포함되어야 합니다. 이렇게 하면 DDL 트랜잭션이 자동으로 DDL 배치로 변환됩니다. 자세한 내용은 PGAdapter의 DDL 옵션을 참조하세요.

Liquibase 샘플 검토

GoogleSQL

GoogleSQL Liquibase 확장 프로그램에 포함된 샘플 변경 로그 파일 changelog.yaml은 Liquibase의 많은 기능과 Spanner에 이를 사용하는 방법을 보여줍니다.

PostgreSQL

PGAdapter 및 Liquibase GitHub 저장소에서 제공되는 샘플 변경 로그 파일 dbchangelog.xml은 Liquibase의 많은 기능과 Spanner에 이를 사용하는 방법을 보여줍니다.

Liquibase 빠른 시작

이 빠른 시작에서는 Liquibase를 사용하여 Singers 테이블을 데이터베이스에 추가하는 방법을 보여줍니다.

시작하기 전에

Liquibase 설치를 위한 이전 단계가 완료되었는지 확인합니다.
Spanner 인스턴스 만듭니다.
GoogleSQL 언어 데이터베이스 또는 PostgreSQL 언어 데이터베이스를 만듭니다.
PostgreSQL 언어 데이터베이스에만 해당하는 경우 PGAdapter가 Liquibase 설치와 동일한 머신에서 시작되고 실행 중인지 확인합니다. 자세한 내용은 PGAdapter 시작을 참조하세요.
PostgreSQL 언어 데이터베이스에만 해당하는 경우 create_database_change_log.sql 스크립트를 사용하여 databasechangeloglock 및 databasechangelog 메타데이터 테이블을 만듭니다. Liquibase가 데이터베이스에 자동으로 만드는 테이블을 재정의하려면 이러한 테이블을 만들어야 합니다. 이러면 Spanner에 올바른 PostgreSQL 데이터 유형이 이러한 테이블에 사용되도록 보장합니다.

다음 명령어로 스크립트를 실행할 수 있습니다.
```
psql -h localhost -d DATABASE_NAME -f create_database_change_log.sql
```
다음 gcloud 명령어를 실행하여 API 액세스를 위해 고유한 Spanner 사용자 인증 정보에 대한 임시 사용 권한을 Spanner Liquibase 확장 프로그램에 부여합니다.
```
gcloud auth application-default login
```

changelog.yaml 만들기

다음 YAML을 원하는 편집기에 입력합니다.

databaseChangeLog:
  - preConditions:
     onFail: HALT
     onError: HALT

  - changeSet:
     id: create-singers-table
     author: spanner-examples
     changes:
       - createTable:
          tableName: Singers
          columns:
            -  column:
                name:    SingerId
                type:    BIGINT
                constraints:
                  primaryKey: true
                  primaryKeyName: pk_Singers
            -  column:
                name:    Name
                type:    VARCHAR(255)

이 YAML은 기본 키 SingerId 및 Name이라는 열을 사용해서 가수 이름을 저장하기 위한 Singers라는 테이블을 정의합니다.

PostgreSQL 언어 데이터베이스의 경우 테이블 및 열 이름에 소문자를 모두 사용하는 것이 좋습니다. 자세한 내용은 PostgreSQL 대소문자 구분을 참고하세요.

createTable 변경 세트에는 기본 키 제약조건이 포함되어야 하며 기본 키 제약조건의 이름은 pk_table_name여야 합니다.

변경사항을 changelog.yaml로 저장합니다.

Liquibase 실행

다음 명령어를 실행하여 changelog.yaml의 변경사항 집합을 적용합니다.

liquibase --changeLogFile changelog.yaml update

Liquibase는 liquibase.properties 파일에 정의된 URL을 사용합니다. 이전 명령어에 다음 인수를 추가하여 파일의 값을 재정의할 수 있습니다.

--url URL

변경사항 확인

이전 단계의 업데이트로 인해 Singer 테이블이 데이터베이스에 추가되었습니다. 또한 DATABASECHANGELOG 및 DATABASECHANGELOGLOCK 테이블이 추가(GoogleSQL 언어 데이터베이스) 또는 업데이트(PostgreSQL 언어 데이터베이스)되었습니다.

Google Cloud 콘솔 또는 gcloud CLI를 통해 이러한 테이블이 있는지 확인할 수 있습니다. 예를 들어 SQL 쿼리 SELECT * FROM INFORMATION_SCHEMA.TABLES를 실행하면 데이터베이스에 있는 모든 테이블 목록이 반환됩니다.

gcloud spanner databases execute-sql DATABASE_NAME --instance=INSTANCE \
    --sql='SELECT * FROM INFORMATION_SCHEMA.TABLES'

DATABASECHANGELOG 콘텐츠를 쿼리하여 적용된 변경사항의 레코드를 볼 수 있습니다.

다음 단계

자세한 내용은 Spanner Liquibase 확장 프로그램 GitHub 저장소를 참조하세요.
Liquibase에 대한 자세한 내용은 Liquibase 시작하기를 참조하세요.