쓰리래빗츠 북 3.0.35 버전부터 지원합니다.

쓰리래빗츠 북으로 데이터베이스 테이블 정의서를 작성하는 방법을 설명합니다.

JDBC API로 데이터베이스에 연결해서 테이블 정보를 가져옵니다. 이 문서를 이해하려면 JDBC API에 맞게 어떤 정보를 입력해야 하는지를 이해하고 있어야 합니다.

데이터베이스 연결 만들기

데이터베이스 연결 설정

다음 순서로 JDBC API를 이용해서 데이터베이스 연결을 설정합니다.

<도구 | 외부 시스템> 메뉴로 이동합니다.

관리 권한이 있는 사용자만 접근할 수 있습니다.

<1DB 만들기> 링크를 클릭합니다.

내용을 입력한 후 저장합니다.

데이터베이스 연결 정보
내용	설명	필수 여부
시스템 아이디	내용을 업데이트할 때 사용하는 임의의 구분자로 고유해야 합니다. 만든 후에 변경할 수 없습니다.	예
이름	구분을 위해 임의로 부여하는 데이터베이스 이름입니다. 실제 데이터베이스 이름과는 상관이 없습니다.	예
JDBC URL	JDBC URL입니다. 오라클이면서 SID를 사용하면 jdbc:oracle:thin:@127.0.0.1:1521:SID, SERVICE_NAME을 사용하면 jdbc:oracle:thin:@127.0.0.1:1521:SERVICE_NAME과 같습니다.	예
JDBC 사용자 아이디	JDBC 사용자 아이디. 사용자 아이디와 비밀번호 방식 연결만을 지원합니다.	JDBC 속성에서 `user`로 설정할 수 있습니다.
JDBC 사용자 비밀번호	JDBC 사용자 비밀번호	JDBC 속성에서 `password`로 설정할 수 있습니다.
JDBC 속성	기타 JDBC 속성을 입력합니다. 속성 이름과 속성 값을 '=' 구분자로 구분합니다. `remarksReporting=true` 줄 바꿈으로 여러 속성을 입력할 수 있습니다.

JDBC 드라이버 라이브러리 복사

JDBC 드라이버 라이브러리를 3RABBIZ_HOME/tomcat/lib 디렉터리에 복사합니다.
쓰리래빗츠 북을 재시작합니다.

데이터베이스 관리자 또는 개발자에게 JDBC 드라이버를 요청합니다.

데이터베이스 연결 테스트

쓰리래빗츠 북을 재시작한 후 <2테스트> 링크를 클릭합니다.

JDBC 연결에 성공하면 테이블 목록이 보입니다.

테이블 목록을 제한하려면 테이블 이름 필터하기를 참고합니다.

DB 속성

데이터베이스 연결이 가능해지면 데이터베이스 속성 표가 나타납니다. 데이터베이스 이름과 버전 등을 확인할 수 있습니다.

접근 권한 설정

다음 순서로 특정 데이터베이스에 접근할 수 있는 사용자 또는 그룹을 설정합니다.

<1접근 권한 변경> 링크를 클릭합니다.
그룹 또는 사용자를 선택한 후 <저장> 버튼을 클릭합니다.
- 글 쓰기 권한이 있는 사용자만 목록에 나타납니다.

데이터베이스 연결 삭제

데이터베이스 연결을 삭제하려면 <1삭제> 링크를 클릭합니다.

삭제한 것과 같은 시스템 아이디로 데이터베이스 연결을 만들면 이전에 가져오기 한 테이블을 다시 동기화할 수 있습니다.

테이블 정의서 만들기

먼저 문서를 만듭니다. 문서를 만드는 자세한 방법은 쓰리래빗츠 북 사용자 가이드를 참고합니다.

<대시보드> 메뉴에서 <책 만들기>를 선택합니다.
내용을 입력한 후 저장합니다.
차례 패널에서 <장 만들기> 링크를 클릭합니다.
내용을 입력한 후 저장합니다.
장의 <내용 편집> 링크를 클릭해서 에디터를 엽니다.

테이블을 가져오는 방법입니다.

에디터 오른쪽 위에 있는 <1외부 시스템> 버튼을 클릭합니다.
2데이터베이스 연결 이름을 선택합니다. 연결을 설정하지 않았거나 접근 권한이 없다면 <DB: 쓰리래빗츠>만이 보입니다(쓰리래빗츠 북 테이블 정보 제공).
- 접근 권한을 설정하는 방법은 접근 권한 설정을 참고합니다.
테이블 정의서를 만들 테이블을 선택한 후 <3가져오기> 버튼을 클릭합니다.

선택한 단락이 있다면 선택한 단락 아래에, 없다면 맨 아래에 테이블 이름(제목 1)과 테이블 정의서 표를 추가합니다.

표에 시스템 아이디와 테이블 이름 라벨이 붙습니다. 테이블 정의서를 업데이트할 때 사용합니다.

테이블 가져오기와 관련해서 다음을 참고합니다.

쓰리래빗츠 북 에디터의 다른 기능을 모두 사용할 수 있습니다. 예를 들어 다른 단락으로 자세한 설명을 추가할 수 있습니다.
내용을 편집하면서 표의 셀을 합치거나 분리하면 업데이트할 수 없습니다.
표의 열은 필요에 따라 정의할 수 있습니다. 설정 방법은 칼럼 속성 설정 정의를 참고합니다.
표의 행으로 테이블 칼럼을 표시합니다. 일반적으로 칼럼이 만들어진 순서를 따르며 ORDINAL_POSITION 값으로 정렬합니다.
웹 뷰어 차례를 위해 제목 1 유형으로 테이블 이름을 추가합니다. 자세한 사항은 테이블 제목 단락 유형 설정을 참고합니다.

테이블 정의서 업데이트

SQL의 ALTER TABLE 등의 명령어로 테이블을 변경했다면 그 내용을 쓰리래빗츠 북으로 만든 테이블 정의서에도 반영할 수 있습니다.

에디터를 엽니다.
에디터 오른쪽 위에 있는 <1외부 시스템> 버튼을 클릭합니다.
<2외부 시스템 단락 업데이트> 버튼을 클릭합니다.

업데이트와 관련해서 다음을 참고합니다.

이력 비교로 변경 내역을 확인할 수 있습니다.
접근 권한이 없는 데이터베이스의 테이블은 업데이트하지 않습니다.
더 이상 존재하지 않는 테이블에 해당하는 표 단락을 자동으로 삭제하지 않습니다. 직접 해당 단락을 삭제 합니다.
테이블 이름은 바꿀 수 없기에 제목 단락은 없데이트 대상이 아닙니다.
셀을 합치거나 나눈 표는 업데이트하지 않습니다.
JDBC 표준 칼럼 속성 값을 쓰리래빗츠 북에서 수정했다면 JDBC가 제공하는 값으로 다시 바뀝니다. 따라서 JDBC 표준 칼럼 속성 값은 변경하지 않습니다.
테이블에는 존재하는 칼럼을 쓰리래빗츠 북에서만 삭제했다면 다시 나타납니다.
사용자 정의 칼럼 속성은 쓰리래빗츠 북에서 바뀐 내용을 유지합니다.

칼럼 속성 설정 정의

JSON으로 칼럼 정의하기

테이블 정의서에서 칼럼의 어떤 속성을 보여줄 것인가를 JSON으로 설정합니다.

<도구 | 웹 페이지> 메뉴를 선택합니다.
<1JSON | ES_TABLE> 메뉴를 선택합니다.
설정한 후 저장합니다.

별도로 설정하지 않으면 기본 설정을 따릅니다. 기본 설정은 다음과 같습니다.

{
    "columns": [
        {
            "key": "COLUMN_NAME",
            "name": {
              "en": "Name",
              "ko": "이름"
            }
        },
        {
            "key": "TYPE_NAME",
            "name": {
              "en": "Type",
              "ko": "유형"
            }
        },
        {
            "key": "COLUMN_SIZE",
            "name": {
              "en": "Size",
              "ko": "크기"
            },
            "align": "right"
        },
        {
            "key": "COLUMN_DEF",
            "name": {
              "en": "Default",
              "ko": "기본값"
            }
        },
        {
            "key": "IS_NULLABLE",
            "name": {
              "en": "Nullable",
              "ko": "NULL 허용"
            }
        },
        {
            "key": "@ALL",
            "name": {
              "en": "Constraint & Index",
              "ko": "제약 조건과 인덱스"
            }
        },
        {
            "key": "#DESCRIPTION",
            "name": {
              "en": "Description",
              "ko": "설명"
            },
            "code": false
        }
    ],
    "option": {
      "tableLayout": "20%,10%,10%,10%,10%,20%,20%"
    }
}

`key` 속성

첫 번째로 JDBC API가 제공하는 표준 칼럼 속성을 키로 사용합니다.

키	유형	설명
TABLE_CAT	문자열	테이블 카탈로그
TABLE_SCHEM	문자열	테이블 스키마
TABLE_NAME	문자열	테이블 이름
COLUMN_NAME	문자열	칼럼 이름
DATA_TYPE	숫자	`java.sql.Types`의 SQL 데이터 형식.
TYPE_NAME	문자열	데이터 형식의 이름
COLUMN_SIZE	숫자	칼럼의 자릿수
BUFFER_LENGTH	숫자	데이터의 전송 크기
DECIMAL_DIGITS	숫자	칼럼의 소수 자릿수
NUM_PREC_RADIX	숫자	칼럼의 기수
NULLABLE	숫자	칼럼이 null을 허용하는지 여부. 0이면 null을 허용하지 않고, 1이면 null을 허용합니다.
REMARKS	문자열	칼럼과 관련된 설명
COLUMN_DEF	문자열	칼럼 기본 값
SQL_DATA_TYPE	숫자
SQL_DATETIME_SUB	숫자
CHAR_OCTET_LENGTH	숫자	열의 최대 바이트 수
ORDINAL_POSITION	숫자	테이블 내의 열 인덱스
IS_NULLABLE	문자열	열에 null 값을 사용할 수 있는지 여부
SCOPE_CATALOG	문자열	참조하는 칼럼의 카탈로그. 참조하지 않는다면 null을 반환합니다.
SCOPE_SCHEMA	문자열	참조하는 칼럼의 스키마. 참조하지 않는다면 null을 반환합니다.
SCOPE_TABLE	문자열	참조하는 칼럼의 테이블. 참조하지 않는다면 null을 반환합니다.
SOURCE_DATA_TYPE	숫자
IS_AUTOINCREMENT	문자열	값을 자동으로 증가하는지 여부. YES 또는 NO를 반환합니다. 판단할 수 없으면 빈 값을 반환합니다.
IS_GENERATEDCOLUMN	문자열	값을 자동으로 계산하는지 여부. YES 또는 NO를 반환합니다. 판단할 수 없으면 빈 값을 반환합니다.

이 표는 JDBC API 문서를 기준으로 합니다. 데이터베이스와 JDBC 드라이버에 따라 별도의 키를 지원할 수도 있습니다.

칼럼 유형을 표시할 때 DATA_TYPE은 코드 값을 반환하기에 TYPE_NAME을 사용합니다.

{
    "key": "TYPE_NAME",
    "name": "유형"
}

두 번째로 업데이트할 때 쓰리래빗츠 북에서 편집한 내용을 유지할 수 있는 키가 있습니다. 칼럼 속성의 key가 #으로 시작하는 임의의 값을 사용합니다.

{
    "key": "#DESCRIPTION",
    "name": "설명"
}

세 번째로 기본 키(Primary Key), 외래 키(Foreign Key), 인덱스 등의 정보를 제공하는 키가 있습니다. 칼럼 속성의 key가 @으로 시작합니다.

@PK: 기본 키 정보를 보여줍니다.
@FK: 외래 키 정보를 보여줍니다.
@INDEX: 인덱스 정보를 보여줍니다.
@ALL: 기본 키, 외래 키, 인덱스 정보를 모두 보여줍니다. 표 너비 제한 때문에 기본 키, 외래 키, 인덱스를 따로 보여주기 어려울 때 사용합니다.

`name` 속성

name 속성으로 칼럼 속성 이름을 설정합니다. 없으면 key 속성을 이름으로 사용합니다.

{
    "key": "COLUMN_NAME",
    "name": "이름"
}

다양한 언어를 지원해야 한다면 다음과 같이 설정합니다. name 속성 값을 JSON 객체로 설정하고 각 언어를 키로 이름을 설정합니다.

{
    "key": "COLUMN_NAME",
    "name": {
        "ko": "이름",
        "en_US": "Name",
        "ja": "名前",
        "zh_CN": "名称"
    }
}

문서 언어에 따라 이름을 결정합니다.

`align` 속성

align 속성으로 좌우 정렬 방법을 설정합니다. left, right, center 등을 지원합니다. 기본 값은 left입니다.

{
    "key": "COLUMN_SIZE",
    "align": "right"
}

부록

테이블 유형 제한하기

다음 순서로 테이블 목록에 특정 테이블 유형만이 보이도록 설정합니다.

<외부 시스템 변경> 링크를 클릭합니다.
JDBC 속성에 jdbc_table_types 값을 추가하고 저장합니다.
<테스트> 링크를 클릭해서 결과를 확인합니다.

DB 속성에서 데이터베이스가 지원하는 테이블 유형을 확인할 수 있습니다.

여러 유형을 지원하려면 쉼표를 구분자로 입력합니다. 예를 들어 테이블과 뷰만을 표시하려면 다음과 같이 입력합니다.

jdbc_table_types=TABLE,VIEW

테이블 이름 필터하기

다음 순서로 테이블 목록에 특정 이름 패턴의 테이블만 보이도록 설정합니다.

<외부 시스템 변경> 링크를 클릭합니다.
JDBC 속성에 jdbc_table_name_pattern 값을 추가하고 저장합니다.
<테스트> 링크를 클릭해서 결과를 확인합니다.

예를 들어 오라클 데이터베이스에서 이름이 R_로 시작하는 테이블만을 보여주려면 다음과 같이 설정합니다.

jdbc_table_name_pattern=R/_%

SQL에서 %는 글자 수와 상관없이 모든 글자를, _는 아무 글자 하나를 의미합니다. 따라서 R_%로 설정하면 R_이 아닌 R로 시작하는 테이블이 나타납니다. R_%는 R%로 설정한 것과 거의 같습니다(이름이 R인 테이블만 제외).

따라서 _ 글자 앞에 탈출문자(Escape Character)를 붙여야 합니다. SQL에서 탈출문자는 데이터베이스마다 다릅니다. DB 속성에서 확인할 수 있습니다.

오라클의 탈출문자는 /입니다. 그래서 R_로 시작하는 테이블만을 보여주려면 _앞에 /를 붙여 R/_%로 설정합니다.

카탈로그 이름으로 필터하기

다음 순서로 테이블 목록에 특정 카탈로그의 테이블만 보이도록 설정합니다.

<외부 시스템 변경> 링크를 클릭합니다.
JDBC 속성에 jdbc_catalog 값을 추가하고 저장합니다.
<테스트> 링크를 클릭해서 결과를 확인합니다.

기본 값은 java.sql.Connection의 getCatalog 메소드 반환 값입니다.

스키마 이름으로 필터하기

다음 순서로 테이블 목록에 특정 카탈로그의 테이블만 보이도록 설정합니다.

<외부 시스템 변경> 링크를 클릭합니다.
JDBC 속성에 jdbc_schema 값을 추가하고 저장합니다.
<테스트> 링크를 클릭해서 결과를 확인합니다.

기본 값은 java.sql.Connection의 getSchema 메소드 반환 값입니다. 이 값도 없을 때는 java.sql.DatabaseMetaData의 getUserName 메소드 반환 값을 사용합니다.

테이블 제목 단락 유형 설정

다음 순서로 테이블 제목 단락 유형을 설정합니다. 기본 값은 heading1(제목 1)입니다.

<외부 시스템 변경> 링크를 클릭합니다.
JDBC 속성에 jdbc_table_name_type를 설정한 후 저장합니다.

다음 값을 사용할 수 있습니다.

heading1: 제목 1 단락
heading2: 제목 2 단락
heading3: 제목 3 단락
heading4: 제목 4 단락
heading5: 제목 5 단락
headline: 헤드라인 단락
noraml: 보통 단락
none: none으로 설정하면 제목 단락을 만들지 않습니다.

예를 들어 제목 단락을 생략하려면 JDBC 속성에 다음과 같이 입력합니다.

jdbc_table_name_type=none

오라클 `DESC` 값 가져오기

오라클에서 DESC 명령어로 설정한 칼럼 설명은 JDBC API의 REMARKS 칼럼 속성에 대응합니다. 하지만 기본적으로 DESC 값이 있어도 null을 반환합니다. 다음 순서로 이 값이 보이도록 설정합니다.

<외부 시스템 변경> 링크를 클릭합니다.
JDBC 속성에 remarksReporting을 다음과 같이 추가한 후 저장합니다.

remarksReporting=true

칼럼 정의에 REMARKS를 추가해야 합니다. 자세한 사항은 칼럼 속성 설정 정의를 참고합니다.

문서에 따르면 MS SQL Server는 REMARKS 값으로 항상 null을 반환합니다.

커넥션 풀링 미사용

계속 사용하는 기능이 아니기에 불필요한 자원 낭비를 막기 위해 커넥션 풀링을 하지 않습니다. 연결할 때마다 JDBC 커넥션을 새로 만들고 사용이 끝나면 바로 닫습니다.