Skip to main content

database create

いずれかの CodeQL 製品を使用して分析できるソース ツリー用の CodeQL データベースを作成します。

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

GitHub CodeQL は、インストール時にユーザーごとにライセンスされます。 CodeQL は、ライセンスの制限の下で特定のタスクでのみ使用できます。 詳しくは、「CodeQL CLI について」を参照してください。

GitHub Advanced Security ライセンスがある場合は、CodeQL を使用して、自動分析、継続的インテグレーション、継続的デリバリーを行うことができます。 詳しくは、「GitHub Advanced Security について」を参照してください。

この記事の内容

このコンテンツでは、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>] [--mode=<mode>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database>

説明

いずれかの CodeQL 製品を使用して分析できるソース ツリー用の CodeQL データベースを作成します。

[オプション]

主なオプション

<database>

[必須] 作成する CodeQL データベースのパス。 このディレクトリは作成され、既に存在していては "なりません" (ただし、その親は必要です)。__

--db-cluster オプションを指定すると、これはデータベース自体ではなく、同じソース ルートから構築された複数の言語のデータベースを "含む" ディレクトリになります。__

このディレクトリは、構築プロセスが干渉する場所に存在しないことが重要です。 たとえば、Maven プロジェクトの target ディレクトリは適切な選択肢ではありません。

--[no-]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: ソース ルートを構築せずにデータベースが作成されます。 JavaScript/TypeScript、Python、Ruby で使用できます。

autobuild: ソース ルートを自動的にビルドしようとすると、データベースが作成されます。 C/C++、C#、Go、Java/Kotlin、Swift で使用できます。

manual: データベースは、手動で指定したビルド コマンドを使用してソース ルートをビルドすることによって作成されます。 C/C++、C#、Go、Java/Kotlin、Swift で使用できます。

--command を使用してデータベースを作成する場合、'--build-mode none' を追加で指定する必要はありません。

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 が指定されていない場合、ファイル システムの空き容量がこの割合を下回ると、エバリュエーターはディスク キャッシュの使用量を抑えようとします。

-m, --mode=<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 を参照してください。

共通オプション

-h, --help

このヘルプ テキストを表示します。

-J=<opt>

[詳細設定] コマンドを実行している JVM にオプションを指定します

(スペースを含むオプションは正しく処理されないことに注意してください)。

-v, --verbose

出力される進行状況メッセージの数を段階的に増やします。

-q, --quiet

出力される進行状況メッセージの数を段階的に減らします。

--verbosity=<level>

[詳細設定] 詳細レベルを、errors、warnings、progress、progress+、progress++、progress+++ のいずれかに明示的に設定します。 -v-q がオーバーライドされます。

--logdir=<dir>

[詳細設定] タイムスタンプと実行中のサブコマンドの名前を含む生成された名前を使用して、指定されたディレクトリ内の 1 つまたは複数のファイルに詳細なログを書き込みます

(完全に制御できる名前でログ ファイルを書き込むには、代わりに --log-to-stderr を指定し、必要に応じて stderr をリダイレクトします)。

--common-caches=<dir>

[[詳細設定] ダウンロードした QL パックやコンパイル済みクエリ プランなど、CLI の複数の実行間に保持される、ディスク上でキャッシュされたデータの場所を制御します。 明示的に設定されない場合、既定ではユーザーのホーム ディレクトリに名前が付けられた .codeql ディレクトリになります。まだ存在しない場合は作成されます。

v2.15.2 以降で使用できます。