database create

Este conteúdo descreve a versão mais recente do CodeQL CLI. Para obter mais informações sobre essa versão, confira https://github.com/github/codeql-cli-binaries/releases.

Para ver os detalhes das opções disponíveis para esse comando em uma versão anterior, execute o comando com a opção --help no terminal.

Sinopse

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>

Descrição

Crie um banco de dados CodeQL para uma árvore de origem que possa ser analisada com um dos produtos do CodeQL.

Opções

Opções principais

`<database>`

[Obrigatório] Caminho para o banco de dados CodeQL a ser criado. Esse diretório será criado e não deve já existir (ao contrário do pai, que precisa existir).

Se a opção --db-cluster for fornecida, isso não será um banco de dados propriamente dito, mas um diretório que conterá bancos de dados para várias linguagens criadas com base na mesma raiz de origem.

É importante que esse diretório não esteja em um local com o qual o processo de build vai interferir. Por exemplo, o diretório target de um projeto Maven não será uma opção adequada.

`--[no-]overwrite`

[Avançado] Se o banco de dados já existir, exclua-o e prossiga com esse comando em vez de causar uma falha. Se o diretório existir, mas não se parecer com um banco de dados, um erro será gerado.

`--[no-]force-overwrite`

[Avançado] Se o banco de dados já existir, exclua-o mesmo que não se pareça com um banco de dados e prossiga com esse comando em vez de causar uma falha. Essa opção deve ser usada com cuidado, pois pode excluir recursivamente todo o diretório do banco de dados.

`--codescanning-config=<file>`

[Avançado] Leia um arquivo de configuração da verificação de código que especifica opções sobre como criar os bancos de dados CodeQL e quais consultas serão executadas nas etapas posteriores. Para obter mais detalhes sobre o formato desse arquivo de configuração, veja Personalizando a configuração avançada para varredura de código. Para executar consultas por meio desse arquivo em uma etapa posterior, invoque codeql database analyze sem nenhuma outra consulta especificada.

`--[no-]db-cluster`

Em vez de criar um banco de dados individual, crie um "cluster" de bancos de dados para linguagens diferentes, cada um deles um subdiretório do diretório fornecido na linha de comando.

`-l, --language=<lang>[,<lang>...]`

A linguagem que o novo banco de dados usará para a análise.

Use codeql resolve languages para obter uma lista dos extratores de linguagem conectáveis encontrados no caminho de pesquisa.

Quando a opção --db-cluster é fornecida, isso pode aparecer várias vezes ou o valor pode ser uma lista separada por vírgula das linguagens.

Se essa opção for omitida e a raiz de origem que estiver sendo analisada for um check-out de um repositório GitHub, a CLI do CodeQL fará uma chamada à API do GitHub para tentar determinar automaticamente as linguagens que serão analisadas. Observe que, para fazer isso, um token PAT do GitHub precisa ser fornecido na variável de ambiente GITHUB_TOKEN ou por meio da entrada padrão com a opção --github-auth-stdin.

`--build-mode=<mode>`

O modo de compilação que será usado para criar o banco de dados.

Escolha seu modo de compilação com base na linguagem que você está analisando:

none: O banco de dados será criado sem criar a raiz do código-fonte. Disponível para C#, Java, JavaScript/TypeScript, Python e Ruby.

autobuild: O banco de dados será criado ao tentar criar automaticamente a raiz do código-fonte. Disponível para C/C++, C#, Go, Java/Kotlin e Swift.

manual: O banco de dados será criado ao compilar a raiz de origem com o uso de um comando de compilação especificado manualmente. Disponível para C/C++, C#, Go, Java/Kotlin e Swift.

Ao criar um banco de dados com --command, não há necessidade de especificar adicionalmente '--build-mode manual'.

Disponível desde v2.16.4.

`-s, --source-root=<dir>`

[Padrão: .] O diretório do código-fonte raiz. Em muitos casos, essa será a raiz do check-out. Os arquivos contidos nele são considerados os arquivos de origem primários desse banco de dados. Em alguns formatos de saída, os arquivos serão referenciados pelo caminho relativo desse diretório.

`-j, --threads=<num>`

Use esse número de threads para a operação de importação e transmita-os como uma dica para todos os comandos de build invocados.

O valor padrão é 1. Você pode transmitir 0 para usar um thread por núcleo no computador ou -N para manter N núcleos não utilizados (com a exceção de que ainda será usado, pelo menos, um thread).

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

Use essa quantidade de memória para a operação de importação e transmita-a como uma dica para todos os comandos de build invocados.

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

Para as linguagens compiladas, crie comandos que farão com que o compilador seja invocado no código-fonte para analisá-lo. Esses comandos serão executados em um ambiente de instrumentação que permite a análise do código gerado e das bibliotecas padrão (em alguns casos).

Se nenhum comando de build for especificado, o comando tentará descobrir automaticamente como criar a árvore de origem, com base na heurística do pacote de linguagens selecionado.

Use-o com cautela, pois algumas combinações de várias linguagens exigem a especificação de um comando de build explícito.

`--no-cleanup`

[Avançado] Suprima toda a limpeza do banco de dados após a finalização. Útil para fins de depuração.

`--no-pre-finalize`

[Avançado] Ignore qualquer script de pré-finalização especificado pelo extrator ativo do CodeQL.

`--[no-]skip-empty`

[Avançado] Gere um aviso em vez de causar uma falha se um banco de dados estiver vazio devido a nenhum código-fonte ter sido visto durante o build. O banco de dados vazio será deixado sem finalização.

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

[Avançado] Controla se a importação do conjunto de dados codeql é compatível com vinculação (padrão) ou não. Em projetos em que essa parte da criação de banco de dados consome muita memória, desabilitar essa opção pode ajudá-los a progredir às custas da integridade do banco de dados.

Disponível desde v2.15.3.

Opções de cálculo da linha de base

`--[no-]calculate-baseline`

[Avançado] Calcule as informações de linha de base sobre o código que está sendo analisado e adicione-o ao banco de dados. Por padrão, isso é habilitado, a menos que a raiz de origem seja a raiz de um sistema de arquivos. Esse sinalizador pode ser usado para desabilitar ou forçar o comportamento a ser habilitado mesmo na raiz do sistema de arquivos.

`--[no-]sublanguage-file-coverage`

[Somente para GitHub.com e GitHub Enterprise Server v3.12.0+] Use informações de cobertura de arquivo de sub-linguagem. Isso calcula, exibe e exporta informações de cobertura de arquivos separadas para linguagens que compartilham um extrator CodeQL como C e C++, Java e Kotlin e JavaScript e TypeScript.

Disponível desde v2.15.2.

Opções de seleção do extrator

`--search-path=<dir>[:<dir>...]`

Uma lista de diretórios nos quais os pacotes de extratores podem ser encontrados. Os diretórios podem ser os próprios pacotes extratores ou diretórios que contenham extratores como subdiretórios imediatos.

Se o caminho contiver várias árvores de diretório, a ordem delas definirá a precedência entre elas: se for encontrada uma correspondência da linguagem de destino em mais de uma das árvores de diretório, a primeira fornecida vencerá.

Os extratores empacotados com a própria cadeia de ferramentas CodeQL sempre serão encontrados, mas se você precisar usar extratores distribuídos separadamente, forneça essa opção (ou, melhor ainda, configure --search-path em um arquivo de configuração por usuário).

(Observação: no Windows, o separador de caminho é ;).

Opções para configurar como chamar a API do GitHub para detectar linguagens automaticamente.

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

Aceite um token do GitHub Apps ou um token de acesso pessoal por meio da entrada padrão.

Isso substitui a variável de ambiente GITHUB_TOKEN.

`-g, --github-url=<url>`

URL da instância do GitHub a ser usada. Se isso for omitido, a CLI tentará fazer a detecção automática dela por meio do caminho do check-out e, se isso não for possível, usará https://github.com/ como padrão

Opções para configurar o gerenciador de pacotes.

`--registries-auth-stdin`

Autentique-se nos registros de contêiner do GitHub Enterprise Server transmitindo uma lista separada por vírgula de pares <registry_url>=<token>.

Por exemplo, você pode transmitir https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2 para se autenticar em duas instâncias do GitHub Enterprise Server.

Isso substitui as variáveis de ambiente CODEQL_REGISTRIES_AUTH e GITHUB_TOKEN. Se você só precisar se autenticar no registro de contêiner do github.com, poderá se autenticar usando a opção --github-auth-stdin mais simples.

Opções de limpeza de conjunto de dados de baixo nível

`--max-disk-cache=<MB>`

Defina a quantidade máxima de espaço que pode ser usada pelo cache de disco para os resultados intermediários da consulta.

Se esse tamanho não for configurado explicitamente, o avaliador tentará usar uma quantidade "razoável" de espaço em cache, com base no tamanho do conjunto de dados e na complexidade das consultas. Se você definir explicitamente um limite mais alto do que esse uso padrão, isso habilitará o cache adicional, que pode acelerar as consultas posteriores.

`--min-disk-free=<MB>`

[Avançado] Defina a quantidade de destino de espaço livre no sistema de arquivos.

Se --max-disk-cache não for fornecido, o avaliador tentará reduzir o uso do cache de disco se o espaço livre no sistema de arquivos ficar abaixo desse valor.

`--min-disk-free-pct=<pct>`

[Avançado] Defina a fração de destino de espaço livre no sistema de arquivos.

Se --max-disk-cache não for fornecido, o avaliador tentará reduzir o uso do cache de disco se o espaço livre no sistema de arquivos ficar abaixo desse percentual.

`--cache-cleanup=<mode>`

Selecione o nível de agressividade de corte do cache. As opções incluem:

clear: remova todo o cache, reduzindo-o ao estado de um conjunto de dados recém-extraído

trim (padrão) : corte tudo, exceto os predicados explicitamente "armazenados em cache".

fit: verifique se os limites de tamanho definidos para o cache de disco são observados, excluindo quantos intermediários forem necessários.

`--cleanup-upgrade-backups`

Exclua todos os diretórios de backup resultantes das atualizações de banco de dados.

Opções de rastreamento

`--no-tracing`

[Avançado] Não rastreie o comando especificado. mas dependa dele para produzir todos os dados necessários diretamente.

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

[Avançado] O caminho para um arquivo de configuração do rastreador. Ele pode ser usado para modificar o comportamento do rastreador de build. Ele pode ser usado para escolher processos do compilador executados como parte do comando de build e disparar a execução de outras ferramentas. Os extratores fornecerão arquivos de configuração do rastreador padrão que devem funcionar na maioria das situações.

Opções de personalização de comando de build

`--working-dir=<dir>`

[Avançado] O diretório no qual o comando especificado deve ser executado. Se esse argumento não for fornecido, o comando será executado no valor de --source-root transmitido para codeql database create, se houver um. Se nenhum argumento --source-root for fornecido, o comando será executado no diretório de trabalho atual.

`--no-run-unnecessary-builds`

[Avançado] Só execute os comandos de build especificados se um banco de dados em construção usar um extrator que dependa do rastreamento de um processo de build. Se essa opção não for fornecida, o comando será executado mesmo quando o CodeQL não precisar dele, na suposição de que você precisa dos efeitos colaterais dele por outros motivos.

Opções para controlar o comportamento do extrator

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

Defina as opções para os extratores do CodeQL. extractor-option-name deve ter o formato extractor_name.group1.group2.option_name ou group1.group2.option_name. Se extractor_option_name começar com o nome de um extrator, o extrator indicado precisará declarar a opção group1.group2.option_name. Caso contrário, qualquer extrator que declare a opção group1.group2.option_name terá a opção definida. value pode ser qualquer cadeia de caracteres que não contenha uma nova linha.

Use essa opção de linha de comando repetidamente para definir várias opções de extratores. Se você fornecer vários valores para a mesma opção de extrator, o comportamento dependerá do tipo esperado pela opção de extrator. As opções de cadeia de caracteres usarão o último valor fornecido. As opções de matriz usarão todos os valores fornecidos, em ordem. As opções de extratores especificadas com essa opção de linha de comando são processadas após as opções de extratores fornecidas por meio de --extractor-options-file.

Quando transmitido para codeql database init ou codeql database begin-tracing, as opções serão aplicadas somente ao ambiente de rastreamento indireto. Se o fluxo de trabalho também fizer chamadas a codeql database trace-command, as opções também precisarão ser transmitidas para ele, se desejado.

Confira https://codeql.github.com/docs/codeql-cli/extractor-options para obter mais informações sobre as opções do extrator do CodeQL, incluindo como listar as opções declaradas pelos extratores.

`--extractor-options-file=<extractor-options-bundle-file>`

Especifique os arquivos de pacote de opções de extratores. Um arquivo de pacote de opções de extratores é um arquivo JSON (extensão .json) ou um arquivo YAML (extensão .yaml ou .yml) que define as opções de extratores. O arquivo precisa ter a chave de mapa de nível superior 'extractor' e, abaixo dela, os nomes de extratores como chaves de mapa de segundo nível. Outros níveis de mapas representam grupos de extratores aninhados, e as opções de cadeia de caracteres e matriz são entradas de mapa com valores de cadeia de caracteres e matriz.

Os arquivos do pacote de opções de extratores são lidos na ordem em que são especificados. Se diferentes arquivos do pacote de opções de extratores especificarem a mesma opção de extrator, o comportamento dependerá do tipo esperado pela opção de extrator. As opções de cadeia de caracteres usarão o último valor fornecido. As opções de matriz usarão todos os valores fornecidos, em ordem. As opções de extratores especificadas com essa opção de linha de comando são processadas antes das opções de extratores fornecidas por meio de --extractor-option.

Opções comuns

`-h, --help`

Mostre este texto de ajuda.

`-J=<opt>`

[Avançado] Forneça a opção para a JVM que executa o comando.

(Use-a com cautela, pois as opções que contêm espaços não serão tratadas corretamente.)

`-v, --verbose`

Aumente incrementalmente o número de mensagens de progresso impressas.

`-q, --quiet`

Diminua incrementalmente o número de mensagens de progresso impressas.

`--verbosity=<level>`

[Avançado] Defina explicitamente o nível de detalhamento como erros, avisos, progresso, progresso+, progresso++ ou progresso+++. Substitui -v e -q.

`--logdir=<dir>`

[Avançado] Escreva logs detalhados em um ou mais arquivos no diretório fornecido, com nomes gerados que incluem carimbos de data/hora e o nome do subcomando em execução.

(Para gravar um arquivo de log com um nome sobre o qual você tem controle completo, forneça --log-to-stderr e redirecione stderr conforme desejado.)

`--common-caches=<dir>`

[Avançado] Controle a localização dos dados armazenados em cache no disco que persistirão entre várias execuções da CLI, como pacotes QL baixados e planos de consulta compilada. Se não for definido explicitamente, o padrão corresponde a um diretório intitulado .codeql no diretório inicial do usuário; que será criado se ainda não existir.

Disponível desde v2.15.2.

Quem pode usar esse recurso?

Neste artigo