数据库创建

此内容描述了 CodeQL CLI 的最新版本。有关此版本的更多信息，请参阅 https://github.com/github/codeql-cli-binaries/releases。

要查看早期版本中此命令可用的选项的详细信息，请在您的终端中使用 --help 选项运行该命令。

摘要

Shell

codeql database create [--language=<lang>[,<lang>...]] [--github-auth-stdin] [--github-url=<url>] [--source-root=<dir>] [--threads=<num>] [--ram=<MB>] [--command=<command>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database>

codeql database create [--language=<lang>[,<lang>...]] [--github-auth-stdin] [--github-url=<url>] [--source-root=<dir>] [--threads=<num>] [--ram=<MB>] [--command=<command>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database>

描述

为可以使用其中一个 CodeQL 产品进行分析的源代码树创建 CodeQL 数据库。

选项

主要选项

`<database>`

[必填] 要创建的 CodeQL 数据库的路径。将创建此目录，并且不得已存在（但其父目录必须存在）。

如果给出了--db-cluster选项，则这本身将不是数据库，而是一个将包含从相同源根构建的几种语言的数据库的目录。

重要的是，此目录不在构建过程将干扰的位置。例如，Maven 项目的target目录不是合适的选择。

`--[no-]overwrite`

[高级] 如果数据库已存在，则删除它并继续执行此命令，而不是失败。如果目录存在，但它看起来不像数据库，则会抛出错误。

`--[no-]force-overwrite`

[高级] 如果数据库已存在，则即使它看起来不像数据库，也将其删除并继续执行此命令，而不是失败。此选项应谨慎使用，因为它可能会递归删除整个数据库目录。

`--codescanning-config=<file>`

[高级] 读取一个 Code Scanning 配置文件，该文件指定有关如何创建 CodeQL 数据库以及在后续步骤中运行哪些查询的选项。有关此配置文件格式的更多详细信息，请参阅自定义代码扫描的高级设置。要在后续步骤中从此文件运行查询，请调用 codeql database analyze 而不指定任何其他查询。

`--[no-]db-cluster`

不是创建单个数据库，而是为不同的语言创建一个数据库“集群”，每个数据库都是命令行上给定目录的子目录。

`-l, --language=<lang>[,<lang>...]`

新数据库将用于分析的语言。

使用 codeql resolve languages 获取搜索路径上找到的可插拔语言提取器的列表。

当给出--db-cluster选项时，这可以多次出现，或者值可以是语言的逗号分隔列表。

如果省略此选项，并且正在分析的源根是 GitHub 存储库的检出，则 CodeQL CLI 将调用 GitHub API 以尝试自动确定要分析的语言。请注意，要能够执行此操作，必须在环境变量 GITHUB_TOKEN 中或通过使用--github-auth-stdin选项通过标准输入提供 GitHub PAT 令牌。

`--build-mode=<mode>`

将用于创建数据库的构建模式。

根据您正在分析的语言选择构建模式

none：将在不构建源根的情况下创建数据库。适用于 C#、Java、JavaScript/TypeScript、Python 和 Ruby。

autobuild：将通过尝试自动构建源根来创建数据库。适用于 C/C++、C#、Go、Java/Kotlin 和 Swift。

manual：通过使用手动指定的构建命令构建源代码根目录来创建数据库。适用于 C/C++、C#、Go、Java/Kotlin 和 Swift。

使用--command创建数据库时，无需另外指定 '--build-mode manual'。

自 v2.16.4 版本起可用。

`-s, --source-root=<dir>`

[默认值：.] 源代码根目录。在许多情况下，这将是检出根目录。其中的文件被视为该数据库的主要源文件。在某些输出格式中，将根据这些文件相对于此目录的路径来引用这些文件。

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

为导入操作使用这么多个线程，并将其作为提示传递给任何调用的构建命令。

默认为 1。您可以传递 0 以在机器上每个核心使用一个线程，或 -N 以保留 N 个核心未使用（但仍至少使用一个线程）。

`-c, --command=<command>`

对于编译语言，构建命令将导致编译器在源代码上调用以进行分析。这些命令将在允许分析生成的代码和（在某些情况下）标准库的检测环境下执行。

如果未指定构建命令，则该命令会尝试根据所选语言包的启发式方法自动找出如何构建源代码树。

请注意，某些多种语言的组合需要指定显式构建命令。

`--[no-]skip-empty`

[高级] 如果数据库为空（因为在构建期间没有看到任何源代码），则输出警告而不是失败。空数据库将保持未完成状态。

`--[no-]linkage-aware-import`

[高级] 控制 codeql dataset import 是否为链接感知型（默认）或非链接感知型。在数据库创建的这一部分消耗过多内存的项目中，禁用此选项可能会帮助它们继续进行，但代价是降低数据库的完整性。

自 v2.15.3 版本起可用。

基线计算选项

`--[no-]calculate-baseline`

[高级] 计算有关正在分析的代码的基线信息并将其添加到数据库中。默认情况下，除非源代码根目录是文件系统的根目录，否则会启用此功能。此标志可用于禁用或强制启用此行为，即使在文件系统的根目录中也是如此。

`--[no-]sublanguage-file-coverage`

[仅限 GitHub.com 和 GitHub Enterprise Server v3.12.0 及更高版本] 使用子语言文件覆盖信息。这将计算、显示和导出共享 CodeQL 提取器（如 C 和 C++、Java 和 Kotlin 以及 JavaScript 和 TypeScript）的语言的单独文件覆盖信息。

自 v2.15.2 版本起可用。

提取器选择选项

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

可在其下找到提取器包的目录列表。这些目录可以是提取器包本身，也可以是包含提取器作为直接子目录的目录。

如果路径包含多个目录树，则它们的顺序定义了它们之间的优先级：如果在多个目录树中匹配目标语言，则首先给出的目录树优先。

CodeQL 工具链本身捆绑的提取器将始终被找到，但如果您需要使用单独分发的提取器，则需要提供此选项（或者，最好在每个用户的配置文件中设置--search-path）。

（注意：在 Windows 上，路径分隔符为;）。

配置如何调用 GitHub API 以自动检测语言的选项。

`-a, --github-auth-stdin`

通过标准输入接受 GitHub 应用令牌或个人访问令牌。

这将覆盖 GITHUB_TOKEN 环境变量。

`-g, --github-url=<url>`

要使用的 GitHub 实例的 URL。如果省略，CLI 将尝试从检出路径自动检测此 URL，如果无法检测，则默认为 https://github.com/

配置包管理器的选项。

`--registries-auth-stdin`

通过传递以逗号分隔的 <registry_url>=<token> 对列表来对 GitHub Enterprise Server 容器注册表进行身份验证。

例如，您可以传递 https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2 以对两个 GitHub Enterprise Server 实例进行身份验证。

这将覆盖 CODEQL_REGISTRIES_AUTH 和 GITHUB_TOKEN 环境变量。如果您只需要对 github.com 容器注册表进行身份验证，则可以使用更简单的--github-auth-stdin选项进行身份验证。

低级数据集清理选项

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

设置磁盘缓存（用于中间查询结果）可以使用空间的最大量。

如果未显式配置此大小，则评估器将尝试使用基于数据集大小和查询复杂度的“合理”缓存空间量。显式设置高于此默认用法的限制将启用其他缓存，这可以加快以后的查询速度。

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

[高级] 设置文件系统上的目标可用空间量。

如果未给出--max-disk-cache，则如果文件系统上的可用空间低于此值，则评估器将尽力减少磁盘缓存的使用。

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

[高级] 设置文件系统上可用空间的目标百分比。

如果未给出--max-disk-cache，则如果文件系统上的可用空间低于此百分比，则评估器将尽力减少磁盘缓存的使用。

`--cache-cleanup=<mode>`

选择修剪缓存的力度。选项包括

clear：删除整个缓存，修剪到新提取的数据集的状态

trim （默认）：修剪除显式“缓存”谓词之外的所有内容。

fit：只需确保遵守磁盘缓存的已定义大小限制，删除尽可能多的中间文件。

跟踪选项

`--extra-tracing-config=<tracing-config.lua>`

[高级] 跟踪器配置文件的路径。它可用于修改构建跟踪器的行为。它可用于选取作为构建命令一部分运行的编译器进程，并触发其他工具的执行。提取器将提供在大多数情况下都适用的默认跟踪器配置文件。

构建命令自定义选项

`--working-dir=<dir>`

[高级] 应在其中执行指定命令的目录。如果未提供此参数，则命令将在传递给 codeql database create 的--source-root的值中执行（如果存在）。如果未提供--source-root参数，则命令将在当前工作目录中执行。

`--no-run-unnecessary-builds`

[高级] 仅当正在构建的数据库使用依赖于跟踪构建过程的提取器时，才运行指定的构建命令。如果未给出此选项，则即使 CodeQL 不需要该命令，也会执行该命令，假设您出于其他原因需要其副作用。

设置 CodeQL 提取器的选项。extractor-option-name应采用 extractor_name.group1.group2.option_name 或 group1.group2.option_name 的形式。如果extractor_option_name以提取器名称开头，则指示的提取器必须声明选项 group1.group2.option_name。否则，任何声明选项 group1.group2.option_name 的提取器都将设置该选项。value可以是任何不包含换行符的字符串。

您可以重复使用此命令行选项来设置多个提取器选项。如果您为同一个提取器选项提供了多个值，则行为取决于提取器选项期望的类型。字符串选项将使用提供的最后一个值。数组选项将按顺序使用提供的全部值。使用此命令行选项指定的提取器选项在通过--extractor-options-file给出的提取器选项之后处理。

当传递给 codeql database init 或codeql database begin-tracing时，这些选项将仅应用于间接跟踪环境。如果您的工作流也对 codeql database trace-command 进行调用，则如果需要，也需要在其中传递这些选项。

有关 CodeQL 提取器选项的更多信息，包括如何列出每个提取器声明的选项，请参阅 https://codeql.github.com/docs/codeql-cli/extractor-options。

`--extractor-options-file=<extractor-options-bundle-file>`

指定提取器选项捆绑文件。提取器选项捆绑文件是 JSON 文件（扩展名为.json）或 YAML 文件（扩展名为.yaml或.yml），用于设置提取器选项。该文件必须具有顶级映射键“extractor”，并在其下以提取器名称作为二级映射键。更深层的映射表示嵌套的提取器组，字符串和数组选项是具有字符串和数组值的映射条目。

提取器选项捆绑文件按指定的顺序读取。如果不同的提取器选项捆绑文件指定了相同的提取器选项，则行为取决于提取器选项期望的类型。字符串选项将使用提供的最后一个值。数组选项将按顺序使用提供的全部值。使用此命令行选项指定的提取器选项在通过--extractor-option给出的提取器选项之前处理。

有关 CodeQL 提取器选项的更多信息，包括如何列出每个提取器声明的选项，请参阅 https://codeql.github.com/docs/codeql-cli/extractor-options。

谁可以使用此功能？

本文档内容