Datenbankupgrade

Hinweis

In diesem Inhalt wird die neueste Version von CodeQL CLI beschrieben. Weitere Informationen zu diesem Thema findest du unter http://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 database upgrade [--threads=<num>] [--ram=<MB>] <options>... -- <database>

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

Description

Führe ein Upgrade für eine Datenbank durch, damit sie von den aktuellen Tools verwendet werden kann.

Dadurch wird eine CodeQL-Datenbank bei Bedarf erneut generiert, sodass sie mit den QL-Bibliotheken kompatibel ist, die sich am QL-Paketsuchpfad befinden.

Wenn ein Upgrade erforderlich ist, kann es nicht rückgängig gemacht werden. Die Datenbank kann anschließend nicht mehr mit den Bibliotheken verwendet werden, die bei der Erstellung aktuell waren.

Options

Primäre Optionen

`<database>`

          \[Erforderlich] Pfad zur CodeQL-Datenbank für das Upgrade.

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

Eine Liste mit Verzeichnissen, unter denen QL-Pakete mit Upgraderezepten zu finden sind. 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 Verzeichnisstrukturen enthält, definiert deren Reihenfolge die Rangfolge zwischen ihnen: Ist ein Paketname, der aufgelöst werden muss, in mehreren der Verzeichnisstrukturen vorhanden, 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.

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

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

          \[Erweitert] Wenn diese Liste von Verzeichnissen angegeben wird, werden diese vor den Verzeichnissen in `--search-path` nach Upgrades 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 zu überschreiben. Einige interne Aktionen fügen diese Option direkt hinzu, wodurch alle konfigurierten Werte überschrieben werden.

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

`--target-dbscheme=<file>`

Das _Ziel_datenbankschema für das Upgrade. Ohne diese Angabe wird ein maximaler Upgradepfad erstellt.

`--target-sha=<sha>`

          \[Erweitert] Eine Alternative zu `--target-dbscheme`, die den internen Hash des Ziel-Dbschemas anstelle der Dbschemadatei angibt.

`--[no-]allow-downgrades`

Schließe alle relevanten Downgrades ein, wenn keine Upgrades vorhanden sind.

Optionen zum Steuern der Auswertung von Upgradeabfragen

`--[no-]tuple-counting`

          \[Erweitert] Anzeige der Tupelzahlen für jeden Evaluierungsschritt in den Abfrage-Evaluator-Protokollen. 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 Steuern der RAM-Nutzung des Upgradeprozesses

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

Die Abfrageauswertung bemüht sich, ihren Gesamtspeicherbedarf unter diesem Wert zu halten. (Bei großen Datenbanken kann es jedoch vorkommen, dass der Schwellenwert durch dateigesicherte Speicherzuordnungen überschritten wird, die bei Speicherauslastung auf einen Datenträger ausgelagert werden können).

Der Wert sollte mindestens 2048 MB betragen; kleinere Werte werden transparent aufgerundet.

          \[Erweitert] Option an die JVM übergeben, die den Befehl ausführt.

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

          \[Erweitert] Lege die Ausführlichkeitsstufe explizit auf einen der Werte errors, warnings, progress, progress+, progress++, progress+++ 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, die zwischen mehreren CLI-Ausführungen bestehen bleiben, wie z. B. heruntergeladene QL-Pakete und kompilierte Abfragepläne. 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