выполнение запросов базы данных

В этом материале описывается последний выпуск Интерфейса командной строки CodeQL. Дополнительные сведения об этом выпуске см. в разделе 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, сохраняя результаты в подкаталоге результатов каталога базы данных.

Позже результаты можно преобразовать в доступные для чтения форматы с помощью codeql database interpret-results или query-for-query с помощью декодирования codeql bqrs или codeql bqrs interpret.

Если ваши запросы дают результаты в форме, которую можно интерпретировать как оповещения исходного кода, вы можете найти анализ базы данных codeql более удобным способом их выполнения. Анализ базы данных codeql объединяет run-queries базы данных codeql с результатами интерпретации базы данных codeql в одном шаге. В частности, анализ базы данных codeql может выдавать выходные данные в формате SARIF, который можно использовать с различными средствами просмотра оповещений.

Кроме того, если у вас есть только один запрос для выполнения, вы можете предпочесть выполнение запроса codeql, который может отображать удобочитаемые выходные данные для быстрой проверки результатов во время отладки.

Основные параметры

`<database>`

[Обязательно] Путь к базе данных CodeQL для запроса.

`<querysuite|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-]tuple-counting`

[Дополнительно] Отображение количества кортежей для каждого шага оценки в журналах средства оценки запросов. --evaluator-log Если указан параметр, счетчик кортежей будет включаться в текстовые и структурированные журналы JSON, созданные командой . (Это может быть полезно для оптимизации производительности сложного кода QL.)

`--timeout=<seconds>`

[Дополнительно] Задайте время ожидания для оценки запроса в секундах.

Функция времени ожидания предназначена для перехвата случаев, когда для оценки сложного запроса потребуется "навсегда". Это не эффективный способ ограничить общее время, которое может занять вычисление запроса. Оценка будет продолжена до тех пор, пока каждая отдельная часть вычисления по времени завершается в течение времени ожидания. В настоящее время эти отдельные части по времени являются уровнями RA оптимизированного запроса, но в будущем они могут измениться.

Если время ожидания не указано или задано как 0, время ожидания не будет задано (за исключением тестового выполнения codeql, где время ожидания по умолчанию составляет 5 минут).

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

Используйте это множество потоков для оценки запросов.

По умолчанию равен 1. Вы можете передать 0, чтобы использовать один поток на каждое ядро на компьютере, или -N , чтобы оставить N ядер неиспользуемых (за исключением использования по крайней мере одного потока).

`--[no-]save-cache`

[Дополнительно] Агрессивно записывайте промежуточные результаты в кэш диска. Это занимает больше времени и занимает (гораздо) больше места на диске, но может ускорить последующее выполнение аналогичных запросов.

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

[Дополнительно] Принимать решения о том, какие предикаты следует оценивать и что записывать в кэш диска, исходя из предположения, что кэш будет удален после выполнения запросов.

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

[Дополнительно] Не очищайте кэш диска после завершения оценки. Это может сэкономить время, если вы собираетесь выполнить очистку набора данных codeql или очистку базы данных codeql .

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

Задайте максимальный объем пространства, который кэш диска может использовать для промежуточных результатов запроса.

Если этот размер не настроен явно, средство оценки попытается использовать "разумный" объем кэша в зависимости от размера набора данных и сложности запросов. Явное задание более высокого ограничения, чем это использование по умолчанию, позволит включить дополнительное кэширование, что может ускорить последующие запросы.

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

[Дополнительно] Задайте целевой объем свободного места в файловой системе.

Если --max-disk-cache значение не задано, средство оценки будет стараться сократить использование кэша диска, если свободное место в файловой системе падает ниже этого значения.

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

[Дополнительно] Задайте целевую долю свободного места в файловой системе.

Если --max-disk-cache значение не задано, средство оценки будет стараться ограничить использование кэша диска, если свободное место в файловой системе падает ниже этого процента.

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

CSV-файл, содержащий строки для внешнего предиката \. Можно указать несколько --external вариантов.

`--xterm-progress=<mode>`

[Дополнительно] Определяет, следует ли отображать отслеживание хода выполнения во время оценки QL с помощью последовательностей элементов управления xterm. Возможны следующие значения:

no: никогда не создавать причудливый прогресс; предположим, что глупый терминал.

auto(по умолчанию): автоматически определяет, выполняется ли команда в соответствующем терминале.

yes: предполагается, что терминал может понимать последовательности элементов управления xterm. Эта функция по-прежнему зависит от возможности автоматически определить размер терминала, а также будет отключена, если -q она задана.

25x80 (или аналогично): нравится yes, а также явно укажите размер терминала.

25x80:/dev/pts/17 (или аналогично): отображение необычного хода выполнения в терминале, отличном от stderr. В основном полезно для внутреннего тестирования.

Параметры управления выходными данными структурированных журналов средства оценки

`--evaluator-log=<file>`

[Дополнительно] Вывод структурированных журналов о производительности средства оценки в указанный файл. Формат этого файла журнала может быть изменен без уведомления, но будет потоком объектов JSON, разделенных двумя символами новой строки (по умолчанию) или одним, если --evaluator-log-minify параметр передан. Используйте для codeql generate log-summary <file> создания более стабильной сводки по этому файлу и избегайте непосредственного анализа файла. Файл будет перезаписан, если он уже существует.

`--evaluator-log-minify`

[Дополнительно] Если --evaluator-log параметр передается, также передача этого параметра позволит свести к минимуму размер создаваемого журнала JSON за счет того, что сделать его гораздо менее удобочитаемым.

Параметры управления использованием ОЗУ

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

Задайте общий объем ОЗУ, который должен использовать средство оценки запросов.

Параметры управления компиляцией 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>`

[Дополнительно] Переопределите максимальный размер по умолчанию для каталога кэша компиляции.

Параметры настройки среды компиляции

`--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>=\ разделенный запятыми.

Например, можно передать https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2 для проверки подлинности в двух экземплярах GitHub Enterprise Server.

Это переопределяет переменные среды AUTH CODEQL_REGISTRIES_и токена GITHUB_. Если вам нужно пройти проверку подлинности только в реестре контейнеров github.com, можно использовать более --github-auth-stdin простой вариант.

`--github-auth-stdin`

Проверка подлинности в реестре контейнеров github.com путем передачи маркера github.com GitHub Apps или личного маркера доступа через стандартные входные данные.

Для проверки подлинности в реестрах контейнеров GitHub Enterprise Server передайте --registries-auth-stdin или используйте переменную среды CODEQL_REGISTRIES_AUTH.

Это переопределяет переменную среды GITHUB_TOKEN.

выполнение запросов базы данных

В этой статье