데이터베이스 실행 쿼리

참고 항목

이 콘텐츠는 CodeQL CLI의 최신 릴리스에 대해 설명합니다. 이 요소에 대한 자세한 내용은 https://github.com/github/codeql-cli-binaries/releases을(를) 참조하세요.

이전 릴리스에서 이 명령에 사용할 수 있는 옵션의 세부 정보를 보려면 터미널에서 옵션을 사용하여 --help 명령을 실행합니다.

개요

Shell

codeql database run-queries [--threads=<num>] [--ram=<MB>] <options>... -- <database> <query|dir|suite|pack>...

codeql database run-queries [--threads=<num>] [--ram=<MB>] <options>... -- <database> <query|dir|suite|pack>...

Description

          \[내부 처리] 쿼리들의 집합을 함께 실행합니다.

CodeQL 데이터베이스에 대해 하나 이상의 쿼리를 실행하여, 그 결과를 데이터베이스 디렉터리의 결과 하위 디렉터리에 저장합니다.

결과는 이후에 codeql database interpret-results를 통해 읽을 수 있는 형식으로 변환되거나, codeql bqrs decode 또는 codeql bqrs interpret를 사용하여 쿼리에 대한 쿼리를 할 수 있습니다.

쿼리들이 소스 코드 경고로 해석할 수 있는 형식으로 결과를 생성하는 경우, codeql database analyze를 실행할 더욱 편리한 방법을 찾을 수도 있습니다. codeql database analyze는 codeql database run-queries 및 codeql database interpret-results를 한 단계로 결합합니다. 특히, codeql database analyze는 SARIF 형식의 출력을 생성하며, 이 형식은 다양한 경고 뷰어와 함께 사용할 수 있습니다.

또는 실행할 쿼리가 하나뿐인 경우, 디버깅하는 중에 결과를 빠르게 검사하기 위해 사람이 읽을 수 있는 출력을 표시할 수 있는 codeql query run이 더 선호될 수 있습니다.

Options

기본 옵션

`<database>`

          \[필수] 쿼리할 CodeQL 데이터베이스 경로입니다.

`<query|dir|suite|pack>...`

실행할 쿼리입니다. 각 인수는 scope/name@range:path 형식으로, 다음과 같습니다.

          `scope/name`은(는) CodeQL 팩의 정규화된 이름입니다.

          `range`은(는) semver 범위입니다.

          `path`은(는) 파일 시스템 경로입니다.

scope/name을(를) 지정하면 range 및 path은(는) 옵션입니다. range이(가) 누락된 경우 이는 지정된 팩의 최신 버전입니다. path이(가) 누락된 경우 이는 지정된 팩의 기본 쿼리 도구 모음입니다.

path은(는) 하나 이상의 쿼리를 포함하는 디렉터리, *.ql 쿼리 파일, .qls 쿼리 도구 모음 파일 중 하나일 수 있습니다. 팩 이름이 지정되지 않은 경우 path을(를) 제공해야 합니다. 이는 현재 프로세스의 현재 작업 디렉터리를 기준으로 해석됩니다.

리터럴 @ 또는 :을(를) 포함하는 path을(를) 지정하려면 path:을(를) path:directory/with:and@/chars과(와) 같이 인수의 접두사로 사용합니다.

scope/name 및 path이(가) 지정된 경우 path은(는) 절댓값이 될 수 없습니다. 이는 CodeQL 팩의 루트에 대해 상대적인 것으로 간주됩니다.

쿼리가 지정되지 않았다면, CLI는 실행하기에 적절한 쿼리 집합을 자동으로 결정할 것입니다. 특히 데이터베이스 생성 시에 --codescanning-config를 사용하여 코드 검사 구성 파일을 지정한 경우, 이 파일의 쿼리가 사용될 것입니다. 그렇지 않으면, 분석 중인 언어에 대한 기본 쿼리가 사용될 것입니다.

`--no-rerun`

BQRS 결과가 출력 위치에 이미 저장되어 있는 것으로 보이는 쿼리는 평가에서 누락됩니다.

`--no-database-extension-packs`

          \[고급] 코드 검사 구성 파일이나 분석된 코드베이스의 '확장' 디렉터리에 저장된 확장 파일에서, 데이터베이스 생성 시 저장된 확장 팩을 누락시킵니다.

`--no-database-threat-models`

          \[고급] 데이터베이스 생성 중에 데이터베이스에 저장된 위협 모델 구성을 코드 검사 구성 파일에서 누락시킵니다.

사용할 모델 팩을 제어하기 위한 옵션

          `--model-packs=<`
          <name@range>>...

평가할 쿼리를 사용자 지정하기 위해 모델 팩으로 사용할 CodeQL 팩 이름 목록입니다(각 이름에 선택적 버전 범위를 포함합니다).

사용할 위협 모델을 제어하기 위한 옵션

`--threat-model=<name>...`

활성화 또는 비활성화할 위협 모델의 목록입니다.

인수는 위협 모델의 이름으로서, 선택적으로 앞에 '!'가 붙습니다. 만약 '!'가 없으면, 이름이 부여된 위협 모델 및 그 하위 항목이 모두 활성화됩니다. '!'가 있으면, 이름이 부여된 위협 모델 및 그 하위 항목이 모두 비활성화됩니다.

'기본' 위협 모델은 활성화되는 것이 기본값이지만 '--threat-model !default'를 지정하는 방법으로 비활성화할 수 있습니다.

'전체' 위협 모델을 이용하여 모든 위협 모델들을 활성화 또는 비활성화할 수 있습니다.

--threat-model 옵션은 순서대로 처리됩니다. 예를 들어 '--threat-model local --threat-model !environment'는 '로컬' 그룹에서 '환경' 위협 모델을 제외한 전체 위협 모델을 활성화합니다.

이 옵션은 위협 모델을 지원하는 언어에만 효과가 있습니다.

v2.15.3부터 사용할 수 있습니다.

쿼리 평가기를 제어하는 옵션

`--[no-]tuple-counting`

          \[고급] 쿼리 평가기 로그에 각 평가 단계별 튜플 수를 표시합니다. `--evaluator-log` 옵션이 제공되면 튜플 수는 명령으로 생성된 텍스트 기반 로그와 구조화된 JSON 로그 모두에 포함됩니다. (복잡한 QL 코드의 성능 최적화에 도움이 될 수 있습니다.)

`--timeout=<seconds>`

          \[고급] 쿼리 평가에 대한 시간 제한(초)을 설정합니다.

시간 제한 기능은 복잡한 쿼리의 평가가 "영구적으로" 실행되는 경우를 방지하기 위해 개발되었습니다. 쿼리 평가에 소요되는 총 시간을 제한하기 위한 목적으로는 효과적이지 않습니다. 별도로 시간이 측정된 각 계산 부분이 시간 제한 내에 완료되면 평가가 진행될 수 있습니다. 현재 별도로 시간이 측정된 부분은 최적화된 쿼리의 "RA 계층"이지만 차후에 변경될 수 있습니다.

시간 제한이 지정되지 않거나 0으로 지정된 경우 시간 제한이 설정되지 않습니다. 단, codeql test run의 경우 기본 시간 제한은 5분입니다.

`-j, --threads=<num>`

해당 스레드 수를 사용하여 쿼리를 평가합니다.

기본값은 1입니다. 0을 전달하여 머신의 코어당 한 개의 스레드를 사용할 수 있고, -_N_을 전달하여 _N_개의 코어를 사용하지 않은 상태로 둘 수 있습니다. 단, 최소 한 개의 스레드는 계속 사용됩니다.

`--[no-]save-cache`

          \[사용되지 않음] \[고급] 이 플래그는 아무 작업도 수행하지 않습니다.

`--[no-]expect-discarded-cache`

          \[고급] 쿼리가 실행된 후 캐시가 삭제될 것을 전제로 하여, 평가할 조건자와 디스크 캐시에 작성할 내용을 결정합니다.

`--[no-]keep-full-cache`

          \[고급] 평가 완료 후 디스크 캐시를 정리하지 않아야 합니다.

차후에 codeql dataset cleanup 또는 codeql database cleanup을 수행할 경우 이를 통해 시간이 절약됩니다.

`--max-disk-cache=<MB>`

디스크 캐시가 중간 쿼리 결과에 사용할 수 있는 최대 공간을 설정합니다.

명시적으로 이 크기가 구성되지 않으면 데이터 세트의 크기와 쿼리의 복잡성에 따라 평가기가 "합리적인" 양의 캐시 공간을 사용하려고 합니다. 명시적으로 이 기본 사용량보다 높은 한도를 설정하게 되면 추가 캐싱이 가능하므로 이후의 쿼리의 속도를 높일 수 있습니다.

`--min-disk-free=<MB>`

          \[고급] 파일 시스템에 확보할 목표 여유 공간의 양을 설정합니다.

--max-disk-cache이(가) 지정되지 않으면 파일 시스템의 사용 가능한 공간이 이 값 이하로 떨어질 때 평가기에서 디스크 캐시 사용량을 줄이려고 합니다.

`--min-disk-free-pct=<pct>`

          \[고급] 파일 시스템에 확보할 목표 여유 공간의 비율을 설정합니다.

--max-disk-cache이(가) 지정되지 않으면 파일 시스템의 사용 가능한 공간이 이 비율 이하로 떨어질 때 평가기에서 디스크 캐시 사용량을 줄이려고 합니다.

`--external=<pred>=<file.csv>`

외부 조건자 <pred> 의 행이 포함된 CSV 파일입니다. 여러 개의 --external 옵션이 제공될 수 있습니다.

`--xterm-progress=<mode>`

          \[고급] xterm 제어 시퀀스를 사용하여 QL 평가 중에 진행률 추적을 표시할지 여부를 제어합니다. 가능한 값은 다음과 같습니다.

          `no`: 복잡한 진행률을 생성하지 않아야 합니다. 바보 터미널이라고 가정합니다.

          `auto`              _(기본값)_: 명령이 적절한 터미널에서 실행 중인지 여부를 자동 검색합니다.

          `yes`: 터미널이 xterm 제어 시퀀스를 인식할 수 있다고 가정합니다. 이 기능은 계속해서 터미널 _크기_의 자동 검색 여부에 따라 달라집니다(Windows에서는 구현되지 않음). 또한 `-q`이(가) 지정되면 이 기능은 비활성화됩니다.

          `25x80` (또는 이와 유사): `yes`과(와) 같으며 터미널 크기를 명시적으로 지정합니다. (`yes`과(와) 다르게 이 기능은 Windows에서 작동합니다.)

          `25x80:/dev/pts/17` (또는 이와 유사): stderr가 아닌 _다른_ 터미널에서 복잡한 진행률을 표시합니다. 내부 테스트에 주로 사용됩니다.

구조화된 평가기 로그의 출력을 제어하는 옵션

`--evaluator-log=<file>`

          \[고급] 지정된 파일에 평가기 성능에 대한 구조화된 로그를 출력합니다. 이 로그 파일의 형식은 예고 없이 변경될 수 있으나, 기본적으로 두 개의 줄 바꿈 문자로 구분된 JSON 개체 스트림입니다. `--evaluator-log-minify` 옵션이 전달된 경우에는 한 개의 줄 바꿈 문자로 구분됩니다. `codeql generate log-summary <file>`을(를) 사용하여 이 파일에 대한 보다 안정적인 요약을 생성하고, 파일을 직접 구문 분석하지 않아야 합니다. 파일이 이미 있으면 덮어쓰기됩니다.

`--evaluator-log-minify`

          \[고급] `--evaluator-log` 옵션이 전달되면 생성되는 JSON 로그의 크기가 최소화되지만 가독성이 크게 저하됩니다.

RAM 사용량을 제어하는 옵션

`-M, --ram=<MB>`

총 메모리 사용량이 이 값을 초과하지 않도록 유지하기 위해 쿼리 평가기가 최대한 노력합니다. (그러나 데이터베이스가 큰 경우 메모리가 부족하면 디스크로 교환할 수 있는 파일 기반 메모리 맵으로 임계값을 초과할 가능성이 있습니다.)

값은 최소 2048MB 이상이어야 하며, 그 이하의 값은 투명하게 반올림됩니다.

QL 컴파일을 제어하기 위한 옵션

`--warnings=<mode>`

QL 컴파일러에서 발생한 경고를 해결하는 방식입니다. 다음 중 하나입니다.

          `hide`: 경고 표시 안 함.

          `show`              _(기본값)_: 경고를 인쇄하지만 계속해서 컴파일을 진행합니다.

          `error`: 경고를 오류로 처리합니다.

`--no-debug-info`

디버깅용 RA에서 원본 위치 정보를 내보내지 않습니다.

`--[no-]fast-compilation`

          \[사용되지 않음] \[고급] 특히 시간이 오래 걸리는 최적화 단계를 생략합니다.

`--no-release-compatibility`

          \[고급] 이식성의 저하를 감수하면서 최신 컴파일러 기능을 사용합니다.

경우에 따라 새로운 QL 언어 기능 및 평가기 최적화는 QL 컴파일러에서 기본 적용되기 전에, 여러 릴리스에 걸쳐 QL 평가기에서 먼저 지원될 예정입니다. 이렇게 하면 최신 CodeQL 릴리스에서 쿼리를 개발할 때 경험하는 성능이 코드 검사 또는 CI 통합에 여전히 사용 중인 이전 버전의 릴리스에서도 동일하게 유지됩니다.

쿼리가 다른(이전 또는 이후) CodeQL 릴리스와의 호환성을 고려할 필요가 없는 경우 이 플래그를 사용하여 컴파일러의 최근 개선 사항을 조기에 활성화하고 약간의 성능 향상을 누릴 수 있습니다.

적용 가능한 최신 개선 사항이 없는 릴리스에서는 이 옵션이 실행되더라도 아무런 효과가 없습니다. 그러므로 전역 CodeQL 구성 파일에서 한 번만 설정해도 안전합니다.

v2.11.1부터 사용할 수 있습니다.

`--[no-]local-checking`

초기 검사는 사용되는 QL 원본 부분에서만 수행합니다.

`--no-metadata-verification`

QLDoc 주석에 포함된 쿼리 메타데이터에 대해 유효성 검사를 수행하지 않습니다.

`--compilation-cache-size=<MB>`

          \[고급] 컴파일 캐시 디렉터리에 설정된 기본 최대 크기 제한을 변경합니다.

`--fail-on-ambiguous-relation-name`

          \[고급] 모호한 관계 이름이 컴파일 중에 생성되는 경우 컴파일에 실패합니다.

컴파일 환경 설정 옵션

`--search-path=<dir>[:<dir>...]`

QL 팩이 위치할 수 있는 디렉터리 목록입니다. 각 디렉터리는 QL 팩(또는 루트에 .codeqlmanifest.json 파일이 포함된 팩 번들)일 수도 있고, 하나 이상의 이러한 디렉터리의 직계 부모일 수 있습니다.

하나 이상의 디렉터리가 경로에 포함된 경우 해당 순서가 우선순위를 정의합니다. 확인해야 하는 팩 이름이 여러 디렉터리 트리에서 일치하는 경우 먼저 지정된 트리가 우선합니다.

이를 오픈 소스 CodeQL 리포지토리의 체크 아웃 위치로 지정하면, 해당 리포지토리에 있는 언어 중 하나를 쿼리할 때 정상적으로 동작합니다.

CodeQL 리포지토리를 압축을 푼 CodeQL 툴체인의 형제로 체크 아웃한 경우에는 이 옵션을 지정할 필요가 없습니다. 다른 방법으로는 찾을 수 없는 QL 팩으로 이러한 형제 디렉터리가 항상 검색됩니다. (해당 기본값이 작동하지 않는 경우 --search-path은(는) 사용자별 구성 파일에서 한 번만 설정하는 것을 권장합니다).

(참고: Windows에서는 경로 구분 기호로 ;을(를) 사용합니다.)

`--additional-packs=<dir>[:<dir>...]`

해당 디렉터리 목록이 지정된 경우 팩이 --search-path에 있는 디렉터리보다 먼저 검색됩니다. 그 사이의 순서는 중요하지 않습니다. 서로 다른 두 위치에서 팩 이름을 이 목록을 통해 찾을 경우에는 오류가 발생합니다.

기본 경로에도 표시되는 팩의 새 버전을 일시적으로 개발하는 경우 이 기능이 유용합니다. 반면에 이 옵션을 구성 파일에서 재정의하는 것은 권장하지 않습니다. 일부 내부 작업에서는 즉시 이 옵션을 추가하여 구성된 값을 재정의합니다.

(참고: Windows에서는 경로 구분 기호로 ;을(를) 사용합니다.)

`--library-path=<dir>[:<dir>...]`

          \[고급] QL 라이브러리의 원시 가져오기 검색 경로에 추가되는 디렉터리의 선택적 목록입니다. QL 팩으로 패키지되지 않은 QL 라이브러리를 사용 중인 경우에 한해 사용 가능합니다.

(참고: Windows에서는 경로 구분 기호로 ;을(를) 사용합니다.)

`--dbscheme=<file>`

          \[고급] 쿼리가 어떤 dbscheme에 대해 컴파일되어야 하는지 명시적으로 정의합니다. 작업 내용을 완전히 파악하고 있는 호출자에 한해서만 사용되어야 합니다.

`--compilation-cache=<dir>`

          \[고급] 컴파일 캐시로 사용하기 위한 추가 디렉터리를 지정합니다.

`--no-default-compilation-cache`

          \[고급] 표준 위치(예: 쿼리를 포함하는 QL 팩 또는 CodeQL 툴체인 디렉터리)에서 컴파일 캐시를 사용하지 마세요.

CodeQL 패키지 관리자 구성 옵션

`--registries-auth-stdin`

GitHub Enterprise Server 컨테이너 레지스트리에 인증하기 위해 <registry_url>=<token> 쌍을 쉼표로 구분한 목록을 전달합니다.

예를 들어, https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2을(를) 전달하여 두 개의 GitHub Enterprise Server 인스턴스에 인증할 수 있습니다.

이는 CODEQL_REGISTRIES_AUTH 및 GITHUB_TOKEN 환경 변수를 재정의합니다. github.com 컨테이너 레지스트리 인증만 필요한 경우 --github-auth-stdin 옵션을 사용하여 간편하게 인증할 수 있습니다.

`--github-auth-stdin`

GitHub Apps 토큰 또는 개인용 액세스 토큰을 github.com에 전달하여 표준 입력을 통해 github.com 컨테이너 레지스트리에 인증합니다.

--registries-auth-stdin을(를) 전달하거나 CODEQL_REGISTRIES_AUTH 환경 변수를 사용하여 GitHub Enterprise Server 컨테이너 레지스트리에 인증할 수 있습니다.

이는 GITHUB_TOKEN 환경 변수를 재정의합니다.

          \[고급] 명령을 실행하는 JVM에 옵션을 제공합니다.

(옵션에 공백이 포함되면 제대로 처리되지 않을 수 있는 점에 유의해야 합니다.)

          \[고급] 세부 정보 표시 수준을 명시적으로 오류, 경고, 진행률, 진행률+, 진행률++, 진행률+++ 중 하나로 설정합니다. 
          `-v` 및 `-q`를 재정의합니다.

`--logdir=<dir>`

          \[고급] 지정한 디렉터리에 상세 로그를 하나 이상의 파일로 작성하며, 생성된 이름에는 타임스탬프와 실행 중인 하위 명령 이름을 포함합니다.

(로그 파일 이름을 직접 작성하려면 대신 --log-to-stderr을(를) 지정하고 stderr를 원하는 위치로 리디렉션합니다.)

`--common-caches=<dir>`

          \[고급] 다운로드한 QL 팩 및 컴파일된 쿼리 계획 등 CLI를 여러 번 실행해도 지속되는 디스크의 캐시된 데이터의 위치를 제어합니다. 명시적으로 설정하지 않으면, 기본적으로 사용자의 홈 디렉터리에 이름이 지정된 `.codeql` 디렉터리로 설정됩니다. 디렉터리가 아직 없는 경우에는 만들어집니다.

v2.15.2부터 사용할 수 있습니다.

데이터베이스 실행 쿼리

누가 이 기능을 사용할 수 있나요?

이 문서의 내용