Befehle im sqlcmd-Hilfsprogramm

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

Das sqlcmd-Hilfsprogramm akzeptiert Transact-SQL Anweisungen, Systemprozeduren und Skriptdateien.

Verwenden Sie zusätzlich zu Transact-SQL Anweisungen in sqlcmd die folgenden Befehle:

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

¹ Nicht unterstützt unter Linux oder macOS.

Beachten Sie beim Verwenden von SQLcmd-Befehlen die folgenden Punkte:

• Alle sqlcmd-Befehle , mit Ausnahme GO, müssen mit einem Doppelpunkt (:) beginnen.

  Important

  Um die Abwärtskompatibilität mit vorhandenen osql-Skripts aufrechtzuerhalten, funktionieren einige Befehle ohne den Doppelpunkt (angegeben durch [:]).

• sqlcmd erkennt Befehle nur, wenn sie am Anfang einer Zeile angezeigt werden.

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

• Jeder Befehl muss in einer eigenen Zeile stehen. Sie können einem Befehl nicht mit einer Transact-SQL-Anweisung oder einem anderen Befehl folgen.

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

Bearbeitungsbefehle

[:]ED

Startet den Text-Editor. Verwenden Sie diesen Editor, um den aktuellen Transact-SQL Batch oder den letzten Ausführungsbatch zu bearbeiten. Um den letzten Ausführungsbatch zu bearbeiten, geben Sie den ED Befehl unmittelbar nach Abschluss der letzten Batchausführung ein.

Die SQLCMDEDITOR Umgebungsvariable definiert den Text-Editor. Der Standardeditor ist Edit. Legen Sie die Umgebungsvariable SQLCMDEDITOR fest, um den Editor zu ändern. Wenn Sie beispielsweise den Editor auf Microsoft Notepad festlegen möchten, geben Sie den folgenden Befehl 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.

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.

Ausgabebefehle

:Error <Dateiname> | STDERR | STDOUT

Alle Fehlerausgaben in die angegebene Datei umleiten, an stderr oder an stdout. Der :Error-Befehl kann mehrmals in einem Skript verwendet werden. Standardmäßig wechselt die Fehlerausgabe zu stderr.

• filename

  Erstellt eine Datei, in die die Ausgabe geschrieben wird, und öffnet sie. Eine vorhandene Datei wird auf null Bytes abgeschnitten. Wenn die Datei aufgrund von Berechtigungen oder anderen Gründen nicht verfügbar ist, wird die Ausgabe nicht gewechselt, und das letzte angegebene oder Standardziel empfängt die Fehlerausgabe.

• STDERR

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

• STDOUT

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

:Out <Dateiname> | STDERR | STDOUT

Erstellt und leitet alle Abfrageergebnisse an die Datei weiter, die durch Dateinamen, an stderroder an stdout. Standardmäßig wechselt die Ausgabe zu stdout. 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 Leistungsablaufverfolgungsinformationen an die Datei weiter, die durch Dateiname angegeben ist, an stderr oder an stdout. Standardmäßig wird die Ausgabe der Leistungsablaufverfolgung an stdout. Eine vorhandene Datei wird auf null Bytes abgeschnitten. Der :Perftrace-Befehl kann mehrmals in einem Skript verwendet werden.

Befehle zur Ausführungssteuerung

:On Error [ beenden | ignorieren ]

Legt die auszuführende Aktion fest, wenn während der Skript- oder Batchausführung ein Fehler auftritt.

Wenn Sie die exit Option verwenden, wird sqlcmd mit dem entsprechenden Fehlerwert beendet.

Wenn Sie die ignore Option verwenden, ignoriert sqlcmd den Fehler und führt die Ausführung des Batchs oder Skripts fort. Sqlcmd druckt standardmäßig eine Fehlermeldung.

[:]QUIT

Bewirkt, dass sqlcmd beendet wird.

[:]EXIT [ ( Anweisung ) ]

Verwenden Sie das Ergebnis einer SELECT Anweisung als Rückgabewert von sqlcmd. 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 höhere Versionen übergeben die ganze 4-Byte-Ganzzahl. 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 mit nichts zwischen den Klammern führt alle vorherigen Anweisungen im Batch aus und beendet dann ohne Rückgabewert.

Wenn Sie eine falsche Abfrage angeben, wird sqlcmd ohne Rückgabewert beendet.

Hier ist eine Liste mit EXIT Formaten:

• :EXIT

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

• :EXIT( )

  Führt die Batchdatei aus, beendet die Ausführung und gibt keinen Wert zurück.

• :EXIT(query)

  Führt den Batch aus, der die Abfrage enthält, und wird dann beendet, nachdem die Ergebnisse der Abfrage zurückgegeben wurden.

Wenn Sie RAISERROR in einem sqlcmd-Skript verwenden und den Status 127 auslösen, beendet sqlcmd die Ausführung und gibt die Nachrichten-ID zurück an den Client. 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 von SQL Server reserviert, und sqlcmd definiert zusätzliche Rückgabewerte.

GO [anzahl]

GO signalisiert sowohl das Ende eines Batches als auch die Ausführung aller zwischengespeicherten Transact-SQL-Anweisungen. Der 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 Dateinamen angegebenen Datei im Anweisungscache. Sqlcmd liest den Dateinamen relativ zum Startverzeichnis.

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

sqlcmd liest und führt die Datei aus, nachdem sie auf einen Batchterminator trifft. Sie können den :r-Befehl mehrmals verwenden. Die Datei kann jeden sqlcmd-Befehl enthalten, einschließlich des Batch-Beendigungszeichens GO.

: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]] [-N[s|m|o]] [-F hostname_in_certificate]

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

• Verschlüsselungsoptionen (-N[s|m|o]):

  Verwenden Sie diese Option, um eine verschlüsselte Verbindung anzufordern. Wenn Sie nicht einschließen -N, ist -Nm (für mandatory) die Standardeinstellung. Diese Option ist eine umbrechende Änderung von SQL Server 2022 (16.x) und früheren Versionen, wobei -No (für optional) der Standardwert ist.

  Value	Description
  -Ns	Streng
  -Nm (Standardwert)	Obligatorisch.
  -No	Wahlfrei

• Hostname im Zertifikat (-F hostname_in_certificate)

  Gibt einen anderen, erwarteten Common Name (CN) oder Subject Alternate Name (SAN) im Serverzertifikat an, der bei der Validierung des Serverzertifikats verwendet werden soll. Ohne diese Option stellt die Zertifikatsüberprüfung sicher, dass der CN oder SAN im Zertifikat mit dem Servernamen übereinstimmt, mit dem Sie sich verbinden. Dieser Parameter kann aufgefüllt werden, wenn der Servername nicht mit dem CN oder SAN übereinstimmt, z. B. bei Verwendung von DNS-Aliasen.

• 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 Sie nur user_name (entweder als Option oder als Umgebungsvariable) angeben, werden Sie von sqlcmd aufgefordert, ein Kennwort einzugeben. 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

Verwenden Sie die folgenden Einstellungen, um mit der Standardinstanz von myserver unter Verwendung von Skriptvariablen eine Verbindung herzustellen:

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

[:]!! command

Führt Befehle des Betriebssystems aus. Um einen Betriebssystembefehl auszuführen, starten Sie eine Zeile mit zwei Ausrufezeichen (!!) gefolgt vom Betriebssystembefehl. Beispiel:

:!! dir

:XML [ EIN | AUS ]

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

:Help

Listet sqlcmd-Befehle zusammen mit einer kurzen Beschreibung der einzelnen Befehle auf.

sqlcmd-Dateinamen

Geben Sie sqlcmd-Eingabedateien mithilfe der -i Option oder des :r Befehls an. Geben Sie Ausgabedateien mithilfe der -o-Option oder den Befehlen :Error, :Out und :Perftrace an. Wenn Sie mit diesen Dateien arbeiten, verwenden Sie die folgenden Richtlinien:

• Verwenden Sie separate Dateinamenwerte für :Error, :Outund :Perftrace. Wenn Sie denselben Dateinamen verwenden, könnten die Befehle Eingaben vermischen.

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

• 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 druckt alle vom Server gesendeten Informationsmeldungen. Im folgenden Beispiel wird, nachdem sqlcmd die Transact-SQL Anweisungen ausgeführt hat, eine Informationsmeldung ausgegeben.

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

USE AdventureWorks2025;
GO

Wenn Sie die EINGABETASTE drücken, druckt sqlcmd die folgende Informationsmeldung:

Changed database context to 'AdventureWorks2025'.

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, füllt sqlcmd die Ausgabe mit Leerzeichen auf, um die Spaltenbreite zu erreichen.

sqlcmd druckt eine Trennlinie, die eine Reihe von Strichzeichen ist. Die folgende Ausgabe zeigt ein Beispiel.

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

USE AdventureWorks2025;

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

Wenn Sie die EINGABETASTE drücken, gibt sqlcmd den folgenden Resultset zurück.

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 beendet sqlcmd die Ausgabe mit 80 Zeichen. Sie können diese Breite ändern, 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.

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 Ausführung einer Transact-SQL-Anweisung gegeben 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.

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 für die Verwendung der Microsoft Entra-Authentifizierung:

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

• sqlcmd-Hilfsprogramm
• Überprüfen der installierten Version des sqlcmd-Hilfsprogramms
• Starten des Hilfsprogramms „sqlcmd“
• Ausführen von T-SQL aus einer Skriptdatei mit sqlcmd
• Verwenden von sqlcmd