dbquery

외부 데이터베이스 서버를 대상으로 JDBC를 통해 SQL 질의를 수행합니다. 데이터베이스 유형의 접속 프로파일이 미리 구성되어 있어야 합니다.

명령어 속성

문법

대상

PROFILE

사용할 데이터베이스 유형 접속 프로파일의 식별자. 접속 프로파일은 웹 콘솔에서 구성할 수 있습니다.

SQL

실행할 SQL 문. SELECT, SHOW, EXECUTE, EXEC 문은 결과 집합을 레코드로 변환하여 출력하고, INSERT, UPDATE, DELETE 등 기타 SQL 문은 실행만 수행합니다.

SQL 문에 콜론(:)으로 시작하는 플레이스홀더를 사용할 수 있습니다. 플레이스홀더는 set 명령어로 설정한 쿼리 매개변수 값으로 대체됩니다. 플레이스홀더 이름은 콜론 뒤에 영문자나 밑줄(_)로 시작해 영문자·숫자·밑줄로 이루어진 두 글자 이상이어야 하며, 설정하지 않은 매개변수는 null로 대체됩니다. PostgreSQL의 ::int처럼 콜론 두 개로 쓰는 형 변환 표기도 플레이스홀더로 인식되어 대체되므로 주의하세요.

• 숫자 타입: 값 그대로 삽입
• 날짜 타입: 'yyyy-MM-dd HH:mm:ss' 또는 'yyyy-MM-dd HH:mm:ss.SSS' 형식의 문자열로 변환
• null: null 문자열로 삽입
• 기타 타입: 작은따옴표로 감싼 문자열로 변환

출력 필드

오류 코드

파싱 오류

런타임 오류

설명

dbquery 명령어는 JDBC를 통해 외부 데이터베이스에 SQL 질의를 실행하고, 결과 집합의 각 행을 레코드로 변환하여 출력합니다.

SELECT, SHOW, EXECUTE, EXEC로 시작하는 SQL 문은 결과 집합을 조회합니다. 그 외의 SQL 문(INSERT, UPDATE, DELETE, DDL 등)은 실행만 수행하며 레코드를 출력하지 않습니다. WITH 절로 시작하는 조회문도 이 규칙에 따라 실행만 수행하므로 레코드를 출력하지 않으며, 데이터베이스에 따라 오류가 발생할 수 있습니다.

SQL 문은 트랜잭션 안에서 실행합니다. 실행을 마치면 커밋하고, 실행에 실패하면 롤백한 뒤 쿼리를 오류로 중단합니다. 이때 오류 메시지에는 플레이스홀더를 대체하기 전의 SQL 문이 표시됩니다. 다만 접속 문자열이 jdbc:hive2://로 시작하는 아파치 하이브 데이터베이스에서는 자동 커밋 설정을 바꾸지 않고 커밋과 롤백도 하지 않습니다.

SQL 문에 콜론으로 시작하는 플레이스홀더(예: :name)를 사용하면, set 명령어로 설정한 쿼리 매개변수 값으로 대체됩니다. 이를 통해 동적으로 SQL 질의를 구성할 수 있습니다.

MySQL 또는 MariaDB에 연결할 때는 대용량 결과 집합을 처리하기 위해 전방 전용 커서와 스트리밍 페치를 사용합니다. 그 외 데이터베이스에서는 결과 집합을 한 번에 2,000건씩 가져옵니다. 이 값은 JVM 시스템 속성 logpresso.jdbc.fetch_size로 변경할 수 있습니다.

쿼리를 실행하는 계정에 지정한 접속 프로파일의 사용 권한이 있어야 합니다. 클러스터 관리자 역할과 관리자 역할 계정은 공유 설정과 관계없이 접속 프로파일을 사용할 수 있고, 그 밖의 계정은 접속 프로파일의 계정 공유·그룹 공유 설정으로 사용 권한을 받습니다.

식별자가 정확히 sonar인 접속 프로파일은 시스템 내부용 프로파일이므로 사용이 차단됩니다. 예약 쿼리 등 시스템이 내부적으로 dbquery를 실행하는 경우에는 이 제한이 적용되지 않습니다. 점검, 장애 대응 등 운영 목적으로 일시적으로 허용해야 하면 부팅 스위치 logpresso.sonar.allow_system_profile을 true로 설정합니다(기본값: 미설정, 차단).

사용 예

1. 외부 데이터베이스에서 데이터 조회

   dbquery mydb SELECT * FROM employees WHERE department = 'sales'
   

   식별자가 mydb인 접속 프로파일로 연결한 데이터베이스에서 employees 테이블의 sales 부서 레코드를 조회합니다.

2. 플레이스홀더를 사용한 동적 질의

   set start_date = string(dateadd(now(), "day", -7), "yyyy-MM-dd")
   | dbquery mydb SELECT * FROM access_logs WHERE log_date >= :start_date
   

   set 명령어로 설정한 start_date 매개변수를 SQL 질의에 삽입하여 최근 7일간의 로그를 조회합니다.

3. 조회 결과를 가공하여 정렬

   dbquery mydb SELECT src_ip, dst_ip, bytes FROM traffic_logs
   | stats sum(bytes) as total_bytes by src_ip
   | sort -total_bytes
   

   외부 데이터베이스에서 트래픽 로그를 조회한 후, 출발지 IP별 전송량 합계를 계산하여 내림차순으로 정렬합니다.

변경 이력