Freigeben über

Befehle im sqlcmd-Hilfsprogramm

Gilt für:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsAnalytics Platform System (PDW)SQL-Datenbank in Microsoft Fabric

Mit dem sqlcmd-Hilfsprogramm können Sie Transact-SQL Anweisungen, Systemprozeduren und Skriptdateien eingeben.

Note

Informationen dazu, welche Variante und Version von sqlcmd auf Ihrem System installiert ist, finden Sie unter Überprüfen der installierten Version des sqlcmd-Hilfsprogramms. Informationen zum Abrufen von sqlcmd finden Sie unter Herunterladen und Installieren des sqlcmd-Hilfsprogramms.

Zusätzlich zu den Transact-SQL-Anweisungen in sqlcmd sind auch die folgenden Befehle verfügbar:

  • GO [ <count> ]
  • :List
  • [:]RESET
  • :Error
  • [:]ED 1
  • :Out
  • [:]!!
  • :Perftrace
  • [:]QUIT
  • :Connect
  • [:]EXIT
  • :On Error
  • :r
  • :Help
  • :ServerList 1
  • :XML [ ON | OFF ] 1
  • :Setvar
  • :Listvar

1 Nicht unterstützt unter Linux oder macOS.

Beachten Sie bei der Verwendung von sqlcmd -Befehlen Folgendes:

  • Alle sqlcmd-Befehle, außer GO, müssen mit einem Doppelpunkt (:) vorangestellt werden.

    Important

    Um die Abwärtskompatibilität mit vorhandenen osql--Skripts aufrechtzuerhalten, werden einige der Befehle ohne den Doppelpunkt erkannt, der durch die :angegeben wird.

  • sqlcmd -Befehle werden nur erkannt, wenn sie am Anfang einer Zeile stehen.

  • Bei keinem sqlcmd-Befehl wird die Groß- und Kleinschreibung beachtet.

  • Jeder Befehl muss in einer eigenen Zeile stehen. Auf einen Befehl darf keine Transact-SQL-Anweisung oder ein anderer Befehl folgen.

  • Die Befehle werden sofort ausgeführt. Sie werden nicht wie Transact-SQL-Anweisungen im Ausführungspuffer abgelegt.

Bearbeitungsbefehle

[:]ED

Startet den Text-Editor. Mit diesem Editor kann der aktuelle Transact-SQL-Batch oder der zuletzt ausgeführte Batch bearbeitet werden. Um den zuletzt ausgeführten Batch zu bearbeiten, muss der ED -Befehl unmittelbar nach Abschluss der Ausführung des letzten Batches eingegeben werden.

Der Text-Editor wird durch die Umgebungsvariable SQLCMDEDITOR definiert. Der Standardeditor ist Edit. Legen Sie die Umgebungsvariable SQLCMDEDITOR fest, um den Editor zu ändern. Wenn Sie beispielsweise Microsoft Notepad als Editor festlegen möchten, geben Sie Folgendes an der Eingabeaufforderung ein:

SET SQLCMDEDITOR=notepad

[:]RESET

Löscht den Anweisungscache

:List

Gibt den Inhalt des Anweisungscaches aus

Variables

:Setvar <var> [ "value" ]

Definiert sqlcmd -Skriptvariablen. Skriptvariablen haben das folgende Format: $(VARNAME).

Bei Variablennamen wird die Groß- und Kleinschreibung nicht beachtet.

Skriptvariablen können folgendermaßen festgelegt werden:

  • Implizit eine Befehlszeilenoption verwenden. Die Option -l legt beispielsweise die SQLCMDLOGINTIMEOUT-Variable fest.
  • Explizit – mithilfe des :Setvar -Befehls.
  • Definieren einer Umgebungsvariable, bevor Sie sqlcmd ausführen.

Note

Die Option -X verhindert, dass Umgebungsvariablen an sqlcmdübergeben werden.

Wenn eine Variable, die mithilfe von :Setvar definiert wurde, denselben Namen wie eine Umgebungsvariable aufweist, ist die mit :Setvar definierte Variable vorrangig.

Variablennamen dürfen keine Leerzeichen enthalten.

Variablennamen können nicht dieselbe Form wie ein Variablenausdruck (z. B. $(var)) aufweisen.

Wenn der Zeichenfolgenwert der Skriptvariablen Leerzeichen enthält, müssen Sie den Wert in Anführungszeichen einschließen. Wenn für eine Skriptvariable kein Wert angegeben wird, wird die Skriptvariable ausgelassen.

:Listvar

Zeigt die Liste der zurzeit festgelegten Skriptvariablen an.

Note

Nur Skriptingvariablen, die von sqlcmd festgelegt werden, und Variablen, die mit dem :Setvar Befehl festgelegt werden, werden angezeigt.

Ausgabebefehle

:Error <Dateiname> | STDERR | STDOUT

Alle Fehlerausgaben werden an die durch filename angegebene Datei, an stderr oder an stdout umgeleitet. Der :Error-Befehl kann mehrmals in einem Skript verwendet werden. Die Fehlerausgabe wird standardmäßig an stderr gesendet.

  • filename

    Erstellt eine Datei, in die die Ausgabe geschrieben wird, und öffnet sie. Wenn die Datei bereits vorhanden ist, wird sie auf 0 Byte gekürzt. Wenn der Zugriff auf die Datei aufgrund unzureichender Berechtigungen oder anderer Ursachen nicht möglich ist, wird die Ausgabe nicht umgeleitet, sondern an das zuletzt angegebene Ziel oder an das Standardziel gesendet.

  • STDERR

    Leitet die Fehlerausgabe in den stderr-Stream um. Wenn die Ausgabe umgeleitet wurde, erhält das Ziel, an das der Datenstrom umgeleitet wird, die Fehlerausgabe.

  • STDOUT

    Leitet die Fehlerausgabe in den stdout-Stream um. Wenn die Ausgabe umgeleitet wurde, erhält das Ziel, an das der Datenstrom umgeleitet wird, die Fehlerausgabe.

:Out <Dateiname> | STDERR | STDOUT

Erstellt und leitet alle Abfrageergebnisse auf die durch Dateiname angegebene Datei, nach stderr oder nach stdout um. Standardmäßig wird die Ausgabe an stdout gesendet. Wenn die Datei bereits vorhanden ist, wird sie auf 0 Byte gekürzt. Der :Out-Befehl kann mehrmals in einem Skript verwendet werden.

:c0 />< :Perftrace | STDERR | STDOUT

Erstellt und leitet alle Informationen zur Leistungsnachverfolgung in der bzw. an die durch filename angegebene Datei, an stderr oder an stdout um. Standardmäßig wird die Ausgabe zur Leistungsnachverfolgung an stdout gesendet. Wenn die Datei bereits vorhanden ist, wird sie auf 0 Byte gekürzt. Der :Perftrace-Befehl kann mehrmals in einem Skript verwendet werden.

Befehle zur Ausführungssteuerung

:On Error [ beenden | ignorieren ]

Legt die Aktion fest, die ausgeführt werden soll, wenn ein Fehler während der Skript- oder Batchausführung auftritt.

Wird die exit-Option verwendet, wird sqlcmd mit dem entsprechenden Fehlerwert beendet.

Wenn die ignore-Option verwendet wird, ignoriert sqlcmd den Fehler und setzt die Batch- oder Skriptausführung fort. Standardmäßig wird eine Fehlermeldung ausgegeben.

[:]QUIT

Bewirkt, dass sqlcmd beendet wird.

[:]EXIT [ ( Anweisung ) ]

Diese Option gibt Ihnen die Möglichkeit, das Ergebnis einer SELECT-Anweisung als Rückgabewert von sqlcmd zu verwenden. Wenn numerisch, wird die erste Spalte der letzten Ergebniszeile in eine 4 Byte lange ganze Zahl (Long) konvertiert. MS-DOS, Linux und macOS übergeben das niedrige Byte an den übergeordneten Prozess oder an die Fehlerebene des Betriebssystems. Windows 2000 und spätere Versionen übergeben den gesamten 4-Byte-Integer. Die Syntax ist :EXIT(query).

Beispiel:

:EXIT(SELECT @@ROWCOUNT)

Sie können den :EXIT-Parameter auch als Teil einer Batchdatei einschließen. Geben Sie an der Eingabeaufforderung z. B. Folgendes ein:

sqlcmd -Q ":EXIT(SELECT COUNT(*) FROM '%1')"

Das Hilfsprogramm sqlcmd sendet alle zwischen den Klammern (()) stehende Angaben an den Server. Wenn eine gespeicherte Systemprozedur eine Menge auswählt und einen Wert zurückgibt, wird nur die Auswahl zurückgegeben. Die :EXIT()-Anweisung ohne Inhalt zwischen den Klammern führt alle vorhergehenden Anweisungen im Batch aus und endet dann ohne Rückgabewert.

Wird eine fehlerhafte Abfrage angegeben, wird sqlcmd beendet, ohne dass ein Wert zurückgegeben wird.

Hier ist eine Liste mit EXIT Formaten:

  • :EXIT

    Führt den Batch nicht aus, beendet das Programm sofort und gibt keinen Wert zurück.

  • :EXIT( )

    Führt die Batch-Datei aus und beendet die Ausführung, ohne einen Wert zurückzugeben.

  • :EXIT(query)

    Führt das Batch mit der darin enthaltenen Abfrage aus und beendet dann das Programm, nachdem die Ergebnisse der Abfrage zurückgegeben wurden.

Wird RAISERROR in einem sqlcmd-Skript verwendet und der Status 127 ausgelöst, wird sqlcmd beendet und die entsprechende Meldungs-ID an den Client zurückgegeben. Beispiel:

RAISERROR(50001, 10, 127)

Dieser Fehler bewirkt, dass das sqlcmd-Skript beendet und die Meldungs-ID 50001 an den Client zurückgegeben wird.

Die Rückgabewerte -1 bis -99 sind für SQL Server reserviert. sqlcmd definiert die folgenden zusätzlichen Rückgabewerte:

Rückgabewert Description
-100 Fehler beim Auswählen des Rückgabewerts.
-101 Beim Auswählen eines Rückgabewerts wurden keine Zeilen gefunden.
-102 Beim Auswählen des Rückgabewerts ist ein Konvertierungsfehler aufgetreten.

GO [anzahl]

GO signalisiert sowohl das Ende eines Batches als auch die Ausführung aller zwischengespeicherten Transact-SQL-Anweisungen. Das Batch wird mehrmals als separate Batches ausgeführt. Sie können eine Variable in einem einzelnen Batch nicht mehr als einmal deklarieren.

Verschiedene Befehle

:r <Dateiname>

Analysiert zusätzliche Transact-SQL-Anweisungen und sqlcmd-Befehle aus der durch Dateiname angegebenen Datei und schreibt das Ergebnis in den Anweisungscache. Dateiname wird relativ zum Startverzeichnis gelesen, in dem sqlcmd ausgeführt wurde.

Wenn die Datei Transact-SQL-Anweisungen enthält, auf die nicht GO folgt, müssen Sie GO in der ersten Zeile nach :r eingeben.

Die Datei wird gelesen und ausgeführt, nachdem ein Batchabschlusszeichen gefunden wurde. Sie können den :r-Befehl mehrmals verwenden. Die Datei kann jeden sqlcmd-Befehl enthalten, einschließlich des Batch-Beendigungszeichens GO.

Note

Die Zeilenanzahl, die im interaktiven Modus angezeigt wird, wird bei jedem :r aufgetretenen Befehl um einen erhöht. Der Befehl :r wird in der Ausgabe des Listenbefehls angezeigt.

:ServerList

Listet die lokal konfigurierten Server sowie die Namen der Server auf, die im Netzwerk senden.

:Connect server_name[\instance_name] [-l timeout] [-U user_name [-P password]]

Stellt eine Verbindung mit einer Instanz von SQL Server her. Schließt außerdem die aktuelle Verbindung.

Timeoutoptionen:

Value Behavior
0 Wartet ewig
n>0 Wartezeit beträgt n Sekunden

Die Skriptvariable SQLCMDSERVER spiegelt die zurzeit aktive Verbindung wider.

Wenn timeout nicht angegeben wird, gilt standardmäßig der Wert der SQLCMDLOGINTIMEOUT-Variablen.

Wenn nur user_name angegeben wird (entweder als Option oder als Umgebungsvariable), werden die Benutzer*innen zur Eingabe eines Kennworts aufgefordert. Benutzer werden nicht benachrichtigt, wenn die SQLCMDUSER oder SQLCMDPASSWORD Umgebungsvariablen festgelegt sind. Wenn Sie weder Optionen noch Umgebungsvariablen angegeben, wird der Windows-Authentifizierungsmodus für die Anmeldung verwendet. Wenn z. B. mithilfe integrierter Sicherheit eine Verbindung mit einer Instanz, instance1, von SQL Server, myserver, hergestellt werden soll, geben Sie folgenden Befehl ein:

:connect myserver\instance1

Wenn mithilfe von Skriptvariablen eine Verbindung mit der Standardinstanz auf myserver hergestellt werden soll, würden Sie folgende Einstellungen verwenden:

:setvar myusername test
:setvar myservername myserver
:connect $(myservername) $(myusername)

[:]!! command

Führt Betriebssystembefehle aus. Um einen Betriebssystembefehl auszuführen, beginnen Sie eine Zeile mit zwei Ausrufezeichen ( !! ) gefolgt von dem Betriebssystembefehl. Beispiel:

:!! dir

Note

Der Befehl wird auf dem Computer ausgeführt, auf dem sqlcmd ausgeführt wird.

:XML [ EIN | AUS ]

Weitere Informationen finden Sie unter XML-Ausgabeformat und JSON-Ausgabeformat in diesem Artikel.

:Help

Hiermit werden die sqlcmd-Befehle zusammen mit einer kurzen Beschreibung jedes Befehls aufgelistet.

sqlcmd-Dateinamen

sqlcmd -Eingabedateien können mit der Option -i oder dem Befehl :r angegeben werden. Ausgabedateien können mit der -o Option oder den :Error, :Out und :Perftrace Befehlen angegeben werden. Es folgen einige Richtlinien für das Verwenden dieser Dateien:

  • :Error, :Outund :Perftrace sollten separate Dateinamenwerte verwenden. Wenn derselbe Dateinamen verwendet wird, können Eingaben aus den Befehlen gemischt werden.

  • Wenn eine Eingabedatei, die sich auf einem Remoteserver befindet, von sqlcmd auf einem lokalen Computer aufgerufen wird und die Datei einen Laufwerksdateipfad wie :Out c:\OutputFile.txt enthält, wird die Ausgabedatei auf dem lokalen Computer und nicht auf dem Remoteserver erstellt.

  • Gültige Dateipfade sind beispielsweise: C:\<filename>, \\<Server>\<Share$>\<filename> und "C:\Some Folder\<file name>". Verwenden Sie Anführungszeichen, wenn der Pfad ein Leerzeichen enthält.

  • Mit jeder neuen sqlcmd-Sitzung werden eventuell schon vorhandene gleichnamige Dateien überschrieben.

Informationsmeldungen

sqlcmd gibt alle vom Server gesendeten Informationsmeldungen aus. Im folgenden Beispiel wird eine Informationsmeldung ausgegeben, nachdem die Transact-SQL-Anweisungen ausgeführt wurden.

Starten Sie sqlcmd. Geben Sie an der sqlcmd -Eingabeaufforderung folgende Abfrage ein:

USE AdventureWorks2022;
GO

Wenn Sie die EINGABETASTE drücken, wird folgende Informationsmeldung ausgegeben:

Changed database context to 'AdventureWorks2022'.

Ausgabeformat von Transact-SQL-Abfragen

sqlcmd gibt zuerst eine Spaltenüberschrift aus, die die in der SELECT-Liste angegebenen Spaltennamen enthält. Die Spaltennamen werden durch das SQLCMDCOLSEP-Zeichen getrennt. In der Regel ist dieses Spaltentrennzeichen ein Leerzeichen. Wenn der Spaltenname kürzer als die Spaltenbreite ist, wird die Ausgabe bis zur nächsten Spalte mit Leerzeichen aufgefüllt.

Auf diese Zeile folgt eine Trennlinie, die aus einer Reihe von Bindestrichen besteht. Die folgende Ausgabe zeigt ein Beispiel.

Starten Sie sqlcmd. Geben Sie an der sqlcmd -Eingabeaufforderung folgende Abfrage ein:

USE AdventureWorks2022;

SELECT TOP (2) BusinessEntityID,
               FirstName,
               LastName
FROM Person.Person;
GO

Wenn Sie die EINGABETASTE drücken, wird das folgende Resultset zurückgegeben.

BusinessEntityID FirstName    LastName
---------------- ------------ ----------
285              Syed         Abbas
293              Catherine    Abel
(2 row(s) affected)

Obwohl die BusinessEntityID Spalte nur vier Zeichen breit ist, wird sie erweitert, um den längeren Spaltennamen aufzunehmen. Standardmäßig wird die Ausgabe mit dem 80. Zeichen beendet. Diese Breite kann geändert werden, indem Sie die -w-Option verwenden oder die SQLCMDCOLWIDTH-Skriptvariable festlegen.

XML-Ausgabeformat

Die XML-Ausgabe, die sich aus der FOR XML-Klausel ergibt, wird unformatiert in einem fortlaufenden Datenstrom ausgegeben.

Verwenden Sie den Befehl :XML ON, wenn Sie eine Ausgabe im XML-Format erwarten.

Note

sqlcmd gibt Fehlermeldungen im üblichen Format zurück. Die Fehlermeldungen werden auch im XML-Textstrom im XML-Format ausgegeben. Mit :XML ON zeigt sqlcmd keine Informationsmeldungen an.

Verwenden Sie den folgenden Befehl, um den XML-Modus zu deaktivieren: :XML OFF.

Der GO-Befehl sollte nicht verwendet werden, bevor der :XML OFF-Befehl ausgegeben wurde, da :XML OFF bewirkt, dass sqlcmd zur zeilenbasierten Ausgabe zurückkehrt.

Es ist nicht möglich, XML-Daten (Datenstrom) und Rowsetdaten zu mischen. Wenn der :XML ON Befehl nicht vor einer Transact-SQL-Anweisung ausgeführt wurde, die XML-Datenströme ausgibt, ist die Ausgabe verzerrt. Nachdem der :XML ON Befehl ausgegeben wurde, können Sie keine Transact-SQL Anweisungen ausführen, die reguläre Zeilensätze ausgeben.

Note

Der Befehl :XML unterstützt die SET STATISTICS XML-Anweisung nicht.

JSON-Ausgabeformat

Verwenden Sie den Befehl :XML ON, wenn Sie eine Ausgabe im JSON-Format erwarten. Andernfalls enthält die Ausgabe sowohl den Spaltennamen als auch den JSON-Text. Diese Ausgabe ist kein gültiger JSON-Code.

Verwenden Sie den folgenden Befehl, um den XML-Modus zu deaktivieren: :XML OFF.

Weitere Informationen finden Sie unter XML-Ausgabeformat in diesem Artikel.

Verwenden Sie die Microsoft Entra-Authentifizierung

Beispiele, in denen die Microsoft Entra-Authentifizierung verwendet wird:

sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net  -G  -l 30
sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net -G -U bob@contoso.com -P MyAzureADPassword -l 30

sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net  -G  -l 30
sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net -G -U bob@contoso.com -P MyAzureADPassword -l 30

sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net  -G  -l 30
sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net -G -U bob@contoso.com -P MyAzureADPassword -l 30

Verwandte Inhalte

  • Last updated on