database create

Note

このコンテンツでは、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>`

[詳細設定] CodeQL データベースの作成方法と後の手順で実行するクエリについてのオプションを指定した Code Scanning 構成ファイルを読み取ります。この構成ファイルの形式について詳しくは、「コードスキャン用の高度なセットアップのカスタマイズ」を参照してください。後の手順でこのファイルからクエリを実行するには、他のクエリを指定せずに codeql database analyze を呼び出します。

`--[no-]db-cluster`

1 つのデータベースを作成する代わりに、異なる言語のデータベースからなる "クラスター" を作成します。そのそれぞれは、コマンドラインで指定したディレクトリのサブディレクトリです。

`-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 を渡して、コンピューター上のコアごとに 1 つのスレッドを使用したり、N を渡して、N 個のコアを未使用のままにしたりすることができます (ただし、その場合でも、少なくとも 1 つのスレッドが使用されます)。

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

この量のメモリをインポート操作に使用し、呼び出されたビルドコマンドにヒントとして渡します。

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

コンパイル型言語の場合は、分析するソースコードに対してコンパイラを呼び出すビルドコマンド。これらのコマンドは、生成されたコードと (場合によっては) 標準ライブラリの分析ができるインストルメンテーション環境で実行されます。

ビルドコマンドを指定していない場合、このコマンドにより、選択した言語パックのヒューリスティックに基づいて、ソースツリーのビルド方法を自動的に把握しようと試みられます。

複数の言語の一部の組み合わせにおいては、明示的なビルドコマンドを指定する "必要がある" ことに注意してください。__

`--no-cleanup`

[詳細設定] ファイナライズ後にすべてのデータベースクリーンアップを抑制します。デバッグが目的の場合に役立ちます。

`--no-pre-finalize`

[詳細設定] アクティブな CodeQL エクストラクターによって指定された事前ファイナライズスクリプトをスキップします。

`--[no-]skip-empty`

[詳細設定] ビルド中にソースコードが表示されず、データベースが空の場合は、失敗するのではなく警告が出力されます。空のデータベースは、ファイナライズされないままになります。

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

[詳細設定] codeql データセットのインポートがリンケージ対応 (既定) かどうかを制御します。データベース作成のこの部分で消費されるメモリが多すぎるプロジェクトでは、このオプションを無効にすると、データベースの完全性が犠牲になりますが、進行しやすくなる場合があります。

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=<dir>[:<dir>...]`

エクストラクターパックが見つかる可能性があるディレクトリのリスト。ディレクトリは、エクストラクターパック自体、またはエクストラクターを直接サブディレクトリとして含むディレクトリのいずれかです。

パスに複数のディレクトリツリーが含まれている場合、それらの順序によってそれらの間の優先順位が定義されます。ターゲット言語が複数のディレクトリツリーで一致する場合、最初に指定されたものが優先されます。

CodeQL ツールチェーン自体にバンドルされているエクストラクターは常に検出されますが、個々に配布されたエクストラクターを使用する必要がある場合は、このオプションを指定する必要があります (または、より良い方法として、ユーザーごとの構成ファイルで --search-path を設定します)。

(注: Windows では、パスの区切り記号は ; です)。

GitHub API を呼び出して言語を自動検出する方法を構成するためのオプション。

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

標準入力を使用して、GitHub Apps トークンまたは個人用アクセストークンを受け入れます。

これにより、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 を渡して、 2 つの 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: ディスクキャッシュに対して定義されたサイズ制限を確認し、必要な数の中間ファイルを削除します。

`--cleanup-upgrade-backups`

データベースのアップグレードに起因するすべてのバックアップディレクトリを削除します。

トレースオプション

`--no-tracing`

[詳細設定] 指定したコマンドをトレースしません。代わりに、必要なすべてのデータを直接生成するために使用します。

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

[詳細設定] トレーサー構成ファイルのパス。ビルドトレーサーの動作を変更するために使用できます。ビルドコマンドの一部として実行されるコンパイラプロセスを選び、他のツールの実行をトリガーするために使用できます。エクストラクターにより、ほとんどの状況で機能する既定のトレーサー構成ファイルが提供されます。

ビルドコマンドのカスタマイズオプション

`--working-dir=<dir>`

[詳細設定] 指定したコマンドを実行するディレクトリ。この引数を指定しない場合、--source-rootcodeql database create に渡されるの値 (存在する場合) でコマンドが実行されます。 --source-root 引数を指定しない場合、コマンドは現在の作業ディレクトリで実行されます。

`--no-run-unnecessary-builds`

[詳細設定] ビルドプロセスのトレースに依存するエクストラクターが作成中のデータベースで使用されている場合にのみ、指定したビルドコマンドを実行します。このオプションを指定しない場合、CodeQL で不要であっても、他の理由で副作用が必要とされているという仮定に基づき、コマンドが実行されます。

エクストラクターの動作を制御するためのオプション

`-O, --extractor-option=<extractor-option-name=value>`

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' があり、その下にエクストラクター名が第 2 レベルのマップキーとして含まれている必要があります。それ以降のレベルのマップは入れ子になったエクストラクターグループを表し、文字列と配列のオプションは、文字列と配列の値を持つマップエントリです。

エクストラクターオプションバンドルファイルは、指定した順序で読み取られます。異なるエクストラクターオプションバンドルファイルで同じエクストラクターオプションを指定した場合、その動作はエクストラクターオプションで想定されている型によって異なります。文字列オプションでは、指定した最後の値が使用されます。配列オプションでは、指定したすべての値が順番に使用されます。このコマンドラインオプションを使用して指定したエクストラクターオプションは、--extractor-option で指定したエクストラクターオプションよりも前に処理されます。

codeql database init または codeql database begin-tracing に渡した場合、オプションは間接トレース環境にのみ適用されます。ワークフローで codeql database trace-command の呼び出しも行う場合は、必要に応じてオプションも渡す必要があります。

各エクストラクターによって宣言されたオプションの一覧を表示する方法など、CodeQL エクストラクターオプションについて詳しくは、https://codeql.github.com/docs/codeql-cli/extractor-options を参照してください。

database create

この機能を使用できるユーザーについて

この記事の内容