Ausführen von Upgrades

Hinweis

In diesem Inhalt wird die neueste Version von CodeQL CLI beschrieben. Weitere Informationen zu diesem Thema findest du unter https://github.com/github/codeql-cli-binaries/releases.

Um Details zu den Optionen anzuzeigen, die für diesen Befehl in früheren Releases verfügbar sind, führe den Befehl mit der Option --help im Terminal aus.

Zusammenfassung

Shell

codeql execute upgrades [--threads=<num>] <options>... -- <dataset> <script>...

codeql execute upgrades [--threads=<num>] <options>... -- <dataset> <script>...

Description

          \[Plumbing] Upgrade-Skripte für ein bestehendes Raw QL Dataset ausführen.

Dieser Befehl führt eine bestimmte Sequenz von Upgradeskripts für das Dataset aus. Es liegt in der Verantwortung der Aufrufer*innen, dass das „alte“ Datenbankschema jedes Upgradeskripts mit dem „neuen“ Datenbankschema des vorherigen Skripts (oder, für das erste Skript, dem aktuellen Datenbankschema des Datasets) übereinstimmt. Andernfalls wird ein Fehler ausgelöst.

Options

Primäre Optionen

`<dataset>`

          \[Erforderlich] Pfad zu dem Raw-QL Dataset, das aktualisiert werden soll.

`<script>...`

          \[Erforderlich] Pfade zu den auszuführenden Upgrade-Skripten. (Jedes Upgradeskript ist ein Verzeichnis mit mehreren Dateien, die einen Upgradevorgang definieren.) Sie müssen in der Reihenfolge angegeben werden, in der sie anzuwenden sind.

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

Eine Liste der Verzeichnisse, in denen QL-Pakete gefunden werden können. Jedes Verzeichnis kann entweder ein QL-Paket (oder ein Bündel von Paketen mit einer Datei vom Typ .codeqlmanifest.json am Stamm) oder das unmittelbar übergeordnete Element eines oder mehrerer solcher Verzeichnisse sein.

Wenn der Pfad mehrere Verzeichnisse enthält, definiert deren Reihenfolge ihre Rangfolge: Ist ein Paketname, der aufgelöst werden muss, in mehreren der Verzeichnisstrukturen enthalten, wird die erste Angabe verwendet.

Ein entsprechender Verweis beim Auschecken des Open-Source-CodeQL-Repositorys sollte funktionieren, wenn eine der darin enthaltenen Sprachen abgefragt wird.

Wenn du das CodeQL-Repository als gleichgeordnetes Element der entpackten CodeQL-Toolkette ausgecheckt hast, musst du diese Option nicht verwenden. Solche gleichgeordneten Verzeichnisse werden immer nach QL-Paketen durchsucht, die andernfalls nicht gefunden werden können. (Wenn diese Standardeinstellung nicht funktioniert, solltest du unbedingt --search-path in einer Benutzerkonfigurationsdatei festlegen.)

(Hinweis: Unter Windows wird ; als Pfadtrennzeichen verwendet.)

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

Bei Angabe dieser Verzeichnisliste werden die Verzeichnisse vor den Verzeichnissen in --search-path nach Paketen durchsucht. Die Reihenfolge zwischen diesen Elementen spielt keine Rolle. Wenn ein Paketname über diese Liste an zwei verschiedenen Stellen gefunden wird, handelt es sich um einen Fehler.

Dies ist hilfreich, wenn du vorübergehend eine neue Version eines Pakets entwickelst, die auch am Standardpfad vorhanden ist. Andererseits wird davon abgeraten, diese Option in einer Konfigurationsdatei außer Kraft zu setzen. Einige interne Aktionen fügen diese Option direkt hinzu, wodurch alle konfigurierten Werte überschrieben werden.

(Hinweis: Unter Windows wird ; als Pfadtrennzeichen verwendet.)

Optionen zum Steuern der Auswertung von Upgradeabfragen

`--[no-]tuple-counting`

          \[Erweitert] Anzeige der Tupelzahlen für jeden Evaluierungsschritt in den Abfrage-Evaluierungsprotokollen. Bei Angabe der Option `--evaluator-log` wird die Tupelanzahl sowohl in die textbasierten als auch in die strukturierten JSON-Protokolle eingeschlossen, die durch den Befehl erstellt werden. (Dies kann bei der Optimierung der Leistung von komplexem QL-Code hilfreich sein.)

`--timeout=<seconds>`

          \[Erweitert] Die Timeout-Länge für die Evaluierung von Abfragen in Sekunden festlegen.

Das Timeoutfeature ist für Fälle vorgesehen, in denen die Auswertung einer komplexen Abfrage zu lange dauern würde. Es ist keine effektive Methode zur Begrenzung der Gesamtdauer der Abfrageauswertung. Die Auswertung kann fortgesetzt werden, solange jeder Teil der Berechnung, für den eine separate Zeiterfassung erfolgt, innerhalb des Timeouts abgeschlossen wird. Derzeit sind diese Teile mit separater Zeiterfassung „RA-Ebenen“ der optimierten Abfrage. Dies kann sich aber noch ändern.

Ohne Timeoutangabe oder bei Angabe eines Nullwerts wird kein Timeout festgelegt. (Einzige Ausnahme ist codeql test run: Hier gilt ein Standardtimeout von fünf Minuten.)

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

Dient zum Festlegen, wie viele Threads für die Abfrageauswertung verwendet werden sollen.

Der Standardwert lautet 1. Du kannst 0 übergeben, um jeweils einen Thread pro Kern auf dem Computer zu verwenden, oder -N, um N Kerne ungenutzt zu lassen. (Es wird allerdings immer noch mindestens ein Thread verwendet.)

`--[no-]save-cache`

          \[Abgeschafft] \[Erweitert] Dieses Flag hat keine Funktion.

`--[no-]expect-discarded-cache`

          \[Erweitert] Entscheide, welche Prädikate evaluiert und was in den Datenträger-Cache geschrieben werden soll, unter der Annahme, dass der Cache nach der Ausführung der Abfragen verworfen wird.

`--[no-]keep-full-cache`

          \[Erweitert] Lösche den Datenträger-Cache nicht, nachdem die Evaluierung abgeschlossen ist.

Das kann Zeit sparen, wenn du später ohnehin codeql dataset cleanup oder codeql database cleanup verwendest.

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

Dient zum Festlegen des maximalen Speicherplatzes, der vom Datenträgercache für Zwischenergebnisse von Abfragen beansprucht werden darf.

Wird diese Größe nicht explizit konfiguriert, versucht der Auswerter, basierend auf der Größe des Datasets und der Komplexität der Abfragen eine angemessene Menge an Cachespeicherplatz zu verwenden. Durch explizites Festlegen eines höheren Grenzwerts (im Vergleich zur Standardnutzung) können mehr Daten zwischengespeichert werden, was spätere Abfragen beschleunigen kann.

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

          \[Erweitert] Zielmenge für freien Speicherplatz im Dateisystem festlegen.

Ohne Angabe von --max-disk-cache versucht der Auswerter nach Möglichkeit, die Nutzung des Datenträgercaches einzuschränken, wenn der freie Speicherplatz im Dateisystem diesen Wert unterschreitet.

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

          \[Erweitert] Zielanteil des freigegebenen Speicherplatzes im Dateisystem festlegen.

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

Eine CSV-Datei, die Zeilen für das externe Prädikat <pred> enthält. Für --external können mehrere Optionen angegeben werden.

`--xterm-progress=<mode>`

          \[Erweitert] Steuert, ob die Fortschrittsverfolgung während der LQ-Evaluierung mit xterm-Steuersequenzen angezeigt werden soll. Mögliche Werte:

          `no`: Niemals eine Fortschrittsanzeige erzeugen; gehe von einem stummen Terminal aus.

          `auto`              _(Standard)_: Automatische Erkennung, ob der Befehl in einem geeigneten Terminal ausgeführt wird.

          `yes`: Gehe davon aus, dass das Terminal die Steuersequenzen von xterm verstehen kann. Das Feature hängt weiterhin davon ab, dass die _Größe_ des Terminals (unter Windows nicht implementiert) automatisch ermittelt werden kann. Es wird ebenfalls deaktiviert, wenn `-q` angegeben wird.

          `25x80` (oder ähnlich): Wie `yes`, und zusätzlich die Größe des Terminals explizit angeben. (Im Gegensatz zu `yes` sollte das unter Windows funktionieren.)

          `25x80:/dev/pts/17` (oder ähnlich): zeige einen schicken Fortschritt auf einem _anderen_ Terminal als stderr. In erste Linie für interne Tests nützlich.

Optionen zum Steuern der Ausgabe strukturierter Auswertungsprotokolle

`--evaluator-log=<file>`

          \[Erweitert] Strukturierte Protokolle über die Leistung der Evaluierung in die angegebene Datei ausgeben. Das Format dieser Protokolldatei kann ohne vorherige Ankündigung geändert werden. Es handelt sich jedoch um einen Datenstrom von JSON-Objekten, die entweder durch zwei Neue-Zeile-Zeichen (standardmäßig) getrennt werden – oder durch ein einzelnes, wenn die Option `--evaluator-log-minify` übergeben wird. Verwende `codeql generate log-summary <file>`, um eine stabilere Zusammenfassung dieser Datei zu erstellen, und vermeide eine direkte Analyse der Datei. Die Datei wird überschrieben, wenn sie bereits vorhanden ist.

`--evaluator-log-minify`

          \[Erweitert] Wenn die Option `--evaluator-log` übergeben wird, wird durch die Übergabe dieser Option die Größe des erzeugten JSON-Protokolls minimiert, allerdings auf Kosten der Lesbarkeit.

Optionen zum Konfigurieren des CodeQL-Paket-Managers

`--registries-auth-stdin`

Führt eine Authentifizierung bei GitHub Enterprise Server-Containerregistrierungen durch, indem eine durch Trennzeichen getrennte Liste von <registry_url>=<token>-Paaren übergeben wird.

Du kannst https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2 übergeben, um dich bei zwei GitHub Enterprise Server-Instanzen zu authentifizieren.

Dadurch werden die Umgebungsvariablen CODEQL_REGISTRIES_AUTH und GITHUB_TOKEN überschrieben. Wenn du dich nur bei der Containerregistrierung von github.com authentifizieren musst, kannst du dich stattdessen mit der einfacheren Option --github-auth-stdin authentifizieren.

`--github-auth-stdin`

Authentifiziere dich bei der Containerregistrierung auf github.com, indem du auf github.com ein GitHub Apps-Token oder ein persönliches Zugriffstoken über die Standardeingabe übergibst.

Für die Authentifizierung bei Containerregistrierungen in GitHub Enterprise Server übergibst du --registries-auth-stdin oder verwendest die Umgebungsvariable „CODEQL_REGISTRIES_AUTH“.

Dadurch wird die GITHUB_TOKEN-Umgebungsvariable überschrieben.

          \[Erweitert] Gib der JVM, die den Befehl ausführt, eine Option.

(Beachte, dass Optionen, die Leerzeichen enthalten, nicht ordnungsgemäß verarbeitet werden.)

          \[Erweitert] Lege die Ausführlichkeitsstufe explizit auf einen der Werte Fehler, Warnungen, Fortschritt, Fortschritt+, Fortschritt++, Fortschritt+++ fest. Überschreibt `-v` und `-q`:

`--logdir=<dir>`

          \[Erweitert] Detaillierte Protokolle in eine oder mehrere Dateien im angegebenen Verzeichnis schreiben, mit generierten Namen, die Zeitstempel und den Namen des ausgeführten Unterbefehls enthalten.

(Um eine Protokolldatei mit einem Namen zu schreiben, über den du die volle Kontrolle hast, gib stattdessen --log-to-stderr an, und leite stderr wie gewünscht um.)

`--common-caches=<dir>`

          \[Erweitert] Steuert den Zwischenspeicherort von Datenträgern wie z. B. heruntergeladene LQ-Pakete und kompilierte Abfragepläne, die zwischen mehreren Ausführen des CLI erhalten bleiben sollen. Wenn dies nicht explizit festgelegt ist, wird dieses Verzeichnis standardmäßig auf ein Verzeichnis mit dem Namen `.codeql` festgelegt, das sich im Startverzeichnis des Benutzer. Es wird erstellt, wenn es noch nicht vorhanden ist.

Verfügbar seit v2.15.2.

Wer kann dieses Feature verwenden?

In diesem Artikel