7. 제한값과 설정

DataAPI는 SQL 실행, 인증, 커넥션 풀, JDBC 접속, SQL 로깅 등을 제어하기 위한 다양한 환경변수를 제공한다.

이 장에서는 주요 환경변수의 기본값과 동작 방식을 설명한다.

7.1 SQL 제한값

환경변수	기본값	설명
DATA_API_SQL_QUERY_TIMEOUT_SECONDS	30	buffered 조회 query timeout
DATA_API_SQL_UTRANS_TIMEOUT_SECONDS	30	/execute 변경 트랜잭션 제한에 사용할 Altibase utrans timeout
DATA_API_SQL_MAX_ROWS	5000	buffered 조회 최대 row 수
DATA_API_BUFFERED_BLOB_INLINE_LIMIT_BYTES	1048576	buffered BLOB inline 최대 크기
DATA_API_BUFFERED_CLOB_INLINE_LIMIT_CHARS	1048576	buffered CLOB inline 최대 크기
DATA_API_STREAM_QUERY_TIMEOUT_SECONDS	300	stream query timeout
DATA_API_MAX_STREAM_DURATION_MILLIS	600000	stream 최대 지속 시간

버퍼링 기반 조회 시 BLOB/CLOB 컬럼의 데이터 크기가 설정된 inline 제한을 초과하면 DATA_007 오류가 발생한다. 따라서 대용량 LOB 데이터를 빈번히 다루는 클라이언트라면 buffered 조회보다는 스트리밍 계열 엔드포인트 사용을 권장한다.

7.2 인증과 role 설정

환경변수	기본값	설명
JWT_SECRET	필수	HS256 서명 키
JWT_ACCESS_EXPIRATION	1800000	Access 토큰 만료 시간(ms)
JWT_REFRESH_EXPIRATION	3600000	Refresh 토큰 만료 시간(ms)
JWT_EXPIRATION	fallback only	Access/Refresh 개별 설정이 없을 때 공용 fallback
DATA_API_ACCESS_ROLE	DATA_API_ACCESS	SQL 엔드포인트 접근 role
DATA_API_MONITORING_ROLE	DATA_API_MONITORING	모니터링 엔드포인트 접근 role

7.3 커넥션 풀 설정

환경변수	기본값	설명
DATA_API_POOL_MAX_ACTIVE_USERS	100	인증 방식별로 캐시에 보관할 최대 사용자 풀의 개수
DATA_API_POOL_EVICT_GRACE_TIMEOUT_MILLIS	10000	비동기 풀 close 작업에서 active borrow 해제를 기다리는 최대 시간(ms)
DATA_API_POOL_EVICT_WAIT_INTERVAL_MILLIS	100	비동기 풀 close 작업에서 active borrow 해제 여부를 다시 확인하는 주기(ms)
DATA_API_JWT_POOL_MAX_SIZE	5	JWT 사용자별 Hikari 풀이 동시에 열 수 있는 최대 DB 커넥션 수
DATA_API_JWT_POOL_MIN_IDLE	0	JWT 사용자별 Hikari 풀 안에 유지할 최소 유휴 DB 커넥션 수
DATA_API_JWT_POOL_IDLE_TIMEOUT_MILLIS	600000	JWT 사용자별 Hikari 풀 안의 유휴 DB 커넥션 정리 기준(ms)
DATA_API_JWT_POOL_EXPIRE_AFTER_ACCESS_MILLIS	3600000	JWT 사용자 풀 자체의 캐시 만료 기준(ms)
DATA_API_BASIC_POOL_MAX_SIZE	1	Basic 사용자별 Hikari 풀이 동시에 열 수 있는 최대 DB 커넥션 수
DATA_API_BASIC_POOL_MIN_IDLE	0	Basic 사용자별 Hikari 풀 안에 유지할 최소 유휴 DB 커넥션 수
DATA_API_BASIC_POOL_IDLE_TIMEOUT_MILLIS	180000	Basic 사용자별 Hikari 풀 안의 유휴 DB 커넥션 정리 기준(ms)
DATA_API_BASIC_POOL_EXPIRE_AFTER_ACCESS_MILLIS	900000	Basic 사용자 풀 자체의 캐시 만료 기준(ms)

DATA_API_JWT_POOL_IDLE_TIMEOUT_MILLIS와 DATA_API_BASIC_POOL_IDLE_TIMEOUT_MILLIS는 커넥션 풀 자체를 제거하는 설정이 아니다. 이 값은 커넥션 풀 안에서 유휴(IDLE) DB 커넥션을 정리하는 기준 시간을 지정한다. 커넥션 풀 자체의 제거 시점은 DATA_API_JWT_POOL_EXPIRE_AFTER_ACCESS_MILLIS, DATA_API_BASIC_POOL_EXPIRE_AFTER_ACCESS_MILLIS로 제어한다.

로그아웃, 세션 초기화 또는 캐시 만료가 발생하면 커넥션 풀은 즉시 제거되지 않고 draining 상태로 전환된다. Draining 상태에서는 새로운 요청은 받지 않고, 진행 중인 작업만 완료한 후 순차적으로 정리된다.

Warning

DATA_API_BASIC_POOL_EXPIRE_AFTER_ACCESS_MILLIS를 스트림 최대 지속 시간보다 짧게 설정하면 장시간 실행되는 Basic 인증 스트림이 중간에 종료될 수 있다.

7.4 JDBC 설정

환경변수	기본값	설명
DATA_API_DB_LOGIN_TIMEOUT_SECONDS	30	Altibase JDBC 접속 단계 login timeout
DATA_API_JDBC_STMT_CACHE_MODE	off	JDBC statement cache URL 주입 모드. off, on 중 하나
DATA_API_JDBC_STMT_CACHE_SIZE	25	JDBC connection별 statement cache 최대 보관 개수
DATA_API_JDBC_STMT_CACHE_SQL_LIMIT	1024	캐시 대상 SQL 문자열 최대 길이

DATA_API_DB_LOGIN_TIMEOUT_SECONDS는 DB 접속 시 JDBC URL의 login_timeout 파라미터로 적용된다. 이 값은 JWT 로그인 검증과 Basic/JWT 커넥션 풀 생성 시 동일하게 적용된다.

DATA_API_JDBC_STMT_CACHE_MODE의 기본값은 off이며, 이 경우 DataAPI는 JDBC 접속 URL에 stmt_cache_enable 파라미터를 추가하지 않는다.

DATA_API_JDBC_STMT_CACHE_MODE를 on으로 설정하면, stmt_cache_enable 속성을 지원하는 Altibase JDBC 8.x 드라이버에서는 Statement Cache 관련 매개변수가 JDBC 접속 URL에 자동으로 추가된다.

반면, Altibase JDBC 7.x처럼 stmt_cache_enable 속성을 지원하지 않는 드라이버에서는 이 설정을 on으로 지정하더라도 관련 매개변수는 추가되지 않는다.

7.5 SQL 로깅

기본 INFO 로그에서는 SQL 원문을 출력하지 않는다. 장애 분석이나 유지보수 중 실행 SQL을 확인해야 하면 SqlExecutor 로거를 DEBUG로 올린다.

java -jar data-api-<version>-altibase8.jar \
  --logging.level.com.altibase.dataapi.component.SqlExecutor=DEBUG

패키지 전체를 올릴 때는 환경변수 LOGGING_LEVEL_COM_ALTIBASE_DATAAPI=DEBUG를 사용할 수 있다. 출력되는 event=sql.execute 로그는 SQL 미리보기, 실행 모드, 타임아웃 정보, 그리고 바인딩된 매개변수 개수(argCount) 또는 배치 행 수(batchRows) 등을 포함한다.

보안상 args에 바인딩된 실제 매개변수 값은 로그에 남지 않는다. 그러나 클라이언트에서 변수 바인딩 대신 SQL 쿼리 문자열에 값을 직접 결합하여 전달한 경우에는 해당 리터럴 값이 SQL 미리보기에 그대로 노출될 수 있으므로 주의해야 한다.

따라서 실제 운영 환경에서는 일시적인 진단 목적으로만 DEBUG 레벨을 활성화하고, 민감 정보 노출 방지를 위해 외부 입력값은 가능한 한 ? 자리표시자와 args 배열을 사용하여 바인딩 처리할 것을 권장한다. 한편, 로그에 출력되는 쿼리 미리보기의 최대 길이는 2,048자로 제한되며 이를 초과하는 부분은 생략된다.