Opdrachten in het hulpprogramma sqlcmd

Van toepassing op:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsAnalytics Platform System (PDW)SQL Database in Microsoft Fabric

Het hulpprogramma sqlcmd accepteert Transact-SQL instructies, systeemprocedures en scriptbestanden.

Gebruik naast Transact-SQL instructies in sqlcmd de volgende opdrachten:

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

¹ Niet ondersteund in Linux of macOS.

Houd rekening met de volgende punten wanneer u sqlcmd-opdrachten gebruikt:

• Alle sqlcmd-opdrachten , behalve GO, moeten beginnen met een dubbele punt (:).

  Important

  Om achterwaartse compatibiliteit met bestaande osql-scripts te behouden, werken sommige opdrachten zonder de dubbelpunt (aangegeven door [:]).

• sqlcmd herkent opdrachten alleen als ze aan het begin van een regel worden weergegeven.

• Alle sqlcmd opdrachten zijn niet hoofdlettergevoelig.

• Elke opdracht moet op een afzonderlijke regel staan. U kunt een opdracht niet volgen met een Transact-SQL instructie of een andere opdracht.

• Opdrachten worden onmiddellijk uitgevoerd. Ze worden niet zoals Transact-SQL-instructies in de uitvoeringsbuffer geplaatst.

Bewerkingsopdrachten

[:]ED

Hiermee start u de teksteditor. Gebruik deze editor om de huidige Transact-SQL batch of de laatste runbatch te bewerken. Als u de laatste uitvoeringsbatch wilt bewerken, typt u de ED opdracht direct nadat de laatste batch is voltooid.

De SQLCMDEDITOR omgevingsvariabele definieert de teksteditor. De standaardeditor is Edit. Als u de editor wilt wijzigen, stelt u de omgevingsvariabele SQLCMDEDITOR in. Als u bijvoorbeeld de editor wilt instellen op Microsoft Kladblok, typt u de volgende opdracht:

SET SQLCMDEDITOR=notepad

[:]RESET

Leegt de verklaring cache.

:List

Hiermee wordt de inhoud van de verklaringscache weergegeven.

Variables

:Setvar <var> [ "waarde" ]

Definieert sqlcmd scriptvariabelen. Scriptvariabelen hebben de volgende indeling: $(VARNAME).

Variabelenamen zijn niet hoofdlettergevoelig.

Scriptvariabelen kunnen op de volgende manieren worden ingesteld:

• Impliciet gebruikend een opdrachtregeloptie. Met de optie -l wordt bijvoorbeeld de variabele SQLCMDLOGINTIMEOUTsqlcmd ingesteld.
• Expliciet met behulp van de opdracht :Setvar.
• Een omgevingsvariabele definiëren voordat u sqlcmd uitvoert.

Als een variabele die is gedefinieerd met behulp van :Setvar en een omgevingsvariabele dezelfde naam heeft, heeft de variabele die is gedefinieerd met behulp van :Setvar voorrang.

Namen van variabelen mogen geen spatietekens bevatten.

Namen van variabelen kunnen niet hetzelfde formulier hebben als een variabeleexpressie, zoals $(var).

Als de tekenreekswaarde van de scriptvariabele lege spaties bevat, plaatst u de waarde tussen aanhalingstekens. Als er geen waarde voor een scriptvariabele is opgegeven, wordt de scriptvariabele verwijderd.

:Listvar

Geeft een lijst weer van de scriptvariabelen die momenteel zijn ingesteld.

Uitvoeropdrachten

:Fout <bestandsnaam> | STDERR | STDOUT

Alle foutuitvoer omleiden naar het bestand dat is opgegeven door bestandsnaam, naar stderr, of naar stdout. De opdracht :Error kan meerdere keren in een script worden weergegeven. Standaard gaat de foutuitvoer naar stderr.

• filename

  Hiermee maakt en opent u een bestand dat de uitvoer ontvangt. Een bestaand bestand wordt afgekapt tot nul bytes. Als het bestand niet beschikbaar is vanwege machtigingen of andere redenen, wordt de uitvoer niet gewijzigd en ontvangt de laatst opgegeven of standaardbestemming de foutuitvoer.

• STDERR

  Hiermee schakelt u foutuitvoer naar de stderr stream. Als uitvoer wordt omgeleid, ontvangt het doel waarnaar de stream wordt omgeleid de foutuitvoer.

• STDOUT

  Hiermee schakelt u foutuitvoer naar de stdout stream. Als uitvoer wordt omgeleid, ontvangt het doel waarnaar de stream wordt omgeleid de foutuitvoer.

:Out <bestandsnaam> | STDERR | STDOUT

Hiermee worden alle queryresultaten gemaakt en omgeleid naar het bestand dat is opgegeven door de bestandsnaam, naar stderrof naar stdout. Standaard gaat de uitvoer naar stdout. Als het bestand al bestaat, wordt het afgekapt tot nul bytes. De opdracht :Out kan meerdere keren in een script worden weergegeven.

:Perftrace <bestandsnaam> | STDERR | STDOUT

Hiermee maakt en omleidt u alle prestatietraceringsgegevens naar het bestand dat is opgegeven door de bestandsnaam, naar stderrof naar stdout. Standaard gaat de prestatietraceringsuitvoer naar stdout. Een bestaand bestand wordt afgekapt tot nul bytes. De opdracht :Perftrace kan meerdere keren in een script worden weergegeven.

Opdrachten voor uitvoeringsbeheer

:Bij foutmelding [ afsluiten | negeren ]

Hiermee stelt u de actie in die moet worden uitgevoerd wanneer er een fout optreedt tijdens het uitvoeren van een script of batch.

Wanneer u de exit optie gebruikt, wordt sqlcmd afgesloten met de juiste foutwaarde.

Wanneer u de ignore optie gebruikt, negeert sqlcmd de fout en gaat verder met het uitvoeren van de batch of het script. Sqlcmd drukt standaard een foutbericht af.

[:]QUIT

Zorgt ervoor dat sqlcmd wordt afgesloten.

[:]EXIT [ ( verklaring ) ]

Gebruik het resultaat van een SELECT instructie als de retourwaarde van sqlcmd. Als de numerieke waarde is, wordt de eerste kolom van de laatste resultaatrij geconverteerd naar een geheel getal van 4 bytes (lang). MS-DOS, Linux en macOS geven de lage byte door naar het foutniveau van het bovenliggende proces of besturingssysteem. Windows 2000 en latere versies geven de volledige 4-byte-integer door. De syntaxis is :EXIT(query).

Voorbeeld:

:EXIT(SELECT @@ROWCOUNT)

U kunt ook de parameter :EXIT opnemen als onderdeel van een batchbestand. Typ bijvoorbeeld bij de opdrachtprompt:

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

Het hulpprogramma sqlcmd verzendt alles tussen de haakjes (()) naar de server. Als een systeem opgeslagen procedure een set selecteert en een waarde retourneert, wordt alleen de selectie geretourneerd. De :EXIT() instructie met niets tussen de haakjes voert alles uit voordat deze in de batch wordt uitgevoerd en sluit vervolgens af zonder een retourwaarde.

Wanneer u een onjuiste query opgeeft, wordt sqlcmd afgesloten zonder een retourwaarde.

Hier volgt een lijst met EXIT formaten:

• :EXIT

  De batch wordt niet uitgevoerd en wordt vervolgens onmiddellijk afgesloten en er wordt geen waarde geretourneerd.

• :EXIT( )

  Voert de batch uit, sluit vervolgens af en retourneert geen waarde.

• :EXIT(query)

  Hiermee wordt de batch uitgevoerd die de query bevat en wordt vervolgens afgesloten nadat de resultaten van de query zijn geretourneerd.

Als u binnen een RAISERROR een status van 127 verhoogt, wordt sqlcmd afgesloten en wordt de bericht-id naar de client teruggestuurd. Voorbeeld:

RAISERROR(50001, 10, 127)

Deze fout zorgt ervoor dat het sqlcmd--script wordt beëindigd en de bericht-id 50001 naar de client wordt geretourneerd.

De geretourneerde waarden -1-99 zijn gereserveerd door SQL Server en sqlcmd definieert extra retourwaarden:

GO [aantal]

GO geeft zowel het einde van een batch aan als de uitvoering van eventuele Transact-SQL-instructies in de cache. De batch wordt meerdere keren uitgevoerd als afzonderlijke batches. U kunt een variabele niet meer dan één keer declareren in één batch.

Diverse opdrachten

:r <bestandsnaam>

Parseert extra Transact-SQL-instructies en sqlcmd-opdrachten uit het bestand dat is opgegeven door de bestandsnaam in de instructiecache. sqlcmd leest bestandsnaam ten opzichte van de opstartmap.

Als het bestand Transact-SQL-instructies bevat die niet worden gevolgd door GO, moet u GO invoeren op de regel die op :rvolgt.

sqlcmd leest en voert het bestand uit nadat het een batch-eindteken heeft gevonden. U kunt meerdere :r opdrachten uitgeven. Het bestand kan elke sqlcmd-opdracht bevatten, inclusief het batcheindteken GO.

:ServerList

Een lijst met de lokaal geconfigureerde servers en de namen van de servers die op het netwerk worden uitgezonden.

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

Maakt verbinding met een exemplaar van SQL Server. Sluit ook de huidige verbinding.

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

  Gebruik deze optie om een versleutelde verbinding aan te vragen. Als je -N niet opneemt, is -Nm de standaard (voor mandatory). Deze optie is een belangrijke wijziging van SQL Server 2022 (16.x) en eerdere versies, waarbij -No (voor optional) de standaardinstelling is.

  Value	Description
  -Ns	Strikt
  -Nm (standaard)	Mandatory
  -No	Optioneel

• Hostnaam in certificaat (-F hostname_in_certificate)

  Hiermee geeft u een andere, verwachte algemene naam (CN) of alternatieve onderwerpnaam (SAN) op in het servercertificaat dat moet worden gebruikt tijdens de validatie van het servercertificaat. Zonder deze optie zorgt certificaatvalidatie ervoor dat de CN of SAN in het certificaat overeenkomt met de servernaam waarmee u verbinding maakt. Deze parameter kan worden ingevuld wanneer de servernaam niet overeenkomt met de CN of SAN, bijvoorbeeld bij het gebruik van DNS-aliassen.

• Time-outopties:

  Value	Behavior
  0	Wacht voor altijd
  n>0	Wacht gedurende en seconden

  De SQLCMDSERVER scriptvariabele weerspiegelt de huidige actieve verbinding.

  Als time-out niet is opgegeven, is de waarde van de variabele SQLCMDLOGINTIMEOUT de standaardwaarde.

Als u alleen user_name (als optie of als omgevingsvariabele) opgeeft, wordt u door sqlcmd gevraagd een wachtwoord in te voeren. Gebruikers worden niet gevraagd of de SQLCMDUSER of SQLCMDPASSWORD omgevingsvariabelen zijn ingesteld. Als u geen opties of omgevingsvariabelen opgeeft, wordt de Windows-verificatiemodus gebruikt om u aan te melden. Als u bijvoorbeeld verbinding wilt maken met een exemplaar, instance1, van SQL Server, myserver, met behulp van geïntegreerde beveiliging, gebruikt u de volgende opdracht:

:connect myserver\instance1

Gebruik de volgende instellingen om met de standaardinstantie van myserver verbinding te maken met behulp van scriptvariabelen.

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

[:]!! command

Voert besturingssysteemopdrachten uit. Als u een besturingssysteemopdracht wilt uitvoeren, start u een regel met twee uitroeptekens (!!) gevolgd door de opdracht van het besturingssysteem. Voorbeeld:

:!! dir

:XML [ AAN | UIT ]

Zie XML Output Format en JSON Output Format in dit artikel voor meer informatie.

:Help

Bevat sqlcmd-opdrachten , samen met een korte beschrijving van elke opdracht.

sqlcmd-bestandsnamen

Geef sqlcmd-invoerbestanden op met behulp van de -i optie of de :r opdracht. Geef uitvoerbestanden op met behulp van de -o optie of de :Error, :Outen :Perftrace opdrachten. Wanneer u met deze bestanden werkt, gebruikt u de volgende richtlijnen:

• Gebruik afzonderlijke bestandsnaamwaarden voor :Error, :Outen :Perftrace. Als u dezelfde bestandsnaam gebruikt, zouden de opdrachten invoer kunnen vermengen.

• Als u een invoerbestand op een externe server aanroept vanaf sqlcmd op een lokale computer en het bestand een bestandsstationpad bevat, zoals :Out c:\OutputFile.txtsqlcmd, wordt het uitvoerbestand gemaakt op de lokale computer, en niet op de externe server.

• Geldige bestandspaden zijn: C:\<filename>, \\<Server>\<Share$>\<filename>en "C:\Some Folder\<file name>". Als er een spatie in het pad staat, gebruik aanhalingstekens.

• Elke nieuwe sqlcmd sessie overschrijft bestaande bestanden met dezelfde namen.

Informatieve berichten

sqlcmd drukt elk informatief bericht af dat de server verzendt. In het volgende voorbeeld, nadat sqlcmd de Transact-SQL instructies uitvoert, wordt er een informatief bericht afgedrukt.

Start sqlcmd. Typ bij de opdrachtprompt sqlcmd de query:

USE AdventureWorks2025;
GO

Wanneer u op Enter drukt, drukt sqlcmd het volgende informatieve bericht af:

Changed database context to 'AdventureWorks2025'.

Uitvoerformaat van Transact-SQL queries

sqlcmd drukt eerst een kolomkop af die de kolomnamen bevat die zijn opgegeven in de selectielijst. De kolomnamen worden gescheiden door het SQLCMDCOLSEP teken te gebruiken. Dit kolomscheidingsteken is standaard een spatie. Als de kolomnaam korter is dan de kolombreedte, wordt de uitvoer door sqlcmd opgevuld met spaties tot aan de volgende kolom.

sqlcmd drukt een scheidingslijn af die een reeks streepjes is. In de volgende uitvoer ziet u een voorbeeld.

Start sqlcmd. Typ bij de opdrachtprompt sqlcmd de query:

USE AdventureWorks2025;

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

Wanneer u op Enter drukt, retourneert sqlcmd de volgende resultatenset.

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

Hoewel de BusinessEntityID kolom slechts vier tekens breed is, wordt deze uitgebreid voor de langere kolomnaam. Sqlcmd beëindigt standaard de uitvoer met 80 tekens. U kunt deze breedte wijzigen met behulp van de -w optie of door de SQLCMDCOLWIDTH scriptvariabele in te stellen.

XML-uitvoerindeling

XML-uitvoer die het resultaat is van een FOR XML-component wordt ongeformatteerd uitgevoerd in een continue stroom.

Wanneer u XML-uitvoer verwacht, gebruikt u de volgende opdracht: :XML ON.

Als u de XML-modus wilt uitschakelen, gebruikt u de volgende opdracht: :XML OFF.

De opdracht GO mag niet voorkomen voordat de opdracht :XML OFF is uitgevoerd, omdat de opdracht :XML OFF sqlcmd weer naar rijgeoriënteerde uitvoer schakelt.

XML-gegevens (gestreamde) en rijsetgegevens kunnen niet worden gecombineerd. Als de :XML ON opdracht niet is uitgegeven vóór een Transact-SQL instructie die XML-streams uitvoert, wordt de uitvoer vervormd. Zodra de :XML ON opdracht is uitgegeven, kunt u Transact-SQL instructies die reguliere rijenets uitvoeren, niet meer uitvoeren.

JSON-uitvoerindeling

Wanneer u JSON-uitvoer verwacht, gebruikt u de volgende opdracht: :XML ON. Anders bevat de uitvoer zowel de kolomnaam als de JSON-tekst. Deze uitvoer is geen geldige JSON.

Als u de XML-modus wilt uitschakelen, gebruikt u de volgende opdracht: :XML OFF.

Zie XML-uitvoerindeling in dit artikel voor meer informatie.

Microsoft Entra-verificatie gebruiken

Voorbeelden die gebruikmaken van Microsoft Entra-verificatie:

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

Verwante inhoud

• sqlcmd-hulpprogramma
• Geïnstalleerde versie van sqlcmd-hulpprogramma controleren
• het hulpprogramma sqlcmd starten
• T-SQL uitvoeren vanuit een scriptbestand met sqlcmd
• Sqlcmd gebruiken