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

Met het hulpprogramma sqlcmd kunt u Transact-SQL instructies, systeemprocedures en scriptbestanden invoeren.

Naast Transact-SQL instructies in sqlcmdzijn ook de volgende opdrachten beschikbaar:

• 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.

Let op het volgende wanneer u sqlcmd opdrachten gebruikt:

• Alle sqlcmd opdrachten, met uitzondering van GO, moeten worden voorafgegaan door een dubbele punt (:).

  Belangrijk

  Om de compatibiliteit met bestaande osql-scripts te behouden, worden sommige opdrachten herkend zonder de dubbele punt, zoals aangegeven door de :.

• sqlcmd opdrachten worden alleen herkend als deze worden weergegeven aan het begin van een regel.

• Alle sqlcmd opdrachten zijn niet hoofdlettergevoelig.

• Elke opdracht moet op een afzonderlijke regel staan. Een opdracht kan niet worden gevolgd door een Transact-SQL instructie of een andere opdracht.

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

Bewerkingsopdrachten

[:]Eerste hulp

Hiermee start u de teksteditor. Deze editor kan worden gebruikt om de huidige Transact-SQL batch of de laatst uitgevoerde batch te bewerken. Als u de laatst uitgevoerde batch wilt bewerken, moet de opdracht ED direct worden getypt nadat de laatste batch de uitvoering heeft voltooid.

De teksteditor wordt gedefinieerd door de omgevingsvariabele SQLCMDEDITOR. 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 bij de opdrachtprompt:

SET SQLCMDEDITOR=notepad

[:]TERUGSTELLEN

Leegt de verklaring cache.

:Lijst

Hiermee wordt de inhoud van de verklaringscache weergegeven.

Variabelen

: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 wordt foutuitvoer verzonden naar stderr.

• bestandsnaam

  Hiermee maakt en opent u een bestand dat de uitvoer ontvangt. Als het bestand al bestaat, wordt het afgekapt tot nul bytes. Als het bestand niet beschikbaar is vanwege machtigingen of andere redenen, wordt de uitvoer niet overgeschakeld en verzonden naar de laatst opgegeven of standaardbestemming.

• STDERR

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

• STDOUT

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

:Out <bestandsnaam> | STDERR | STDOUT

Hiermee worden alle queryresultaten omgeleid naar het bestand dat is opgegeven door bestandsnaam, naar stderr of naar stdout. Standaard wordt uitvoer verzonden 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 worden alle prestatietraceringsgegevens gemaakt en omgeleid naar het bestand dat is opgegeven door bestandsnaam, naar stderr of naar stdout. Standaard wordt de uitvoer van prestatietracering verzonden naar stdout. Als het bestand al bestaat, wordt het 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 de optie exit wordt gebruikt, wordt sqlcmd afgesloten met de juiste foutwaarde.

Wanneer de optie ignore wordt gebruikt, negeert sqlcmd de fout en gaat verder met het uitvoeren van de batch of het script. Standaard wordt een foutbericht afgedrukt.

[:]AFSLUITEN

Zorgt ervoor dat sqlcmd wordt afgesloten.

[:]EXIT [ ( verklaring ) ]

Hiermee kunt u het resultaat van een SELECT-instructie als retourwaarde gebruiken in de 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 het gehele getal van 4 bytes 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 retourwaarde.

Wanneer een onjuiste query is opgegeven, sqlcmd wordt afgesloten zonder een retourwaarde.

Hier volgt een lijst met EXIT formaten:

• :EXIT

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

• :EXIT( )

  Voert de batch uit en beëindigt en geeft geen waarde terug.

• :EXIT(query)

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

Als RAISERROR wordt gebruikt in een sqlcmd script en er een status van 127 wordt gegenereerd, wordt sqlcmd afgesloten en wordt de bericht-id teruggezet naar de client. 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 retourwaarden -1 aan -99 zijn gereserveerd door SQL Server en sqlcmd- definieert de volgende 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 door bestandsnaam opgegeven bestand in de instructiecache. bestandsnaam wordt gelezen ten opzichte van de opstartmap waarin sqlcmd- is uitgevoerd.

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

Het bestand wordt gelezen en uitgevoerd nadat er een batcheindteken is aangetroffen. 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]]

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

Time-outopties:

De SQLCMDSERVER scriptvariabele weerspiegelt de huidige actieve verbinding.

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

Als alleen user_name is opgegeven (als optie of als omgevingsvariabele), wordt de gebruiker 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

Als u verbinding wilt maken met het standaardexemplaren van myserver met behulp van scriptvariabelen, gebruikt u de volgende instellingen:

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

[:]!! opdracht

Hiermee worden besturingssysteemopdrachten uitgevoerd. 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.

:Hulp

Een lijst met sqlcmd opdrachten, samen met een korte beschrijving van elke opdracht.

sqlcmd-bestandsnamen

sqlcmd invoerbestanden kunnen worden opgegeven met de optie -i of de opdracht :r. Uitvoerbestanden kunnen worden opgegeven met de -o optie of de :Error, :Outen :Perftrace opdrachten. Hier volgen enkele richtlijnen voor het werken met deze bestanden:

• :Error, :Outen :Perftrace moet afzonderlijke bestandsnaamwaarden gebruiken. Als dezelfde bestandsnaam wordt gebruikt, kunnen invoeren van de opdrachten worden vermengd.

• Als een invoerbestand dat zich op een externe server bevindt, wordt aangeroepen vanuit sqlcmd op een lokale computer en het bestand een stationspad bevat, zoals :Out c:\OutputFile.txt, 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 alle informatieberichten afdrukken die door de server worden verzonden. In het volgende voorbeeld wordt, nadat de Transact-SQL instructies zijn uitgevoerd, een informatief bericht afgedrukt.

Start sqlcmd. Typ bij de opdrachtprompt sqlcmd de query:

USE AdventureWorks2022;
GO

Wanneer u op Enterdrukt, wordt het volgende informatieve bericht afgedrukt:

Changed database context to 'AdventureWorks2022'.

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 opgevuld met spaties tot aan de volgende kolom.

Deze regel wordt gevolgd door een scheidingsteken dat een reeks van streepjes is. In de volgende uitvoer ziet u een voorbeeld.

Start sqlcmd. Typ bij de opdrachtprompt sqlcmd de query:

USE AdventureWorks2022;

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

Wanneer u op Enter-drukt, wordt de volgende resultatenset geretourneerd.

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. Standaard wordt de uitvoer beëindigd met 80 tekens. Deze breedte kan worden gewijzigd met behulp van de optie -w 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 geen Transact-SQL instructies uitvoeren die reguliere rijenets 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 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