Preparing CodeQL databases to use with LGTM Enterprise

Overview

CodeQL databases with complex build requirements can be uploaded to LGTM Enterprise using the LGTM API. This makes it easier for more users to view analysis results, and makes the uploaded database available in the LGTM query console.

This topic explains how to use the database bundle subcommand to prepare databases for use with LGTM Enterprise.

Note

CodeQL databases are not directly compatible with the legacy IDE plugin, CodeQL for Eclipse. For more information about preparing databases to use with CodeQL for Eclipse, see Database compatibility notes.

Prerequisites

The databases that you want to upload to LGTM Enterprise must have been created using a version of the CodeQL CLI that is compatible with your version of LGTM.

For the release of LGTM Enterprise 1.23 (and future releases), there will be a simultaneous release of the CodeQL CLI that uses compatible tools for this purpose. Use this version of the CLI to ensure your databases are compatible without LGTM having to upgrade them. For further information, see the LGTM Enterprise releases page and Setting up the CodeQL CLI.

Click to show more information about using other versions of the CodeQL CLI

Note

If you don’t have access to compatible version of the CLI, you can use an older version. This means that the extractor used by the CLI will either be the same as, or older than, the version used by LGTM. If it’s the same, the database will be compatible. If it’s older, then the database may not be directly compatible, but LGTM can upgrade it after it has been uploaded.

If your CodeQL CLI is newer than LGTM, then the extractor may be newer than the one used by LGTM. In this case, databases created using the CLI are not compatible, and LGTM cannot downgrade them. These databases cannot be uploaded to LGTM.

For further information about creating databases with the CodeQL CLI, see Creating a CodeQL database.

Running codeql database bundle

The database bundle command archives the useful parts of a CodeQL database so that it can be moved around more easily, and used with other applications.

You can bundle a database by running the following command:

codeql database bundle <database> --ouput=<output-zip>

You must specify:

  • <database>: the path to the CodeQL database you want to bundle.
  • --output: the output path of the bundled database.

You can include extra data in your bundled database by specifying the following options:

  • --include-results: includes precomputed analysis results in the bundle, which will be available in LGTM after the database has been added. Only specify this option if you have created the database using the CodeQL CLI released alongside your version of LGTM Enterprise–bundled databases that include results will not be upgraded if they are incompatible with LGTM, and they cannot be uploaded. For more information about analyzing databases, see Analyzing databases with the CodeQL CLI.
  • --mode: specifies how aggressively to clean up the cached data in the database. Set as light to include as much cached data as possible, so that precomputed intermediate query results (such as cached predicates) are also uploaded to LGTM and available for other users. Note, if your database needs to be upgraded, cached data will be ignored by LGTM.

For full details of all the options you can specify when bundling databases, see the database bundle reference documentation.

Uploading snapshots to LGTM

After you have bundled your database, you can upload it to LGTM using the LGTM API. As part of the upload process, the database will be analyzed by running the standard LGTM query suites, if the results are not included in the bundle. For further information, see About the API for LGTM in the LGTM administrator help.