Polecenia w narzędziu sqlcmd

Dotyczy:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsAnalytics Platform System (PDW)SQL Database w Microsoft Fabric

Narzędzie sqlcmd umożliwia wprowadzanie instrukcji Transact-SQL, procedur systemowych i plików skryptów.

Note

Aby dowiedzieć się, który wariant i wersja narzędzia sqlcmd jest zainstalowany w systemie, zobacz Sprawdzanie zainstalowanej wersji narzędzia sqlcmd. Aby uzyskać informacje na temat pobierania narzędzia sqlcmd, zobacz Pobieranie i instalowanie narzędzia sqlcmd.

Oprócz instrukcji Transact-SQL w sqlcmddostępne są również następujące polecenia:

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

¹ Nieobsługiwane w systemie Linux lub macOS.

Podczas korzystania z poleceń sqlcmd należy pamiętać o następujących kwestiach:

• Wszystkie polecenia sqlcmd, z wyjątkiem GO, muszą być poprzedzone dwukropkiem (:).

  Important

  Aby zachować zgodność wsteczną z istniejącymi skryptami osql, niektóre polecenia są rozpoznawane bez dwukropka, co wskazuje :.

• polecenia sqlcmd są rozpoznawane tylko wtedy, gdy pojawiają się na początku wiersza.

• Wszystkie polecenia sqlcmd są niewrażliwe na wielkość liter.

• Każde polecenie musi znajdować się w osobnym wierszu. Polecenie nie może być poprzedzone instrukcją Transact-SQL ani innym poleceniem.

• Polecenia są wykonywane natychmiast. Nie są one umieszczane w buforze wykonywania tak, jak instrukcje Transact-SQL.

Edytowanie poleceń

[:]ED

Uruchamia edytor tekstów. Za pomocą tego edytora można edytować bieżącą Transact-SQL partię lub ostatnią wykonaną partię. Aby edytować ostatnią wykonaną partię, polecenie ED musi być wpisywane natychmiast po zakończeniu wykonywania ostatniej partii.

Edytor tekstu jest definiowany przez zmienną środowiskową SQLCMDEDITOR. Domyślny edytor to Edit. Aby zmienić edytor, ustaw zmienną środowiskową SQLCMDEDITOR. Aby na przykład ustawić program Microsoft Notatnik jako edytor, w wierszu polecenia wpisz:

SET SQLCMDEDITOR=notepad

[:]RESET

Czyści pamięć podręczną deklaracji.

:List

Drukuje zawartość pamięci podręcznej zapytań.

Variables

:Setvar <var> [ "wartość" ]

Definiuje zmienne skryptowe sqlcmd. Zmienne skryptowe mają następujący format: $(VARNAME).

Nazwy zmiennych są niewrażliwe na wielkość liter.

Zmienne skryptowe można ustawić na następujące sposoby:

• Niejawne użycie opcji wiersza polecenia. Na przykład opcja -l ustawia zmiennąSQLCMDLOGINTIMEOUT sqlcmd.
• Jawnie przy użyciu polecenia :Setvar.
• Definiowanie zmiennej środowiskowej przed uruchomieniem polecenia sqlcmd.

Note

Opcja -X uniemożliwia przekazywanie zmiennych środowiskowych do sqlcmd.

Jeśli zmienna zdefiniowana przy użyciu :Setvar i zmiennej środowiskowej mają taką samą nazwę, zmienna zdefiniowana przy użyciu :Setvar ma pierwszeństwo.

Nazwy zmiennych nie mogą zawierać pustych znaków spacji.

Nazwy zmiennych nie mogą mieć tej samej formy co wyrażenia zmiennej, takie jak $(var).

Jeśli wartość ciągu zmiennej skryptowej zawiera puste spacje, należy ująć wartość w cudzysłów. Jeśli nie określono wartości zmiennej skryptowej, zmienna skryptowa zostanie porzucona.

:Listvar

Wyświetla listę aktualnie ustawionych zmiennych skryptowych.

Note

Wyświetlane są tylko zmienne skryptowe ustawiane przez polecenie sqlcmd i zmienne ustawione przy użyciu :Setvar polecenia.

Polecenia wyjściowe

:Błąd <nazwa pliku> | STDERR | STDOUT

Przekieruj wszystkie dane wyjściowe błędu do pliku wskazanego przez filename, na stderr lub do stdout. Polecenie :Error może pojawić się wiele razy w skrypcie. Domyślnie komunikaty o błędach są wysyłane do stderr.

• filename

  Tworzy i otwiera plik, który odbiera dane wyjściowe. Jeśli plik już istnieje, zostanie obcięty do zera bajtów. Jeśli plik nie jest dostępny z powodu uprawnień lub innych powodów, dane wyjściowe nie są zmieniane i są wysyłane do ostatnio określonego lub domyślnego miejsca docelowego.

• STDERR

  Przełącza strumień błędów na stderr. Jeśli dane wyjściowe zostały przekierowane, docelowy obiekt, do którego jest przekierowywany strumień, odbiera błędne dane wyjściowe.

• STDOUT

  Przełącza strumień błędów na stdout. Jeśli dane wyjściowe zostały przekierowane, docelowy obiekt, do którego jest przekierowywany strumień, odbiera błędne dane wyjściowe.

:Out <nazwa pliku> | STDERR | STDOUT

Tworzy i przekierowuje wszystkie wyniki zapytania do pliku określonego przez nazwę pliku , do stderr lub do stdout. Domyślnie dane wyjściowe są wysyłane do stdout. Jeśli plik już istnieje, zostanie obcięty do zera bajtów. Polecenie :Out może pojawić się wiele razy w skrypcie.

:Perftrace <nazwa pliku> | STDERR | STDOUT

Tworzy i przekierowuje wszystkie informacje śledzenia wydajności do pliku o nazwie , do stderr lub do stdout. Domyślnie wyniki śledzenia wydajności są wysyłane do stdout. Jeśli plik już istnieje, zostanie obcięty do zera bajtów. Polecenie :Perftrace może pojawić się wiele razy w skrypcie.

Polecenia kontroli realizacji

:Przy błędzie [ zakończ | zignoruj ]

Ustawia akcję do wykonania, gdy wystąpi błąd podczas wykonywania skryptu lub partii.

Gdy jest używana opcja exit, sqlcmd kończy działanie z odpowiednią wartością błędu.

Gdy jest używana opcja ignore, sqlcmd ignoruje błąd i kontynuuje wykonywanie partii lub skryptu. Domyślnie jest wyświetlany komunikat o błędzie.

[:]QUIT

Powoduje zakończenie działania sqlcmd .

[:]EXIT [ ( instrukcja ) ]

Umożliwia użycie wyniku instrukcji SELECT jako wartości zwracanej z sqlcmd. Jeśli wartość liczbowa, pierwsza kolumna ostatniego wiersza wyników jest konwertowana na liczbę całkowitą 4-bajtową (długą). Systemy MS-DOS, Linux i macOS przekazują niższy bajt do poziomu błędu procesu nadrzędnego lub systemu operacyjnego. System Windows 2000 i nowsze wersje przekazują całą 4-bajtową liczbę całkowitą. Składnia jest :EXIT(query).

Przykład:

:EXIT(SELECT @@ROWCOUNT)

Można również dołączyć parametr :EXIT w ramach pliku wsadowego. Na przykład w wierszu polecenia wpisz:

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

Narzędzie sqlcmd wysyła wszystko między nawiasami (()) do serwera. Jeśli systemowa procedura składowana wybiera zestaw i zwraca wartość, zwracany jest tylko wybór. Instrukcja :EXIT() bez niczego między nawiasami wykonuje wszystko, co jest przed nią w serii, a następnie kończy działanie bez zwracania wartości.

Po określeniu nieprawidłowego zapytania sqlcmd kończy działanie bez zwracanej wartości.

Oto lista formatów EXIT:

• :EXIT

  Nie wykonuje skryptu wsadowego, i od razu kończy działanie, nie zwracając żadnej wartości.

• :EXIT( )

  Wykonuje zadanie, a następnie zakończa i nie zwraca żadnej wartości.

• :EXIT(query)

  Wykonuje partię zawierającą zapytanie, a następnie kończy działanie po powrocie wyników zapytania.

Jeśli RAISERROR jest używana w skrypcie sqlcmd i zgłoszony zostanie stan 127, sqlcmd kończy działanie i zwraca identyfikator komunikatu z powrotem do klienta. Przykład:

RAISERROR(50001, 10, 127)

Ten błąd powoduje zakończenie skryptu sqlcmd i zwrócenie komunikatu o identyfikatorze 50001 do klienta.

Zwracane wartości -1 do -99 są zarezerwowane przez program SQL Server, a sqlcmd definiuje następujące dodatkowe wartości zwracane:

Wartość zwracana	Description
-100	Wystąpił błąd przed wybraniem wartości zwracanej.
-101	Podczas wybierania wartości zwracanej nie znaleziono wierszy.
-102	Wystąpił błąd konwersji podczas wybierania wartości zwracanej.

GO [count]

GO sygnalizuje zarówno koniec partii, jak i wykonywanie wszelkich buforowanych instrukcji Transact-SQL. Seria jest wykonywana wiele razy jako oddzielne partie. Nie można zadeklarować zmiennej więcej niż raz w jednej partii.

Różne polecenia

:r <nazwa pliku>

Analizuje dodatkowe instrukcje Transact-SQL i polecenia sqlcmd z pliku określonego przez filename do bufora instrukcji. nazwa pliku jest odczytywana względem katalogu startowego, w którym uruchomiono sqlcmd.

Jeśli plik zawiera instrukcje Transact-SQL, które nie są poprzedzone przez GO, należy wprowadzić GO w wierszu, który następuje po :r.

Plik zostanie odczytany i wykonany po napotkaniu terminatora wsadowego. Można wydać wiele poleceń :r. Plik może zawierać dowolne polecenie sqlcmd, w tym terminator GOzestawu.

Note

Liczba wierszy wyświetlana w trybie interaktywnym jest zwiększana o jedną dla każdego :r napotkanego polecenia. Polecenie :r zostanie wyświetlone w danych wyjściowych polecenia listy.

:ServerList

Wyświetla listę lokalnie skonfigurowanych serwerów i nazw serwerów nadających w sieci.

:Connect server_name[\instance_name] [-l limit czasu] [-U user_name [-P hasło]]

Nawiązuje połączenie z wystąpieniem SQL Server. Zamyka również bieżące połączenie.

Opcje limitu czasu:

Value	Behavior
0	Czekaj na zawsze
n>0	Poczekaj n sekund

Zmienna skryptowa SQLCMDSERVER odzwierciedla bieżące aktywne połączenie.

Jeśli limit czasu nie zostanie określony, wartość zmiennej SQLCMDLOGINTIMEOUT jest wartością domyślną.

Jeśli zostanie określona tylko user_name (jako opcja lub jako zmienna środowiskowa), użytkownik zostanie poproszony o wprowadzenie hasła. Użytkownicy nie otrzymują powiadomień, jeśli zmienne środowiskowe SQLCMDUSER lub SQLCMDPASSWORD są ustawione. Jeśli nie udostępniasz opcji ani zmiennych środowiskowych, tryb uwierzytelniania systemu Windows jest używany do logowania. Aby na przykład ustanowić połączenie z wystąpieniem instance1serwera SQL Server myserver, przy użyciu zintegrowanego bezpieczeństwa, należy użyć następującego polecenia:

:connect myserver\instance1

Aby nawiązać połączenie z domyślnym wystąpieniem myserver przy użyciu zmiennych skryptowych, należy użyć następujących ustawień:

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

[:]!! command

Wykonuje polecenia systemu operacyjnego. Aby wykonać polecenie systemu operacyjnego, uruchom wiersz z dwoma wykrzyknikami (!!), a następnie polecenie systemu operacyjnego. Przykład:

:!! dir

Note

Polecenie jest wykonywane na komputerze, na którym jest uruchomiony sqlcmd.

:XML [ ON | WYŁĄCZONE ]

Aby uzyskać więcej informacji, zobacz format danych wyjściowych XML i format danych wyjściowych JSON w tym artykule.

:Help

Wymienia polecenia sqlcmd wraz z krótkim opisem każdego polecenia.

nazwy plików sqlcmd

pliki wejściowe sqlcmd można określić za pomocą opcji -i lub polecenia :r. Pliki wyjściowe można określić za pomocą -o opcji lub :Errorpoleceń , :Outi :Perftrace . Poniżej przedstawiono pewne wskazówki dotyczące pracy z tymi plikami:

• :Error, :Outi :Perftrace powinny używać oddzielnych wartości nazw plików . W przypadku użycia tej samej nazwy pliku, dane wejściowe z poleceń mogą się wymieszać.

• Jeśli plik wejściowy znajdujący się na serwerze zdalnym jest wywoływany z sqlcmd na komputerze lokalnym, a plik zawiera ścieżkę pliku dysku, taką jak :Out c:\OutputFile.txt, plik wyjściowy jest tworzony na komputerze lokalnym, a nie na serwerze zdalnym.

• Prawidłowe ścieżki plików obejmują: C:\<filename>, \\<Server>\<Share$>\<filename>i "C:\Some Folder\<file name>". Jeśli w ścieżce znajduje się spacja, użyj cudzysłowów.

• Każda nowa sqlcmd sesji zastępuje istniejące pliki o tych samych nazwach.

Komunikaty informacyjne

sqlcmd wyświetla wszelkie komunikaty informacyjne wysyłane przez serwer. W poniższym przykładzie po wykonaniu instrukcji Transact-SQL zostanie wydrukowany komunikat informacyjny.

Uruchom sqlcmd. W wierszu polecenia sqlcmd wpisz zapytanie:

USE AdventureWorks2022;
GO

Po naciśnięciu ENTERzostanie wyświetlony następujący komunikat informacyjny:

Changed database context to 'AdventureWorks2022'.

Format danych wyjściowych z zapytań Transact-SQL

sqlcmd najpierw wyświetla nagłówek kolumny, który zawiera nazwy kolumn określone na liście wyboru. Nazwy kolumn są oddzielone znakiem SQLCMDCOLSEP. Domyślnie ten separator kolumn jest spacją. Jeśli nazwa kolumny jest krótsza niż szerokość kolumny, dane wyjściowe są dopełniane spacjami do następnej kolumny.

Po tym wierszu następuje linia separacyjna, składająca się z serii znaków kreski. Następujący wynik pokazuje przykład.

Uruchom sqlcmd. W wierszu polecenia sqlcmd wpisz zapytanie:

USE AdventureWorks2022;

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

Po naciśnięciu ENTERzostanie zwrócony następujący zestaw wyników.

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

Mimo że kolumna BusinessEntityID ma tylko cztery znaki szerokości, rozszerza się, aby pomieścić dłuższą nazwę kolumny. Domyślnie dane wyjściowe są zakończone na 80 znakach. Tę szerokość można zmienić przy użyciu opcji -w lub ustawiając zmienną skryptową SQLCMDCOLWIDTH.

Format danych wyjściowych XML

Dane wyjściowe XML będące wynikiem klauzuli FOR XML to dane wyjściowe, niesformatowane, w strumieniu ciągłym.

Jeśli oczekujesz danych wyjściowych XML, użyj następującego polecenia: :XML ON.

Note

sqlcmd zwraca komunikaty o błędach w zwykłym formacie. Komunikaty o błędach są również eksportowane w strumieniu tekstowym XML w formacie XML. Przy użyciu :XML ONprogram sqlcmd nie wyświetla komunikatów informacyjnych.

Aby ustawić tryb XML na wyłączony, użyj następującego polecenia: :XML OFF.

Polecenie GO nie powinno być wyświetlane przed wydaniem polecenia :XML OFF, ponieważ polecenie :XML OFF przełącza sqlcmd z powrotem do danych wyjściowych zorientowanych na wiersz.

Nie można mieszać danych xml (przesyłanych strumieniowo) i danych zestawu wierszy. :XML ON Jeśli polecenie nie zostało wystawione przed instrukcją Transact-SQL, która zwraca strumienie XML jest wykonywana, dane wyjściowe są uruchamiane. Po wydaniu polecenia :XML ON nie można wykonać instrukcji Transact-SQL, które generują standardowe zestawy wierszy.

Note

Polecenie :XML nie obsługuje instrukcji SET STATISTICS XML.

Format danych wyjściowych JSON

Jeśli oczekujesz danych wyjściowych JSON, użyj następującego polecenia: :XML ON. W przeciwnym razie dane wyjściowe zawierają zarówno nazwę kolumny, jak i tekst JSON. Te dane wyjściowe nie są prawidłowe w formacie JSON.

Aby ustawić tryb XML na wyłączony, użyj następującego polecenia: :XML OFF.

Aby uzyskać więcej informacji, zobacz format danych wyjściowych XML w tym artykule.

Korzystanie z uwierzytelniania Microsoft Entra

Przykłady użycia uwierzytelniania entra firmy Microsoft:

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

Treści powiązane

• narzędzie sqlcmd
• Sprawdzanie zainstalowanej wersji narzędzia sqlcmd
• Uruchamianie narzędzia sqlcmd
• Wykonywanie języka T-SQL z pliku skryptu za pomocą polecenia sqlcmd
• Korzystanie z narzędzia sqlcmd