# 数据库创建 为可以使用一个 CodeQL 产品进行分析的源树创建 CodeQL 数据库。 > \[!NOTE] > 此内容描述了 CodeQL CLI 的最新版本。 有关此版本的详细信息，请参阅 。 > > 若要查看早期版本中此命令可用选项的详细信息，请在终端中使用 `--help` 选项运行命令。 ## 概要 ```shell copy codeql database create [--language=[,...]] [--github-auth-stdin] [--github-url=] [--source-root=] [--threads=] [--ram=] [--command=] [--extractor-option=] ... -- ``` ## Description 为可以使用一个 CodeQL 产品进行分析的源树创建 CodeQL 数据库。 ## 选项 ### 主要选项 #### `` ``` \[必选] 要创建的 CodeQL 数据库的路径。 此目录将被创建，且_不得_已存在（但其父目录必须存在）。 ``` 如果指定了 `--db-cluster` 选项，此目录本身不会是数据库，而是\_包含\_从同一源根构建的多种语言的数据库的目录。 重要的是，此目录不位于生成过程会干扰的位置。 例如，Maven 项目的 `target` 目录不是合适的选择。 #### `--[no-]overwrite` ``` \[高级] 如果数据库已存在，则删除它并继续执行此命令，而非失败。 如果该目录存在，但看起来不是数据库，则会抛出错误。 ``` #### `--[no-]force-overwrite` ``` \[高级] 如果数据库已存在，即使它看起来不是数据库，也删除它并继续执行此命令，而非失败。 应谨慎使用此选项，因为它可能以递归方式删除整个数据库目录。 ``` #### `--codescanning-config=` ``` \[高级] 读取 Code Scanning 配置文件，该文件指定有关如何创建 CodeQL 数据库以及在后续步骤中运行哪些查询的选项。 有关此配置文件格式的更多详细信息，请参阅 [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning)。 要在后续步骤中从此文件运行查询，请在未指定任何其他查询的情况下调用 [codeql database analyze](/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-analyze)。 ``` #### `--[no-]db-cluster` 为不同语言创建数据库“群集”（其中每个数据库都是命令行上给定的目录的子目录），而不是创建单一数据库。 #### `-l, --language=[,...]` 新数据库将用于分析的语言。 使用 [codeql resolve languages](/zh/code-security/reference/code-scanning/codeql/codeql-cli-manual/resolve-languages) 获取搜索路径上发现的可插入语言提取程序的列表。 如果给定了 `--db-cluster` 选项，这可能会多次显示，或者该值可以是以逗号分隔的语言列表。 如果省略此选项，并且要分析的源根目录是 GitHub 存储库的签出，则 CodeQL CLI 将调用 GitHub API 以尝试自动确定要分析的语言。 请注意，要执行此操作，必须在环境变量 GITHUB\_TOKEN 中或通过使用 `--github-auth-stdin` 选项的标准输入来提供 GitHub PAT 令牌。 #### `--build-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=` ``` \[默认：。]源代码根目录。 在许多情况下，这将是签出根目录。 其中的文件被视为此数据库的主要源文件。 在某些输出格式中，文件将由此目录中的相对路径引用。 ``` #### `-j, --threads=` 将这么多线程用于导入操作，并将其作为提示传递给任何调用的生成命令。 默认值为 1。 可以传递 0 以在机器上每个内核使用一个线程，或传递 -*N* 以保留 *N* 个内核不使用（但仍至少使用一个线程）。 #### `-M, --ram=` 将这么多内存用于导入操作，并将其作为提示传递给任何调用的生成命令。 #### `-c, --command=` 对于已编译的语言，生成命令，这些命令将导致对源代码调用编译器进行分析。 这些命令将在允许分析生成的代码和（在某些情况下）标准库的检测环境下执行。 如果未指定生成命令，该命令会尝试根据所选语言包中的启发式方法自动确定如何生成源树。 请注意，多种语言的某些组合\_需要\_指定显式构建命令。 #### `--no-cleanup` ``` \[高级] 完成后抑制所有数据库清理操作。 对调试很有用。 ``` #### `--no-pre-finalize` ``` \[高级] 跳过活动 CodeQL 提取程序指定的任何预完成脚本。 ``` #### `--[no-]skip-empty` ``` \[高级] 如果数据库为空（因为构建期间未检测到源代码），则输出警告而非失败。 空数据库将保持未完成状态。 ``` #### `--[no-]linkage-aware-import` ``` \[高级] 控制 [codeql dataset import](/code-security/reference/code-scanning/codeql/codeql-cli-manual/dataset-import) 是否支持链接 _（默认）_。 对于在数据库创建这一部分占用过多内存的项目，禁用此选项可能有助于其运行，但会牺牲数据库的完整性。 ``` 自 `v2.15.3` 起可用。 ### 基线计算选项 #### `--[no-]calculate-baseline` ``` \[高级] 计算有关待分析代码的基线信息，并将其添加到数据库中。 默认情况下，除非源根目录是文件系统的根目录，否则会启用此选项。 此标志可用于禁用或强制启用行为，即使在文件系统的根目录中也是如此。 ``` #### `--[no-]sublanguage-file-coverage` ``` \[仅 GitHub.com 和 GitHub Enterprise Server v3.12.0+] 使用子语言文件覆盖率信息。 这会为共享 C 和 C++、Java 和 Kotlin，以及 JavaScript 和 TypeScript 等 CodeQL 提取程序包的语言计算、显示和导出单独的文件覆盖信息。 ``` 自 `v2.15.2` 起可用。 ### 提取程序选择选项 #### `--search-path=[:...]` 可在其中找到提取程序包的目录列表。 目录可以是提取程序包本身，也可以是包含提取程序作为直接子目录的目录。 如果路径包含多个目录树，则目录树的顺序定义了各自之间的优先级：如果目标语言在多个目录树中匹配，则给定的第一个目录树优先。 与 CodeQL 工具链本身捆绑的提取程序始终都能找到，但如果需要单独使用分布式提取程序，则需要提供此选项（或者更佳方式是，在每用户配置文件中设置 `--search-path`）。 （注意：在 Windows 上，路径分隔符为 `;`）。 ### 用于配置如何调用 GitHub API 以自动检测语言的选项。 #### `-a, --github-auth-stdin` 通过标准输入接受 GitHub Apps 令牌或个人访问令牌。 这会替代 GITHUB\_TOKEN 环境变量。 #### `-g, --github-url=` 要使用的 GitHub 实例的 URL。 如果省略，CLI 将尝试从签出路径自动检测此项，如果这不可行，则默认为 ### 用于配置包管理器的选项。 #### `--registries-auth-stdin` 通过传递逗号分隔的 \=\ 对列表，向 GitHub Enterprise Server 容器注册表进行身份验证。 例如，可以传递 `https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` 向两个 GitHub Enterprise Server 实例进行身份验证。 这会替代 CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN 环境变量。 如果只需向 github.com 容器注册表进行身份验证，则可以改用更简单的 `--github-auth-stdin` 选项进行身份验证。 ### 低级别数据集清理选项 #### `--max-disk-cache=` 设置磁盘缓存可用于中间查询结果的最大空间量。 如果未显式配置此大小，计算器将根据数据集大小和查询复杂性尝试使用“合理的”缓存空间量。 显式设置高于此默认使用量的限制将启用额外的缓存，从而加快以后的查询速度。 #### `--min-disk-free=` ``` \[高级] 设置文件系统的目标可用空间量。 ``` 如果未提供 `--max-disk-cache`，当文件系统上的可用空间低于此值时，计算器便会努力减少磁盘缓存使用量。 #### `--min-disk-free-pct=` ``` \[高级] 设置文件系统的目标可用空间比例。 ``` 如果未提供 `--max-disk-cache`，当文件系统上的可用空间低于此百分比时，计算器便会努力减少磁盘缓存使用量。 #### `--cache-cleanup=` 选择剪裁缓存的主动程度。 选项包括： ``` `clear`：删除整个缓存，缩减到刚提取数据集的状态 `trim` _（默认）_：修剪除明确“缓存”的谓词之外的所有内容。 `fit`：只需确保遵守磁盘缓存的已定义大小限制，删除必要数量的中间文件。 `overlay`：修剪到仅对覆盖层评估有用的数据。 ``` #### `--cleanup-upgrade-backups` 删除因数据库升级而生成的任何备份目录。 ### 跟踪选项 #### `--no-tracing` ``` \[高级] 不跟踪指定的命令，而是依赖它直接生成所有必要数据。 ``` #### `--extra-tracing-config=` ``` \[高级] 跟踪器配置文件的路径。 这可用于修改生成跟踪器的行为。 它可用于选取作为生成命令的一部分运行的编译器进程，并触发其他工具的执行。 提取程序将提供在大多数情况下应该都能工作的默认跟踪器配置文件。 ``` ### 生成命令自定义选项 #### `--working-dir=` ``` \[高级] 应执行指定命令的目录。 如果未提供此参数，则在传递给 codeql database create 的 `--source-root` 值（若存在）中执行命令。 如果未提供任何 `--source-root` 参数，则会在当前工作目录中执行命令。 ``` #### `--no-run-unnecessary-builds` ``` \[高级] 仅在构建中的数据库使用依赖于跟踪生成过程的提取程序时，才运行指定的生成命令。 ``` 如果未给定此选项，即使 CodeQL 不需要该命令，也会执行该命令，前提是出于其他原因需要其副作用。 ### 用于控制提取程序行为的选项 #### `-O, --extractor-option=` 设置 CodeQL 提取程序的选项。 `extractor-option-name` 应为 \_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](/zh/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-init) 或 `codeql database begin-tracing` 时，选项将仅应用于间接跟踪环境。 如果工作流还调用 [codeql database trace-command](/zh/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-trace-command)，则还需根据需要传递选项。 请参阅 以了解有关 CodeQL 提取程序选项的详细信息，包括如何列出每个提取程序声明的选项。 #### `--extractor-options-file=` 指定提取程序选项捆绑文件。 提取程序选项捆绑文件是设置提取程序选项的 JSON 文件（扩展名为 `.json`）或 YAML 文件（扩展名为 `.yaml` 或 `.yml`）。 该文件必须具有顶级映射键“extractor”，并且其下必须具有作为二级映射键的提取程序名称。 进一步的映射级别表示嵌套的提取程序组，字符串和数组选项是具有字符串和数组值的映射条目。 按指定的顺序读取提取程序选项捆绑文件。 如果不同的提取程序选项捆绑文件指定了相同的提取程序选项，则行为取决于提取程序选项所需的类型。 字符串选项将使用提供的最后一个值。 数组选项将按顺序使用提供的所有值。 使用此命令行选项指定的提取程序选项在通过 `--extractor-option` 给定的提取程序选项之前进行处理。 传递给 [codeql database init](/zh/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-init) 或 `codeql database begin-tracing` 时，选项将仅应用于间接跟踪环境。 如果工作流还调用 [codeql database trace-command](/zh/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-trace-command)，则还需根据需要传递选项。 请参阅 以了解有关 CodeQL 提取程序选项的详细信息，包括如何列出每个提取程序声明的选项。 ### 常用选项 #### `-h, --help` 显示此帮助文本。 #### `-J=` ``` \[高级] 向运行命令的 JVM 提供选项。 ``` （请注意，无法正确处理包含空格的选项。） #### `-v, --verbose` 以增量方式增加输出的进度消息数。 #### `-q, --quiet` 以增量方式减少输出的进度消息数。 #### `--verbosity=` ``` \[高级] 明确将详细级别设置为 errors、warnings、progress、progress+、progress++、progress+++ 之一。 重写 `-v` 和 `-q`。 ``` #### `--logdir=` ``` \[高级] 将详细日志写入指定目录中的一个或多个文件，生成的文件名包含时间戳和正在运行的子命令名称。 ``` （要使用可以完全控制的名称编写日志文件，请根据需要提供 `--log-to-stderr` 并重定向 stderr。） #### `--common-caches=` ``` \[高级] 控制磁盘上缓存数据的位置，这些数据将在 CLI 的多次运行之间保留，例如下载的 QL 包和编译的查询计划。 如果未明确设置，则默认为用户主目录中名为 `.codeql` 的目录；如果尚不存在，则会创建该目录。 ``` 自 `v2.15.2` 起可用。