database create

注意

此内容描述了 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>

选项

主要选项

`<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 PAT 令牌，或通过使用 --github-auth-stdin 选项的标准输入提供。

`--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 将尝试从检出路径自动检测；若无法检测，则默认使用 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: 简单地确保遵守磁盘缓存的已定义大小限制，必要时删除尽可能多的中间结果。

overlay: 修剪至仅保留在针对覆盖层评估时有用的数据。

跟踪选项

`--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 以提取器名称开头，则对应的提取器必须声明该 option group1.group2.option_name。否则，声明了该 option 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。

谁可以使用此功能？

本文内容