database create

Note

En este contenido se describe la versión más reciente de CodeQL CLI. Para obtener más información sobre esta versión, consulta https://github.com/github/codeql-cli-binaries/releases.

Para ver detalles de las opciones disponibles para este comando en una versión anterior, ejecuta el comando con la opción --help en el terminal.

Sinopsis

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>

Descripción

Crea una base de datos CodeQL para un árbol de origen que se pueda analizar mediante uno de los productos CodeQL.

Opciones

Opciones principales

`<database>`

[Obligatorio] Ruta de acceso a la base de datos CodeQL que se va a crear. Se creará este directorio y no debe existir previamente (por el contrario, su elemento primario sí debe existir).

Si se brinda la opción --db-cluster, no será una base de datos en sí misma, sino un directorio que contendrá bases de datos para varios lenguajes creadas a partir de la misma raíz de origen.

Es importante que este directorio no esté en una ubicación con la que interfiera el proceso de compilación. Por ejemplo, el directorio target de un proyecto de Maven no sería una opción adecuada.

`--[no-]overwrite`

[Avanzado] Si la base de datos ya existe, elimínala y sigue con este comando en lugar de generar un error. Si el directorio existe, pero no parece una base de datos, se producirá un error.

[Avanzado] Si la base de datos ya existe, elimínala incluso si no parece una base de datos y sigue con este comando en lugar de generar un error. Esta opción se debe usar con precaución, ya que puede eliminar de manera recursiva todo el directorio de base de datos.

`--codescanning-config=<file>`

[Avanzado] Lee un archivo de configuración de examen de código que especifique las opciones para crear las bases de datos CodeQL y las consultas que se van a ejecutar en pasos posteriores. Para información más detallada sobre el formato de este archivo de configuración, consulta Personalización de la configuración avanzada para el examen de código. Para ejecutar consultas desde este archivo en un paso posterior, invoca codeql database analyze sin ninguna otra consulta especificada.

`--[no-]db-cluster`

En lugar de crear una base de datos única, crea un "clúster" de bases de datos para distintos lenguajes, cada una de los cuales es un subdirectorio del directorio especificado en la línea de comandos.

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

Lenguaje que la base de datos nueva usará para realizar el análisis.

Usa codeql resolve languages para obtener una lista de los extractores de lenguaje conectables que se encuentran en la ruta de búsqueda.

Cuando se proporciona la opción --db-cluster, puede aparecer varias veces, o bien el valor puede ser una lista de lenguajes separados por coma.

Si se omite esta opción y la raíz de origen que se analiza es una extracción de un repositorio de GitHub, la CLI de CodeQL llamará a la API de GitHub para intentar determinar automáticamente los lenguajes que se van a analizar. Ten en cuenta que, para poder hacerlo, se debe proporcionar un token de acceso personal de GitHub en la variable de entorno GITHUB_TOKEN o a través de la entrada estándar con la opción --github-auth-stdin.

`--build-mode=<mode>`

Modo de compilación que se usará para crear la base de datos.

Elija el modo de compilación en función del lenguaje que está analizando:

none: la base de datos se creará sin compilar la raíz de origen. Disponible para C#, Java, JavaScript/TypeScript, Python y Ruby.

autobuild: la base de datos se creará intentando compilar automáticamente la raíz de origen. Disponible para C/C++, C#, Go, Java/Kotlin y Swift.

manual: la base de datos se creará mediante la compilación de la raíz de origen mediante un comando de compilación especificado manualmente. Disponible para C/C++, C#, Go, Java/Kotlin y Swift.

Al crear una base de datos con --command, no es necesario especificar además "--build-mode manual".

Disponible desde la versión v2.16.4.

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

[Valor predeterminado: .] Directorio de código fuente raíz. En muchos casos, será la raíz de la extracción. Los archivos que se encuentran en su interior se consideran los archivos de origen principales para esta base de datos. En algunos formatos de salida, la ruta de acceso relativa de este directorio hará referencia a los archivos.

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

Usa todos estos subprocesos para la operación de importación y pásala como una sugerencia a los comandos de compilación invocados.

De manera predeterminada, su valor es 1. Puedes pasar 0 para usar un subproceso por núcleo en la máquina o -N para dejar N núcleos sin utilizar (excepto que aún se usa al menos un subproceso).

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

Usa toda esta memoria para la operación de importación y pásala como una sugerencia a los comandos de compilación invocados.

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

En el caso de los lenguajes compilados, comandos de compilación que harán que se invoque el compilador en el código fuente que se va analizar. Estos comandos se ejecutarán en un entorno de instrumentación que permita el análisis de código generado y (en algunos casos) bibliotecas estándar.

Si no se especifica ningún comando de compilación, el comando intenta averiguar automáticamente cómo compilar el árbol de origen, en función de la heurística del paquete de lenguaje seleccionado.

Ten en cuenta que algunas combinaciones de varios lenguajes requieren que se especifique un comando de compilación explícito.

`--no-cleanup`

[Avanzado] Después de la finalización, suprime toda la limpieza de la base de datos. Esto es útil con fines de depuración.

`--no-pre-finalize`

[Avanzado] Omite cualquier script finalizado previamente especificado por el extractor de CodeQL activo.

`--[no-]skip-empty`

[Avanzado] Genera una advertencia en lugar de generar un error si una base de datos está vacía porque no se ha visto ningún código fuente durante la compilación. La base de datos vacía quedará sin finalizar.

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

[Avanzado] Controla si codeql dataset import reconoce la vinculación (valor predeterminado) o no. En los proyectos en los que esta parte de la creación de la base de datos consume demasiada memoria, deshabilitar esta opción puede ayudarles a avanzar a costa de la integridad de la base de datos.

Disponible desde la versión v2.15.3.

Opciones de cálculo de línea base

`--[no-]calculate-baseline`

[Avanzado] Calcula la información de línea de base sobre el código que se está analizando y agrégala a la base de datos. De manera predeterminada, esta opción se encuentra habilitada, a menos que la raíz de origen sea la raíz de un sistema de archivos. Esta marca se puede usar para deshabilitar o forzar la habilitación del comportamiento incluso en la raíz del sistema de archivos.

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

[GitHub.com y GitHub Enterprise Server v3.12.0 y versiones posteriores solamente] Use la información de cobertura de archivos de sublenguaje. Esto calcula, muestra y exporta información de cobertura de archivos independiente para lenguajes que comparten un extractor de CodeQL como C y C++, Java y Kotlin, y JavaScript y TypeScript.

Disponible desde la versión v2.15.2.

Opciones de selección del extractor

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

Lista de directorios en los que pueden encontrarse los paquetes extractores. Los directorios pueden ser los paquetes extractores en sí o directorios que contienen extractores como subdirectorios inmediatos.

Si la ruta de acceso contiene varios árboles de directorios, su orden define la prioridad entre ellos: si el lenguaje de destino tiene coincidencias en más de uno de los árboles de directorio, tiene prioridad el que aparece primero.

Los extractores agrupados con la propia cadena de herramientas CodeQL siempre se encontrarán, pero si necesita usar extractores distribuidos por separado, debe proporcionar esta opción (o mejor aún, configurar --search-path en un archivo de configuración por usuario).

(Nota: En Windows, el separador de ruta de acceso es ;).

Opciones para configurar cómo llamar a la API de GitHub para detectar lenguajes automáticamente.

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

Acepta un token de GitHub Apps o un token de acceso personal por medio de la entrada estándar.

Esto invalida la variable de entorno GITHUB_TOKEN.

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

Dirección URL de la instancia de GitHub que se va a usar. Si se omite, la CLI intentará detectarlo automáticamente a partir de la ruta de acceso de extracción del repositorio y, si no es posible, se establece https://github.com/ como predeterminada.

Opciones para configurar el administrador de paquetes.

`--registries-auth-stdin`

Autentícate en los registros de contenedores de servidor de GitHub Enterprise; para ello, pasa una lista separada por comas de pares <registry_url>=<token>.

Por ejemplo, puedes pasar https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2 para autenticarte en dos instancias del servidor de GitHub Enterprise.

Esto invalida las variables de entorno CODEQL_REGISTRIES_AUTH y GITHUB_TOKEN. Si solo necesitas autenticarte en el registro de contenedor de github.com, puedes hacerlo mediante la opción --github-auth-stdin más sencilla.

Opciones de limpieza de conjuntos de datos de bajo nivel

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

Establece la cantidad máxima de espacio que puede usar la caché del disco para los resultados intermedios de la consulta.

Si este tamaño no está configurado explícitamente, el evaluador intentará usar una cantidad "razonable" de espacio de caché, en función del tamaño del conjunto de datos y de la complejidad de las consultas. Establecer explícitamente un límite mayor que este uso predeterminado permitirá el almacenamiento en caché adicional que puede acelerar las consultas posteriores.

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

[Avanzado] Establece la cantidad de espacio libre de destino en el sistema de archivos.

Si no se proporciona --max-disk-cache, el evaluador intentará reducir el uso de la caché del disco si el espacio libre en el sistema de archivos cae por debajo de este valor.

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

[Avanzado] Establece la fracción de destino del espacio libre en el sistema de archivos.

Si no se proporciona --max-disk-cache, el evaluador intentará reducir el uso de la caché del disco si el espacio libre en el sistema de archivos cae por debajo de este porcentaje.

`--cache-cleanup=<mode>`

Selecciona cómo recortar la caché de forma agresiva. Entre las opciones se incluyen:

clear: quita toda la caché y recorta hasta el estado de un conjunto de datos recién extraído.

trim (valor predeterminado) : recorta todo excepto los predicados "almacenados en caché" explícitamente.

fit: simplemente asegúrese de que se observan los límites de tamaño definidos para la caché de disco y que se eliminan tantos intermedios como sea necesario.

`--cleanup-upgrade-backups`

Elimina los directorios de copia de seguridad resultantes de las actualizaciones de la base de datos.

Opciones de seguimiento

`--no-tracing`

[Avanzando] No hagas un seguimiento del comando especificado. En lugar de eso, úsalo para generar directamente todos los datos necesarios.

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

[Avanzado] Ruta de acceso a un archivo de configuración de seguimiento. Se puede usar para modificar el comportamiento del seguimiento de compilación. Se puede usar para seleccionar los procesos del compilador que se ejecutan como parte del comando de compilación y desencadenar la ejecución de otras herramientas. Los extractores proporcionarán archivos de configuración de seguimiento predeterminados que deben funcionar en la mayoría de las situaciones.

Opciones de personalización del comando de compilación

`--working-dir=<dir>`

[Avanzado] Directorio en el que se debe ejecutar el comando especificado. Si no se proporciona este argumento, el comando se ejecuta en el valor de --source-root pasado a codeql database create, si existe alguno. Si no se proporciona ningún argumento --source-root, el comando se ejecuta en el directorio de trabajo actual.

`--no-run-unnecessary-builds`

[Avanzado] Ejecuta solo los comandos de compilación especificados si una base de datos en construcción usa un extractor que depende del seguimiento de un proceso de compilación. Si no se proporciona esta opción, el comando se ejecutará incluso cuando CodeQL no lo necesite, sobre el supuesto de que necesitas sus efectos secundarios por otros motivos.

Opciones para controlar el comportamiento del extractor

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

Establece opciones para los extractores de CodeQL. extractor-option-name debe tener el formato extractor_name.group1.group2.option_name o group1.group2.option_name. Si extractor_option_name comienza con un nombre de extractor, el extractor indicado debe declarar la opción group1.group2.option_name. De lo contrario, cualquier extractor que declare la opción group1.group2.option_name tendrá la opción establecida. value puede ser cualquier cadena que no contenga una nueva línea.

Puedes usar esta opción de línea de comandos repetidamente para establecer varias opciones de extractor. Si proporcionas varios valores para la misma opción de extractor, el comportamiento depende del tipo que espera la opción de extractor. Las opciones de cadena usarán el último valor proporcionado. Las opciones de matriz usarán todos los valores proporcionados, en orden. Las opciones de extractor especificadas mediante esta opción de línea de comandos se procesan después de las opciones de extractor dadas a través de --extractor-options-file.

Cuando se pasa a codeql database init o codeql database begin-tracing, las opciones solo se aplican al entorno de seguimiento indirecto. Si el flujo de trabajo también realiza llamadas a codeql database trace-command, las opciones también deben pasarse allí si así lo quieres.

Consulta https://codeql.github.com/docs/codeql-cli/extractor-options para más información sobre las opciones de extractor de CodeQL, incluido cómo enumerar las opciones declaradas por cada extractor.

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

Especifica los archivos de agrupación de opciones de extractor. Un archivo de agrupación de opciones de extractor es un archivo JSON (extensión .json) o un archivo YAML (extensión .yaml o .yml) que establece las opciones de extractor. El archivo debe tener la clave de mapa de nivel superior "extractor" y, debajo, los nombres del extractor como claves de mapa de segundo nivel. Otros niveles de mapas representan grupos de extractores anidados y las opciones de cadena y matriz son entradas de mapa con valores de cadena y matriz.

Los archivos de agrupación de opciones de extractor se leen en el orden en que se especifican. Si diferentes archivos de agrupación de opciones de extractor especifican la misma opción de extractor, el comportamiento depende del tipo que espera la opción de extractor. Las opciones de cadena usarán el último valor proporcionado. Las opciones de matriz usarán todos los valores proporcionados, en orden. Las opciones de extractor especificadas mediante esta opción de línea de comandos se procesan antes que las opciones de extractor proporcionadas a través de --extractor-option.

Opciones comunes

`-h, --help`

Muestra este texto de ayuda.

`-J=<opt>`

[Avanzado] Asigna la opción a la JVM que ejecuta el comando.

(Ten en cuenta que las opciones que contienen espacios no se administrarán correctamente).

`-v, --verbose`

Aumenta incrementalmente el número de mensajes de progreso impresos.

`-q, --quiet`

Reduce incrementalmente el número de mensajes de progreso impresos.

`--verbosity=<level>`

[Avanzado] Establece explícitamente el nivel de detalle en errores, advertencias, progreso, progreso+, progreso++, progreso+++. Invalida -v y -q.

`--logdir=<dir>`

[Avanzado] Escribe registros detallados en uno o varios archivos del directorio especificado, con nombres generados que incluyen marcas de tiempo y el nombre del subcomando en ejecución.

(Para escribir un archivo de registro con un nombre sobre el que tienes control total, proporciona --log-to-stderr y redirige stderr como quieras).

`--common-caches=<dir>`

[Avanzado] Controla la ubicación de los datos en caché del disco que se conservarán entre varias ejecuciones de la CLI, como paquetes QL descargados y planes de consulta compilada. Si no se define explícitamente, se toma como predeterminado un directorio denominado .codeql en el directorio principal del usuario, que se creará en caso de que no exista.

Disponible desde la versión v2.15.2.

¿Quién puede utilizar esta característica?

En este artículo