liquibase-jpa-test/README.md

모든 설명들은 [docopt 표기법](http://docopt.org/) 을 사용하였습니다.
- <CONSTANTS>: 상수
- (set|remove): 상호 배타 요소
- [<OPTIONAL_ARGUMENTS>]: 선택적 요소

## 작업 순서

### feature 브랜치 생성

- gitflow 방식에 의해 develop 브랜치로부터 feature 브랜치 생성
- feature 브랜치 명명 규칙: `feature/(postgres | assign-redshift | device-redshift)-v<MAJOR_VERSION_NUMBER>[-<MINOR_VERSION_NUMBER>]`
  - `v` 는 소문자
  - changelog 버젼 충동을 방지하기 위함
  - 명명 규칙에 의거하여 리모트 레파지토리에 먼저 올린 브랜치가 버젼 선점에 대한 우선권을 갖습니다.

### [DDL(Data Definition Language) 체인지 로그 파일 gernerate] 

-JPA 엔티티 변경 후 XXXX 태스크 사용
  - 자신이 작업한 내용만 남기고 다른 내용은 제거
- generate 된 파일의 버젼 번호와 작업이름을 수정
- DB 변경을 수동으로 작업한 이후 generateChangelog 태스크를 사용
  - 자신이 작업한 내용만 남기고 다른 내용은 제거
  - generate 된 파일의 버젼 번호와 작업이름을 수정

### changelog 파일 생성하거나 generate 된 파일 변경

- 위치: `src/main/resources/(postgres | assign-redshift | device-redshift)/changelog`
- 파일 형식: `v<MAJOR_VERSION_NUMBER>[.<MINOR_VERSION_NUMBER>]__(ddl | dml)__<NAME>.yaml`
  - `v` 는 소문자
  - `_` 가 2개임
  - <MAJOR_VERSION_NUMBER>: 작업의 첫번째 경우에 develop 에 push 된 이전 메이져 버젼에서 증분하여 사용
  - <MINOR_VERSION_NUMBER>: 이전 작업에서 추가되는 경우 마이너 버젼을 붙여 사용
  - ddl: (create | alter | drop) (table | column) 한 경우 선택
  - dml: insert, update, delete, truncate 등 데이터 수정시 선택 
  - <NAME>: lower-kebab-case 형태로 작업을 간략하게 표현

### feature 브랜치 commit & push

- commit log 는 반드시 일감 번호로 시작해야 합니다.

### merge develop

- 코드리뷰를 통해 develop 에 병합되어야 합니다.
- develop 에 병합된 소스는 매일 자정에 devdb 초기화 이후 자동반영됩니다.
- 그러므로 코드리뷰를 통하지 않은 SQL 오류와 테스트/개발 환경의 오류는 작업자 본인의 책임입니다.

### apm-stage 에 반영

```shell
./gradlew update --db (postgres | assign-redshift | device-redshift) --profile apm-dev
```

### 운영 반영

1. release/hotfix 브랜치 생성
1. 반영
    ```shell
    ./gradlew update --db (postgres | assign-redshift | device-redshift) --profile (skb-prod | uplus-prod | flower-prod)
    ```
1. changelog 파일에 태그 달기(운영 작업 후 필수)
    * major version: 테이블을 추가하거나 삭제한 경우 major version 을 올린다.
    * minor version: alter 의 경우에는 minor version 을 올린다.

---

이 밑쪽은 아직 다듬기 전 내용들 (예전 내용들임)

1. database.yaml 을 참고하여 각 프로파일별로 변경내용 적용
    * generateChangelog 를 통하여 체인지로그 파일을 생성하였고 변경내용을 적용하려는 프로파일이 수동으로 작업한 곳이라면 changelogSync 태스크 수행 (update 태스크 필요 없음)
    1. updateSQL 태스크로 DB 에 실제로 적용되는 SQL 문을 확인
    1. update 태스크로 체인지로그의 변경내용을 실제로 적용

## Commands
liquibase task 이름의 작명규칙이 있다. 아래의 규칙을 미리 알면 사용이 더욱 쉽다.
* 뒤가 ChangeLog 로 끝나면 결과는 changeLog 파일로 생성된다.
    * diffChangeLog
    * generateChangelog
* SQL 로 끝나면 sql 문을 아웃풋으로 뿌려준다.
    * changelogSyncSQL
    * updateSQL
    * rollbackSQL
    * 이하 생략
* SQL 로 끝나는 task 를 SQL 을 빼고 실행하면 아웃풋으로 뿌려주던 SQL 문의 내용이 실행되어 DB 에 반영된다. 그러므로 실제 반영 전 SQL 을 붙여 반영될 작업의 결과를 확인하고 반영하는 것이 좋을 듯하다.

### generateChangelog
DB의 모든 테이블 스키마를 읽어와 liquibase 에서 제공하는 DSL 이나 sql 로 변환한다. gradle.properties 의 generateChangeLogFile 에 설정한 이름대로 저장된다.
```bash
./gradlew generateChangelog -Dprofile=mysql-dev
```

### changelogSyncSQL
changelogSync 태스크를 실행할 때 실제 수행될 SQL 문을 출력한다.
```bash
./gradlew changelogSyncSQL -Dprofile=mysql-local
```

### changelogSync
DATABASECHANGELOG 테이블을 갱신한다. 데이터베이스를 수동으로 업데이트 한 경우에 유용하다.
```bash
./gradlew changelogSync -Dprofile=mysql-local
```

### updateSQL
DB 의 적용될 사항을 sql 로 보여준다.
```bash
./gradlew updateSQL -Dprofile=mysql-local
```

### update
실제 변경을 적용할 경우 사용하는 명령. 데이터는 삭제되지 않으나 컬럼 추가/변경/삭제 등을 할 경우 change-logs 에 마이그레이션을 위한 update 문이 포함되어야 할 수도 있다.
```bash
./gradlew update -Dprofile=mysql-local
```

### diff
profile 과 referenceProfile DB 의 차이점을 보여준다.
새로운 변경사항이 적용된 referenceProfile 을 이전 버젼의 profile 과 비교하여 스키마의 차이점을 찾는다.
```bash
./gradlew diff -Dprofile=mysql-dev -DreferenceProfile=mysql-local
```

### diffChangeLog
profile 과 referenceProfile DB 의 차이점을 찾아 ChangeLog 로 만들어준다. gradle.properties 의 diffChangeLogFile 에 설정한 이름대로 저장된다.
diffChangeLog 의 정확도가 조금 약하다. 그러므로, diffChangeLogFile 에서 실제로 수정된 것만 추려내는 작업이 필요할 수도 있다.
새로운 변경사항이 적용된 referenceProfile 을 이전 버젼의 profile 과 비교하여 스키마의 차이점을 찾는다.
```bash
./gradlew diffChangeLog -Dprofile=mysql-dev -DreferenceProfile=mysql-local
```

### rollbackSQL
태그를 지정하여 롤백 시 수행될 쿼리를 볼 수 있다.
```bash
./gradlew rollbackSQL -Dprofile=mysql-local -PliquibaseCommandValue=V1.0 
```

### rollback
태그를 지정하여 롤백 가능하다.
```bash
./gradlew rollback -Dprofile=mysql-local -PliquibaseCommandValue=V1.0 
```

### clearCheckSums
수정시 파일이 바뀌어 체크섬을 다시 계산해야 되는 경우 위 명령을 실행하고 update 나 changelogSync 등을 실행
```bash
./gradlew clearCheckSums -Dprofile=mysql-local
```

### dbDoc
javadoc 스타일로 현재 DB 적용 상태를 문서로 만들어준다.
```bash
./gradlew dbDoc -Dprofile=mysql-local
```

### tasks
모든 tasks 를 볼려면
```bash
./gradlew tasks
```