CodeQL databases that can't be built using the LGTM worker hosts can be created offline and uploaded to LGTM so that users can easily view analysis results, or run their own queries against the database in the query console. Before uploading a database to LGTM, you must first add a project in upload analysis mode, then prepare the database using the CodeQL command-line interface (CLI). This topic tells you how to create and prepare databases using the CodeQL CLI. For more information about adding projects in upload analysis mode, see Adding a project in upload analysis mode.
Setting up the CodeQL CLI
If you want to create CodeQL databases to upload to LGTM, you must download the version of the CodeQL CLI that is compatible with your version of LGTM. Compatibility information is included in the description for each release on the CodeQL CLI releases page on GitHub. Using the correct version of the CLI ensures that your CodeQL databases are compatible with your version of LGTM.
If you don’t have access to a directly compatible version of the CLI, you can use an older version. This means that the extractor used by the CLI to create databases 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, 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.
After you have downloaded a compatible version of the CodeQL CLI, you need to set it up so it can access the tools, queries, and libraries required to create and analyze databases. For more information, see Getting started with the CodeQL CLI in the CodeQL help.
Creating a CodeQL database
After you have successfully set up the CodeQL CLI, you need to create a CodeQL database containing all the data required to run queries on your code. For more information, see Creating CodeQL databases in the CodeQL help.
Preparing your database
CodeQL databases must be prepared or "bundled" using the
database bundle CodeQL command, before they can be uploaded to LGTM. This command archives the useful parts of a CodeQL database so that it can be moved around more easily, and used with other applications.
To bundle a database, run the following CodeQL command:
codeql database bundle <database> --output=<output-zip>
<database>: the path to the CodeQL database you want to bundle
--output=<output-zip>: the output path of the bundled database
You can also 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 to view in LGTM after the database has been uploaded. Only specify this option if you have created the database using the CodeQL CLI released alongside your version of LGTM. Bundled databases that include results will not be upgraded or uploaded if they are incompatible with LGTM. For more information about analyzing databases, see Analyzing databases with the CodeQL CLI in the CodeQL help.
--mode: specifies how to clean up the cached data in the database. Set as
lightto include as much cached data as possible, so that precomputed intermediate query results (such as cached predicates) are also uploaded to LGTM. This can speed up query execution in the query console. 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 in the CodeQL help.
After you have successfully bundled your database, it is ready to be uploaded to LGTM. For more information, see Adding externally-built CodeQL databases to LGTM.