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 akceptuje instrukcje Transact-SQL, procedury systemowe i pliki skryptów.

Oprócz instrukcji Transact-SQL w narzędziu sqlcmd użyj następujących poleceń:

• 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ą zaczynać się dwukropkiem (:).

  Important

  Aby zachować zgodność z istniejącymi skryptami osql, niektóre polecenia działają bez dwukropka (wskazuje na to [:]).

• Narzędzie sqlcmd rozpoznaje polecenia 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. Nie można wykonać polecenia za pomocą instrukcji Transact-SQL lub innego polecenia.

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

Edytowanie poleceń

[:]ED

Uruchamia edytor tekstów. Użyj tego edytora, aby edytować bieżącą transakcję Transact-SQL lub ostatnio uruchomioną transakcję. Aby edytować ostatnio uruchomioną partię, wpisz polecenie ED natychmiast po zakończeniu wykonywania ostatniej partii.

Zmienna SQLCMDEDITOR środowiskowa definiuje edytor tekstów. Domyślny edytor to Edit. Aby zmienić edytor, ustaw zmienną środowiskową SQLCMDEDITOR. Aby na przykład ustawić jako edytor Notatnik systemu Microsoft, wpisz następujące polecenie:

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.

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.

Polecenia wyjściowe

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

Przekieruj wszystkie dane wyjściowe błędu do pliku określonego przez nazwę pliku, do stderr, lub do stdout. Polecenie :Error może pojawić się wiele razy w skrypcie. Domyślnie wyjście błędu jest kierowane do stderr.

• filename

  Tworzy i otwiera plik, który odbiera dane wyjściowe. Istniejący plik jest obcinany do zera bajtów. Jeśli plik nie jest dostępny z powodu uprawnień lub innych powodów, dane wyjściowe nie są przełączane, a ostatni określony lub domyślny obiekt docelowy odbiera dane wyjściowe błędu.

• STDERR

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

• STDOUT

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

: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 przechodzą 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 określonego przez nazwę pliku, do stderr, lub do stdout. Domyślnie dane wyjściowe śledzenia wydajności przechodzą do stdout. Istniejący plik jest obcinany 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.

W przypadku korzystania z exit opcji program sqlcmd kończy działanie z odpowiednią wartością błędu.

Jeśli używasz ignore opcji, narzędzie sqlcmd ignoruje błąd i kontynuuje wykonywanie partii lub skryptu. Domyślnie narzędzie sqlcmd wyświetla komunikat o błędzie.

[:]QUIT

Powoduje zakończenie działania sqlcmd .

[:]EXIT [ ( instrukcja ) ]

Użyj wyniku instrukcji SELECT jako wartości zwracanej z polecenia 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ą 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 żadnych elementów między nawiasami uruchamia wszystko, co było w zadaniu wsadowym przed nią, a następnie kończy działanie bez zwracania wartości.

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

Oto lista formatów EXIT:

• :EXIT

  Nie uruchamia zadania, natychmiast kończy działanie i nie zwraca żadnej wartości.

• :EXIT( )

  Uruchamia partię, a następnie zakończa działanie oraz nie zwraca wartości.

• :EXIT(query)

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

Jeśli używasz RAISERROR skryptu sqlcmd i zgłaszasz 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-99 są zarezerwowane przez program SQL Server, a polecenie sqlcmd definiuje dodatkowe wartości zwracane:

GO [count]

GO sygnalizuje zarówno koniec partii, jak i wykonywanie wszelkich buforowanych instrukcji Transact-SQL. Partia jest uruchamiana 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 nazwę pliku do pamięci podręcznej instrukcji. sqlcmd odczytuje nazwę pliku względem katalogu startowego.

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.

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

:ServerList

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

:Connect server_name[\instance_name] [-l timeout] [-U user_name [-P password]] [-N[s|m|o]] [-F hostname_in_certificate]

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

• Opcje szyfrowania (-N[s|m|o]):

  Użyj tej opcji, aby zażądać zaszyfrowanego połączenia. Jeśli nie dołączysz -N, -Nm (dla mandatory) jest wartością domyślną. Ta opcja jest zasadniczą zmianą w porównaniu do SQL Server 2022 (16.x) i wcześniejszych wersji, gdzie -No (dla optional) jest ustawieniem domyślnym.

  Value	Description
  -Ns	Surowy
  -Nm (ustawienie domyślne)	Mandatory
  -No	Opcjonalnie

• Nazwa hosta w certyfikacie (-F hostname_in_certificate)

  Określa inną, oczekiwaną nazwę pospolitą (CN) lub alternatywną nazwę podmiotu (SAN) w certyfikacie serwera do użycia podczas walidacji certyfikatu serwera. Bez tej opcji weryfikacja certyfikatu gwarantuje, że cn lub SAN w certyfikacie są zgodne z nazwą serwera, z którym nawiązujesz połączenie. Ten parametr można wypełnić, gdy nazwa serwera nie jest zgodna z CN lub SAN, na przykład podczas korzystania z aliasów DNS.

• 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 określisz tylko user_name (jako opcję lub jako zmienną środowiskową), polecenie sqlcmd wyświetli monit 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, użyj następujących ustawień:

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

[:]!! command

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

:!! dir

: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

Wyświetla listę poleceń sqlcmd wraz z krótkim opisem każdego polecenia.

nazwy plików sqlcmd

Określ pliki wejściowe sqlcmd przy użyciu -i opcji lub :r polecenia. Określ pliki wyjściowe przy użyciu opcji -o lub poleceń :Error, :Out, i :Perftrace. Podczas pracy z tymi plikami należy użyć następujących wskazówek:

• Użyj oddzielnych wartości nazw plików dla :Error, :Outi :Perftrace. Jeśli używasz tej samej nazwy pliku, polecenia mogą wymieszać dane wejściowe.

• Jeśli wywołasz plik wejściowy znajdujący się na serwerze zdalnym z programu sqlcmd na komputerze lokalnym, a plik zawiera ścieżkę pliku dysku, taką jak :Out c:\OutputFile.txt, program sqlcmd tworzy plik wyjściowy 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

Narzędzie sqlcmd wyświetla wszelkie komunikaty informacyjne wysyłane przez serwer. W poniższym przykładzie po uruchomieniu instrukcji Transact-SQL narzędzie sqlcmd wyświetla komunikat informacyjny.

Uruchom sqlcmd. W wierszu polecenia sqlcmd wpisz zapytanie:

USE AdventureWorks2025;
GO

Po naciśnięciu klawisza Enter, sqlcmd wyświetla następujący komunikat informacyjny:

Changed database context to 'AdventureWorks2025'.

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, funkcja sqlcmd dopełnia dane wyjściowe spacjami do następnej kolumny.

sqlcmd drukuje wiersz separatora, który jest serią znaków kreski. Następujący wynik pokazuje przykład.

Uruchom sqlcmd. W wierszu polecenia sqlcmd wpisz zapytanie:

USE AdventureWorks2025;

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

Po naciśnięciu klawisza Enterpolecenie sqlcmd zwraca 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 sqlcmd ogranicza dane wyjściowe do 80 znaków. Tę szerokość można zmienić przy użyciu -w opcji lub ustawiając zmienną SQLCMDCOLWIDTH skryptową.

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.

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. Jeśli polecenie :XML ON nie zostało wydane przed uruchomieniem instrukcji Transact-SQL, która generuje strumienie XML, dane wyjściowe są zniekształcone. Po wydaniu :XML ON polecenia nie można uruchomić Transact-SQL instrukcji, które wyświetlają zwykłe zestawy wierszy.

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 korzystające z uwierzytelniania firmy Microsoft Entra:

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