215 lines
6.3 KiB
Markdown
215 lines
6.3 KiB
Markdown
---
|
|
title: database finalize
|
|
versions:
|
|
fpt: '*'
|
|
ghae: '*'
|
|
ghec: '*'
|
|
ghes: '*'
|
|
topics:
|
|
- Advanced Security
|
|
- Code scanning
|
|
- CodeQL
|
|
type: reference
|
|
product: '{% data reusables.gated-features.codeql %}'
|
|
autogenerated: codeql-cli
|
|
intro: '[Plumbing] Final steps in database creation.'
|
|
redirect_from:
|
|
- /code-security/codeql-cli/manual/database-finalize
|
|
---
|
|
|
|
|
|
<!-- Content after this section is automatically generated -->
|
|
|
|
{% data reusables.codeql-cli.man-pages-version-note %}
|
|
|
|
## Synopsis
|
|
|
|
```shell{:copy}
|
|
codeql database finalize [--dbscheme=<file>] [--threads=<num>] [--ram=<MB>] [--mode=<mode>] <options>... -- <database>
|
|
```
|
|
|
|
## Description
|
|
|
|
\[Plumbing] Final steps in database creation.
|
|
|
|
Finalize a database that was created with [codeql database init](/code-security/codeql-cli/codeql-cli-manual/database-init) and subsequently seeded with analysis data using [codeql database trace-command](/code-security/codeql-cli/codeql-cli-manual/database-trace-command). This needs to happen before the new database can be queried.
|
|
|
|
## Primary options
|
|
|
|
#### `<database>`
|
|
|
|
\[Mandatory] Path to the CodeQL database under construction. This must
|
|
have been prepared for extraction with [codeql database init](/code-security/codeql-cli/codeql-cli-manual/database-init).
|
|
|
|
If the `--db-cluster` option is given, this is not a database itself,
|
|
but a directory that *contains* databases, and all of those databases
|
|
will be processed together.
|
|
|
|
#### `--[no-]db-cluster`
|
|
|
|
Indicates that the directory given on the command line is not a database
|
|
itself, but a directory that *contains* one or more databases under
|
|
construction. Those databases will be processed together.
|
|
|
|
#### `--additional-dbs=<database>[:<database>...]`
|
|
|
|
\[Advanced] Path to additional CodeQL databases under construction.
|
|
These will not themselves be finalized, but the data from them will be
|
|
included in the finalized database being created. This is an advanced
|
|
option that may not have the desired effect in all cases. For more
|
|
information, please refer to the documentation of [codeql database import](/code-security/codeql-cli/codeql-cli-manual/database-import).
|
|
|
|
If the `--db-cluster` option is given, it is expected that these will be
|
|
database clusters rather than individual CodeQL databases.
|
|
|
|
(Note: On Windows the path separator is `;`).
|
|
|
|
#### `--no-cleanup`
|
|
|
|
\[Advanced] Suppress all database cleanup after finalization. Useful
|
|
for debugging purposes.
|
|
|
|
#### `--no-pre-finalize`
|
|
|
|
\[Advanced] Skip any pre-finalize script specified by the active CodeQL
|
|
extractor.
|
|
|
|
#### `--[no-]skip-empty`
|
|
|
|
\[Advanced] Output a warning instead of failing if a database is empty
|
|
because no source code was seen during the build. The empty database
|
|
will be left unfinalized.
|
|
|
|
### Options for controlling the TRAP import operation
|
|
|
|
#### `-S, --dbscheme=<file>`
|
|
|
|
\[Advanced] Override the auto-detected dbscheme definition that the
|
|
TRAP files are assumed to adhere to. Normally, this is taken from the
|
|
database's extractor.
|
|
|
|
#### `-j, --threads=<num>`
|
|
|
|
Use this many threads for the import operation.
|
|
|
|
Defaults to 1. You can pass 0 to use one thread per core on the machine,
|
|
or -*N* to leave *N* cores unused (except still use at least one
|
|
thread).
|
|
|
|
#### `-M, --ram=<MB>`
|
|
|
|
Use this much memory for the import operation.
|
|
|
|
### Low-level dataset cleanup options
|
|
|
|
#### `--max-disk-cache=<MB>`
|
|
|
|
Set the maximum amount of space that the disk cache for intermediate
|
|
query results can use.
|
|
|
|
If this size is not configured explicitly, the evaluator will try to use
|
|
a "reasonable" amount of cache space, based on the size of the dataset
|
|
and the complexity of the queries. Explicitly setting a higher limit
|
|
than this default usage will enable additional caching which can speed
|
|
up later queries.
|
|
|
|
#### `--min-disk-free=<MB>`
|
|
|
|
\[Advanced] Set target amount of free space on file system.
|
|
|
|
If `--max-disk-cache` is not given, the evaluator will try hard to
|
|
curtail disk cache usage if the free space on the file system drops
|
|
below this value.
|
|
|
|
#### `--min-disk-free-pct=<pct>`
|
|
|
|
\[Advanced] Set target fraction of free space on file system.
|
|
|
|
If `--max-disk-cache` is not given, the evaluator will try hard to
|
|
curtail disk cache usage if the free space on the file system drops
|
|
below this percentage.
|
|
|
|
#### `-m, --mode=<mode>`
|
|
|
|
Select how aggressively to trim the cache. Choices include:
|
|
|
|
`brutal`: Remove the entire cache, trimming down to the state of a
|
|
freshly extracted dataset
|
|
|
|
`normal` *(default)*: Trim everything except explicitly "cached"
|
|
predicates.
|
|
|
|
`light`: Simply make sure the defined size limits for the disk cache are
|
|
observed, deleting as many intermediates as necessary.
|
|
|
|
#### `--cleanup-upgrade-backups`
|
|
|
|
Delete any backup directories resulting from database upgrades.
|
|
|
|
### Options for checking imported TRAP
|
|
|
|
#### `--[no-]check-undefined-labels`
|
|
|
|
\[Advanced] Report errors for undefined labels.
|
|
|
|
#### `--[no-]check-unused-labels`
|
|
|
|
\[Advanced] Report errors for unused labels.
|
|
|
|
#### `--[no-]check-repeated-labels`
|
|
|
|
\[Advanced] Report errors for repeated labels.
|
|
|
|
#### `--[no-]check-redefined-labels`
|
|
|
|
\[Advanced] Report errors for redefined labels.
|
|
|
|
#### `--[no-]check-use-before-definition`
|
|
|
|
\[Advanced] Report errors for labels used before they're defined.
|
|
|
|
#### `--[no-]fail-on-trap-errors`
|
|
|
|
\[Advanced] Exit non-zero if an error occurs during trap import.
|
|
|
|
#### `--[no-]include-location-in-star`
|
|
|
|
\[Advanced] Construct entity IDs that encode the location in the TRAP
|
|
file they came from. Can be useful for debugging of TRAP generators, but
|
|
takes up a lot of space in the dataset.
|
|
|
|
### Common options
|
|
|
|
#### `-h, --help`
|
|
|
|
Show this help text.
|
|
|
|
#### `-J=<opt>`
|
|
|
|
\[Advanced] Give option to the JVM running the command.
|
|
|
|
(Beware that options containing spaces will not be handled correctly.)
|
|
|
|
#### `-v, --verbose`
|
|
|
|
Incrementally increase the number of progress messages printed.
|
|
|
|
#### `-q, --quiet`
|
|
|
|
Incrementally decrease the number of progress messages printed.
|
|
|
|
#### `--verbosity=<level>`
|
|
|
|
\[Advanced] Explicitly set the verbosity level to one of errors,
|
|
warnings, progress, progress+, progress++, progress+++. Overrides `-v`
|
|
and `-q`.
|
|
|
|
#### `--logdir=<dir>`
|
|
|
|
\[Advanced] Write detailed logs to one or more files in the given
|
|
directory, with generated names that include timestamps and the name of
|
|
the running subcommand.
|
|
|
|
(To write a log file with a name you have full control over, instead
|
|
give `--log-to-stderr` and redirect stderr as desired.)
|