database upgrade

Synopsis

codeql database upgrade [--threads=<num>] [--ram=<MB>] <options>... -- <database>

codeql database upgrade [--threads=<num>] [--ram=<MB>] <options>... -- <database>

Description

Met à niveau une base de données pour qu’elle soit utilisable par les outils actuels.

Cette opération réécrit une base de données CodeQL pour qu’elle soit compatible avec les bibliothèques QL qui se trouvent sur le chemin de recherche du pack QL, si nécessaire.

Si une mise à niveau est nécessaire, elle est irréversible. La base de données sera par la suite inutilisable avec les bibliothèques qui étaient à jour lors de sa création.

Options

Options principales

<database>

[Obligatoire] Chemin vers la base de données CodeQL à mettre à niveau.

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

Liste des répertoires dans lesquels des packs QL contenant des recettes de mise à niveau peuvent être trouvés. Chaque répertoire peut être un pack QL (ou un bundle de packs contenant un fichier .codeqlmanifest.json à la racine) ou le parent immédiat d’un ou plusieurs de ces répertoires.

Si le chemin contient des arborescences de répertoires, leur ordre définit la priorité entre elles : si un nom de pack qui doit être résolu est mis en correspondance dans plusieurs arborescences de répertoires, celle donnée en premier gagne.

Le pointage de ce chemin vers une extraction du dépôt CodeQL open source devrait fonctionner lors de l’interrogation d’un des langages qui y résident.

(Remarque : Sur Windows, le séparateur de chemin est ;.)

--additional-packs=<dir>[:<dir>...]

[Avancé] Si cette liste de répertoires est donnée, ils font l’objet d’une recherche de mises à niveau avant ceux indiqués dans --search-path. L’ordre entre eux n’a pas d’importance ; il s’agit d’une erreur si un nom de pack est trouvé dans deux répertoires différents de cette liste.

Cette option est utile si vous développez temporairement une nouvelle version d’un pack qui apparaît aussi dans le chemin par défaut. En revanche, il n’est pas recommandé de remplacer cette option dans un fichier de configuration ; certaines actions internes ajoutent cette option à la volée, remplaçant toute valeur configurée.

(Remarque : Sur Windows, le séparateur de chemin est ;.)

--target-dbscheme=<file>

Schéma de base de données cible vers lequel nous voulons effectuer la mise à niveau. S’il n’est pas fourni, un chemin de mise à niveau maximal est construit

--target-sha=<sha>

[Avancé] Alternative à --target-dbscheme qui donne le hachage interne du schéma de base de données cible au lieu du fichier du schéma de base de données.

--[no-]allow-downgrades

Inclut tous les passages à une version antérieure pertinents s’il n’y a aucune mise à niveau

Options pour contrôler l’évaluation des requêtes de mise à niveau

--[no-]tuple-counting

[Avancé] Affiche le nombre de tuples pour chaque étape d’évaluation dans les journaux de l’évaluateur de requête. Si l’option --evaluator-log est fournie, les nombres de tuples sont inclus dans les journaux JSON textuels et structurés générés par la commande. (Cela peut être utile pour l’optimisation des performances du code QL complexe.)

--timeout=<seconds>

[Avancé] Définit la durée du délai d’expiration pour l’évaluation de la requête, en secondes.

La fonctionnalité de délai d’expiration est destinée à intercepter les cas où l’évaluation d’une requête complexe durerait « indéfiniment ». Il ne s’agit pas d’un moyen efficace de limiter la durée totale de l’évaluation de la requête. L’évaluation est autorisée à se poursuivre tant que chaque partie du calcul se termine dans le délai d’expiration qui lui a été imparti séparément. Pour l’instant, ces parties sont des « couches RA » de la requête optimisée, mais cela peut changer.

Si aucun délai d’expiration n’est spécifié ou que 0 est fourni, aucun délai n’est défini (sauf pour codeql test run, où le délai d’expiration par défaut est de 5 minutes).

-j, --threads=<num>

Utilise le nombre de threads spécifié pour évaluer les requêtes.

La valeur par défaut est de 1. Vous pouvez passer 0 pour utiliser un thread par cœur sur la machine ou -N pour laisser N cœurs inutilisés (sauf si au moins un thread est toujours utilisé).

--[no-]save-cache

[Avancé] Écrit de manière agressive des résultats intermédiaires dans le cache de disque. Cela prend plus de temps et utilise (beaucoup) plus d’espace disque, mais peut accélérer l’exécution ultérieure de requêtes similaires.

--[no-]expect-discarded-cache

[Avancé] Prend des décisions sur les prédicats à évaluer et sur ce qu’il faut écrire dans le cache de disque, en supposant que le cache soit ignoré une fois les requêtes exécutées.

--[no-]keep-full-cache

[Avancé] Ne nettoie pas le cache de disque une fois l’évaluation terminée. Cela peut faire gagner du temps si vous êtes amené à exécuter codeql dataset cleanup ou codeql database cleanup par la suite.

--max-disk-cache=<MB>

Définit la quantité maximale d’espace que le cache de disque peut utiliser pour les résultats de requête intermédiaires.

Si cette taille n’est pas configurée explicitement, l’évaluateur essaie d’utiliser une quantité « raisonnable » d’espace de cache en fonction de la taille du jeu de données et de la complexité des requêtes. La définition explicite d’une limite supérieure à cette utilisation par défaut permet une mise en cache supplémentaire qui peut accélérer les requêtes ultérieures.

--min-disk-free=<MB>

[Avancé] Définit la quantité cible d’espace disponible sur le système de fichiers.

Si --max-disk-cache n’est pas donné, l’évaluateur s’efforce de limiter l’utilisation du cache de disque si l’espace disponible sur le système de fichiers passe en dessous de cette valeur.

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

[Avancé] Définit la fraction cible d’espace disponible sur le système de fichiers.

Si --max-disk-cache n’est pas donné, l’évaluateur s’efforce de limiter l’utilisation du cache de disque si l’espace disponible sur le système de fichiers passe en dessous de ce pourcentage.

--external=<pred>=<file.csv>

Fichier CSV qui contient des lignes pour le prédicat <pred> externe. Vous pouvez fournir plusieurs options --external.

--xterm-progress=<mode>

[Avancé] Contrôle s’il faut afficher le suivi de la progression pendant l’évaluation du code QL avec des séquences de contrôle xterm. Les valeurs possibles sont les suivantes :

no : ne produit jamais de progression fantaisiste ; suppose qu’il s’agit d’un terminal idiot.

auto (par défaut)  : détermine automatiquement si la commande s’exécute dans un terminal approprié.

yes : suppose que le terminal peut comprendre les séquences de contrôle xterm. La fonctionnalité dépend toujours de la possibilité de détecter automatiquement la taille du terminal et est également désactivée si -q est donné.

25x80 (ou similaire) : comme yes, et donne aussi explicitement la taille du terminal.

25x80:/dev/pts/17 (ou similaire) : affiche une progression fantaisiste sur un terminal différent de stderr. Principalement utile pour les tests internes.

Options pour contrôler la sortie des journaux structurés de l’évaluateur

--evaluator-log=<file>

[Avancé] Génère des journaux structurés sur les performances de l’évaluateur dans le fichier donné. Le format de ce fichier journal est susceptible d’être modifié sans préavis, mais il s’agit d’un flux d’objets JSON séparés par deux caractères de nouvelle ligne (par défaut) ou un seul si l’option --evaluator-log-minify est transmise. Utilisez codeql generate log-summary <file> pour produire un résumé plus stable de ce fichier et évitez d’analyser le fichier directement. Le fichier est remplacé, s’il existe déjà.

--evaluator-log-minify

[Avancé] Si l’option --evaluator-log est transmise, le passage de cette option réduit également la taille du journal JSON produit, mais celui-ci devient beaucoup moins lisible par les êtres humains en contrepartie.

Options pour contrôler l’utilisation de la RAM du processus de mise à niveau

-M, --ram=<MB>

L'évaluateur de requêtes s'efforcera de maintenir son empreinte mémoire totale en dessous de cette valeur. (Toutefois, pour les grandes bases de données, il est possible que le seuil soit dépassé par les cartes mémoire sauvegardées sur fichier, qui peuvent être basculées sur disque en cas de sollicitation de la mémoire).

La valeur doit être d'au moins 2048 Mo ; les valeurs inférieures seront arrondies de manière transparente.

Options courantes

-h, --help

Affiche ce texte d’aide.

-J=<opt>

[Avancé] Donne une option à l’environnement JVM exécutant la commande.

(Attention, les options contenant des espaces ne sont pas gérées correctement.)

-v, --verbose

Augmente de façon incrémentielle le nombre de messages de progression affichés.

-q, --quiet

Diminue de façon incrémentielle le nombre de messages de progression affichés.

--verbosity=<level>

[Avancé] Définit explicitement le niveau de détail sur errors, warnings, progress, progress+, progress++ ou progress+++. Remplace -v et -q.

--logdir=<dir>

[Avancé] Écrit des journaux détaillés dans un ou plusieurs fichiers du répertoire donné, avec des noms générés qui incluent des horodatages et le nom de la sous-commande en cours d’exécution.

(Pour écrire un fichier journal avec un nom sur lequel vous avez un contrôle total, donnez plutôt --log-to-stderr et redirigez stderr comme vous le souhaitez.)

--common-caches=<dir>

[Avancé] Contrôle l’emplacement des données en cache sur le disque qui persisteront entre plusieurs exécutions de l’interface CLI, telles que les packs QL téléchargés et les plans de requête compilés. S’il n’est pas défini explicitement, il s’agit par défaut d’un répertoire nommé .codeql dans le répertoire de base de l’utilisateur. S’il n’existe pas déjà, il est créé.

Disponible depuis v2.15.2.