Partager via


sqlcmd (utilitaire)

S’applique à : SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW)

L'utilitaire sqlcmd vous permet d'entrer des instructions Transact-SQL, des procédures système et des fichiers de script dans différents modes :

  • À l'invite de commandes.
  • Dans l'l'éditeur de requête en mode SQLCMD.
  • Dans un fichier de script Windows.
  • Dans une étape de travail de système d'exploitation (cmd.exe) d'un travail SQL Server Agent.

Remarque

Bien que Microsoft Entra ID soit le nouveau nom d’Azure Active Directory (Azure AD) pour empêcher l’interruption des environnements existants, Azure AD reste toujours dans certains éléments codés en dur, tels que les champs d’interface utilisateur, les fournisseurs de connexions, les codes d’erreur et cmdlets. Dans cet article, les deux noms sont interchangeables.

Rechercher la version que vous avez installée

Il existe deux versions de sqlcmd :

  • Sqlcmd basé sur go-mssqldb, parfois présenté comme go-sqlcmd. Cette version est un outil autonome que vous pouvez télécharger indépendamment de SQL Server.

  • Sqlcmd basé sur ODBC, disponible avec SQL Server ou les utilitaires de ligne de commande Microsoft et partie du package mssql-tools sur Linux.

Pour déterminer la version que vous avez installée, exécutez l'instruction suivante sur la ligne de commande :

sqlcmd "-?"
sqlcmd "-?"
sqlcmd -?

Si vous utilisez la nouvelle version de sqlcmd (Go), la sortie est similaire à l'exemple suivant :

Version: 1.3.1

Vérifier la version

Vous pouvez utiliser sqlcmd --version pour déterminer la version installée. La version 1.0.0 ou ultérieure doit être installée.

Important

L'installation de sqlcmd (Go) par le biais d'un gestionnaire de package remplacera sqlcmd (ODBC) par sqlcmd (Go) dans le chemin d'accès de votre environnement. Toutes les sessions de ligne de commande actuelles devront être fermées et ouvertes de nouveau pour que cela prenne effet. sqlcmd (ODBC) ne sera pas supprimé et peut toujours être utilisé en spécifiant le chemin complet de l'exécutable. Vous pouvez également mettre à jour votre PATH variable pour indiquer laquelle sera prioritaire. Pour ce faire dans Windows 11, ouvrez Paramètres système et accédez à À propos des > paramètres système avancés. Lorsque Propriétés système s'ouvre, sélectionnez le bouton Variables d'environnement. Dans la moitié inférieure, sous Variables système, sélectionnez Chemin d'accès, puis Modifier. Si l'emplacement sqlcmd (Go) est enregistré dans (C:\Program Files\sqlcmd est par défaut) est répertorié avant C:\Program Files\Microsoft SQL Server\<version>\Tools\Binn, sqlcmd (Go) est alors utilisé. Vous pouvez inverser l'ordre pour rétablir sqlcmd (ODBC) comme valeur par défaut.

Télécharger et installer sqlcmd

sqlcmd (Go) peut être installé sur plusieurs plateformes, sur Microsoft Windows, macOS et Linux.

winget (interface CLI Windows Package Manager)

  1. Installez Windows Package Manager Client si ce n'est pas déjà fait.

  2. Exécutez la commande suivante pour installer sqlcmd (Go).

    winget install sqlcmd
    

Chocolatey

  1. Installez Chocolatey si ce n'est pas déjà fait.

  2. Exécutez la commande suivante pour installer sqlcmd (Go).

    choco install sqlcmd
    

Téléchargement direct

  1. Téléchargez la ressource -windows-x64.zip ou -windows-arm.zip correspondante à partir de la dernière version de go-sqlcmd dans le référentiel de code GitHub.

  2. Extrayez le fichier sqlcmd.exe à partir du dossier zip téléchargé.

Préinstallé

Azure Cloud Shell

Vous pouvez essayer l'utilitaire sqlcmd à partir d'Azure Cloud Shell, car il est préinstallé par défaut :

Azure Data Studio

Pour exécuter des instructions SQLCMD dans Azure Data Studio, sélectionnez Activer SQLCMD dans la barre d'outils de l'éditeur.

SQL Server Management Studio (SSMS)

Pour exécuter des instructions SQLCMD dans SQL Server Management Studio (SSMS), sélectionnez le mode SQLCMD dans la liste déroulante du menu Requête de la barre de navigation supérieure.

(SSMS) utilise le cadre Microsoft .NET SqlClient pour l'exécution en mode régulier et SQLCMD dans l'Éditeur de requête. Lorsque sqlcmd est exécuté à partir de la ligne de commande, sqlcmd utilise le pilote ODBC. Dans la mesure où différentes options par défaut peuvent s'appliquer, vous pouvez constater un comportement différent lorsque vous exécutez la même requête dans SSMS en mode SQLCMD et dans l'utilitaire sqlcmd.

Syntaxe

Usage:
  sqlcmd [flags]
  sqlcmd [command]

Examples:
# Install/Create, Query, Uninstall SQL Server
  sqlcmd create mssql --accept-eula --using https://aka.ms/AdventureWorksLT.bak
  sqlcmd open ads
  sqlcmd query "SELECT @@version"
  sqlcmd delete
# View configuration information and connection strings
  sqlcmd config view
  sqlcmd config cs

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  config      Modify sqlconfig files using subcommands like "sqlcmd config use-context mssql"
  create      Install/Create SQL Server, Azure SQL, and Tools
  delete      Uninstall/Delete the current context
  help        Help about any command
  open        Open tools (e.g ADS) for current context
  query       Run a query against the current context
  start       Start current context
  stop        Stop current context

Flags:
  -?, --?                  help for backwards compatibility flags (-S, -U, -E etc.)
  -h, --help               help for sqlcmd
      --sqlconfig string   configuration file (default "/Users/<currentUser>/.sqlcmd/sqlconfig")
      --verbosity int      log level, error=0, warn=1, info=2, debug=3, trace=4 (default 2)
      --version            print version of sqlcmd

Use "sqlcmd [command] --help" for more information about a command.

Pour en savoir plus sur la syntaxe et l'utilisation de sqlcmd, reportez-vous à Syntaxe sqlcmd ODBC.

Changements cassants de sqlcmd (ODBC)

Plusieurs commutateurs et comportements sont modifiés dans l'utilitaire sqlcmd (Go). Pour obtenir la liste la plus récente des indicateurs manquants à des fins de compatibilité descendante, reportez-vous à la discussion GitHub sur les indicateurs de compatibilité descendante à implémenter en priorité.

  • Dans les versions antérieures de sqlcmd (Go), le commutateur -P a été temporairement supprimé et les mots de passe pour l'authentification SQL Server ne peuvent être fournis que par le biais de ces mécanismes :

    • La variable d'environnement SQLCMDPASSWORD
    • La commande :CONNECT
    • Lorsque vous y êtes invité, l'utilisateur pourrait saisir le mot de passe pour terminer une connexion
  • -r nécessite un argument 0 ou 1

  • Le commutateur -R est supprimé.

  • Le commutateur -I est supprimé. Pour désactiver le comportement de l'identificateur entre guillemets, ajoutez SET QUOTED IDENTIFIER OFF à vos scripts.

  • -N prend maintenant une valeur de chaîne qui peut être l'un des true, false ou disable pour spécifier le choix de chiffrement. (default est identique à omettre le paramètre)

    • Si -N et -C ne sont pas fournis, sqlcmd négocie l'authentification avec le serveur sans valider le certificat de serveur.
    • Si -N est fourni, mais pas -C, sqlcmd exige la validation du certificat de serveur. Une valeur false pour le chiffrement peut toujours entraîner le chiffrement du paquet de connexions.
    • Si -N et -C sont fournis, sqlcmd utilise leurs valeurs pour la négociation de chiffrement.
    • Vous trouverez plus d'informations sur la négociation de chiffrement client/serveur à l'adresse MS-TDS PRELOGIN.
  • -u La marque d'ordre d'octet (BOM) Little-Endian UTF-16 est écrite sur le fichier de sortie Unicode généré.

  • Certains comportements conservés pour maintenir la compatibilité avec OSQL peuvent être modifiés, comme l'alignement des en-têtes de colonne pour certains types de données.

  • Toutes les commandes doivent s'adapter à une ligne, même EXIT. Le mode interactif ne vérifie pas les parenthèses ou les guillemets ouverts dans les commandes et n'invite pas à entrer des lignes successives. Ce comportement est différent de la version ODBC, ce qui permet à la requête d'être exécutée par EXIT(query) de s'étendre sur plusieurs lignes.

Les connexions depuis l'utilitaire sqlcmd (Go) sont limitées aux connexions TCP. Les canaux nommés ne sont pas pris en charge dans le pilote go-mssqldb pour l'instant.

Améliorations

  • :Connect dispose désormais d'un paramètre facultatif -G pour sélectionner l'une des méthodes d'authentification pour Azure SQL Database - SqlAuthentication, ActiveDirectoryDefault, ActiveDirectoryIntegrated, ActiveDirectoryServicePrincipal, ActiveDirectoryManagedIdentity, ActiveDirectoryPassword. Pour plus d’informations, consultez Authentification Microsoft Entra. Si -G n’est pas fourni, l’authentification par sécurité intégrée ou SQL Server est utilisée, selon qu’un paramètre de nom d’utilisateur -U est présent ou non.

  • Le nouveau paramètre de ligne de commande --driver-logging-level vous permet de voir les traces du pilote go-mssqldb. Utilisez 64 pour suivre toutes les traces.

  • sqlcmd peut désormais imprimer les résultats dans un format vertical. Utilisez le nouveau commutateur de ligne de commande -F vertical pour le définir. La variable de script SQLCMDFORMAT contrôle aussi cela.

Options de ligne de commande

-A

Se connecte à SQL Server avec une connexion administrateur dédiée (DAC). Ce type de connexion est utilisé pour dépanner un serveur. Cette connexion ne fonctionne qu'avec les serveurs prenant en charge DAC. Si DAC n'est pas disponible, sqlcmd génère un message d'erreur et se termine. Pour plus d'informations sur DAC, consultez Connexion de diagnostic pour les administrateurs de base de données. L'option -A n'est pas prise en charge avec l'option -G. Quand vous vous connectez à Azure SQL Database avec -A, vous devez être administrateur sur le serveur SQL logique. DAC n’est pas disponible pour un administrateur Microsoft Entra.

C-

Cette option est utilisée par le client pour le configurer afin d'approuver implicitement le certificat de serveur sans validation. Cette option est équivalente à l'option ADO.NET TRUSTSERVERCERTIFICATE = true.

Pour l'utilitaire sqlcmd (Go), les conditions suivantes s'appliquent également :

  • Si -N et -C ne sont pas fournis, sqlcmd négocie l'authentification avec le serveur sans valider le certificat de serveur.
  • Si -N est fourni, mais pas -C, sqlcmd exige la validation du certificat de serveur. Une valeur false pour le chiffrement peut toujours entraîner le chiffrement du paquet de connexions.
  • Si -N et -C sont fournis, sqlcmd utilise leurs valeurs pour la négociation de chiffrement.

-d db_name

Émet une instruction USE <db_name> quand vous démarrez sqlcmd. Cette option définit la variable de script sqlcmdSQLCMDDBNAME. Ce paramètre spécifie la base de données initiale. La valeur par défaut est la propriété de base de données par défaut de votre connexion. Si la base de données n'existe pas, un message d'erreur est généré et sqlcmd se termine.

-d

Interprète le nom du serveur fourni à -Scomme nom de source de données plutôt que nom d'hôte. Pour plus d'informations, consultez Prise en charge du nom de source de données dans sqlcmd et bcp dans Connexion avec sqlcmd.

Notes

L'option -D n'est disponible que sur les clients Linux et macOS. Sur les clients Windows, elle faisait précédemment référence à une option désormais obsolète qui a été supprimée et est ignorée.

-l délai_d'expiration_connexion

Spécifie le nombre de secondes au terme duquel une connexion sqlcmd au pilote ODBC expire quand vous tentez d'établir une connexion à un serveur. Cette option définit la variable de script sqlcmdSQLCMDLOGINTIMEOUT. Le délai d'expiration par défaut pour la connexion à sqlcmd est de 8 secondes. Si vous utilisez l’option -G pour vous connecter à Azure SQL Database ou à Azure Synapse Analytics et vous authentifier avec Microsoft Entra ID, il est recommandé d’utiliser une valeur de délai d’expiration d’au moins 30 secondes. Le délai d'expiration de la connexion doit être un nombre compris entre 0 et 65534. Si la valeur fournie n'est pas numérique ou ne se trouve pas dans cette plage, sqlcmd génère un message d'erreur. Une valeur de 0 spécifie un délai d'expiration infini.

-E

Utilise une connexion approuvée au lieu d'un nom d'utilisateur et d'un mot de passe pour se connecter à SQL Server. Par défaut, si -E n'est pas spécifié, sqlcmd utilise l'option de connexion approuvée.

L'option -E ignore les éventuels paramètres de variables d'environnement de nom d'utilisateur et de mot de passe tels que SQLCMDPASSWORD. Si l'option -E est utilisée avec l'option -U ou l'option -P, un message d'erreur est généré.

-g

Définissez le paramètre de chiffrement de colonne sur Enabled. Pour plus d'informations, consultez Always Encrypted. Uniquement les clés principales stockées dans le magasin de certificats Windows sont prises en charge. L'option -g nécessite au moins sqlcmd version 13.1. Pour déterminer votre version, exécutez sqlcmd -?.

-G

Le client utilise cette option lors de la connexion à Azure SQL Database ou Azure Synapse Analytics pour faire en sorte que l’utilisateur doit être authentifié à l’aide de l’authentification Microsoft Entra. Cette option définit la variable de script sqlcmdSQLCMDUSEAAD = true. Le commutateur -G nécessite au moins sqlcmd version 13.1. Pour déterminer votre version, exécutez sqlcmd -?. Pour plus d’informations, consultez Connexion à SQL Database ou Azure Synapse Analytics à l’aide de l’authentification Microsoft Entra. L'option -A n'est pas prise en charge avec l'option -G.

L'option -G s'applique uniquement à Azure SQL Database et à Azure Synapse Analytics.

L'authentification interactive Microsoft Entra n'est actuellement prise en charge ni sur Linux ni sur macOS. L’authentification intégrée Microsoft Entra requiert la version 17.6.1 ou une version ultérieure du pilote ODBC Microsoft 17 pour SQL Server et un environnement Kerberos correctement configuré.

Pour plus d’informations sur l’authentification Microsoft Entra dans Azure SQL, consultez Authentification Microsoft Entra dans sqlcmd.

-H nom_station_travail

Nom d'une station de travail. Cette option définit la variable de script sqlcmdSQLCMDWORKSTATION. Le nom de la station de travail est listé dans la colonne hostname de la vue catalogue sys.sysprocesses et peut être retourné à l'aide de la procédure stockée sp_who. Si cette option n'est pas spécifiée, le nom de l'ordinateur actif est utilisé par défaut. Ce nom peut être utilisé pour identifier différentes sessions sqlcmd .

-j

Imprime des messages d'erreur bruts à l'écran.

-K intention_application

Déclare le type de la charge de travail de l'application lors de la connexion à un serveur. La seule valeur actuellement prise en charge est ReadOnly. Si -K n'est pas spécifié, sqlcmd ne prend pas en charge la connectivité à un réplica secondaire dans un groupe de disponibilité. Pour plus d'informations, consultez Secondaires actifs : réplicas secondaires lisibles (groupes de disponibilité Always On).

-M basculement_plusieurs_sous-réseaux

Spécifiez toujours -M en cas de connexion à l'écouteur de groupe de disponibilité d'un groupe de disponibilité SQL Server ou d'une instance de cluster de basculement SQL Server. -M fournit une détection plus rapide du serveur actif et une connexion à celui-ci. Si -M n'est pas spécifié, -M est désactivé. Pour plus d'informations sur Écouteurs, connectivité client et basculement d'application, Création et configuration des groupes de disponibilité (SQL Server), Clustering de basculement et groupes de disponibilité AlwaysOn (SQL Server), et Secondaires actifs : réplicas secondaires lisibles (groupes de disponibilité AlwaysOn).

-n

Cette option est utilisée par le client pour demander une connexion chiffrée.

Pour l'utilitaire sqlcmd (Go), -N prend désormais une valeur de chaîne qui peut être l'un des true, false, ou disable pour spécifier le choix de chiffrement. (default est identique à l'omission de paramètre) :

  • Si -N et -C ne sont pas fournis, sqlcmd négocie l'authentification avec le serveur sans valider le certificat de serveur.
  • Si -N est fourni, mais pas -C, sqlcmd exige la validation du certificat de serveur. Une valeur false pour le chiffrement peut toujours entraîner le chiffrement du paquet de connexions.
  • Si -N et -C sont fournis, sqlcmd utilise leurs valeurs pour la négociation de chiffrement.

-P password

Mot de passe spécifié par l'utilisateur. Les mots de passe respectent la casse. Lorsque l'option -U est utilisée, que l'option -P n'est pas utilisée et que la variable d'environnement SQLCMDPASSWORD n'est pas définie, sqlcmd demande un mot de passe à l'utilisateur. Nous déconseillons d'utiliser le mot de passe Null (vide), mais vous pouvez le spécifier en utilisant une paire de guillemets doubles contigus pour la valeur du paramètre ("").

Important

L'utilisation de -P doit être considérée comme non sécurisée. Évitez de donner le mot de passe sur la ligne de commande. Vous pouvez également utiliser la variable d'environnement SQLCMDPASSWORD ou entrer de manière interactive le mot de passe en omettant l'option -P.

Nous vous recommandons d'utiliser un mot de passe fort.

L'invite de mot de passe s'affiche en imprimant l'invite de commande sur la console, comme suit : Password:

L'entrée de l'utilisateur est masquée, ce qui signifie que rien ne s'affiche et que le curseur reste immobile.

La variable d'environnement SQLCMDPASSWORD vous permet de définir un mot de passe par défaut pour la session active. Par conséquent, les mots de passe n'ont pas besoin d'être codés en dur dans des fichiers de commandes. L'exemple suivant définit d'abord la variable SQLCMDPASSWORD à l'invite de commandes, puis accède à l'utilitaire sqlcmd.

À l'invite de commandes, tapez :

SET SQLCMDPASSWORD=p@a$$w0rd
sqlcmd
SET SQLCMDPASSWORD=p@a$$w0rd
sqlcmd
SET SQLCMDPASSWORD=p@a$$w0rd
sqlcmd

Si la combinaison de nom d'utilisateur et de mot de passe est incorrecte, un message d'erreur est généré.

Notes

La variable d'environnement OSQLPASSWORD a été conservée à des fins de compatibilité descendante. La variable d'environnement SQLCMDPASSWORD est prioritaire sur la variable d'environnement OSQLPASSWORD. Il est donc possible d'utiliser sqlcmd et osql côte à côte sans interférence. Les anciens scripts continueront à fonctionner.

Si l'option -P est utilisée avec l'option -E, un message d'erreur est généré.

Si l'option -P est suivie de plusieurs arguments, un message d'erreur est généré et le programme se termine.

Un mot de passe contenant des caractères spéciaux peut générer un message d'erreur. Vous devez échapper des caractères spéciaux lors de l'utilisation de -P ou utiliser la variable d'environnement SQLCMDPASSWORD à la place.

-S [protocole:]serveur[\nom_instance][,port]

Spécifie l'instance de SQL Server à laquelle se connecter. Définit la variable de script sqlcmdSQLCMDSERVER.

Spécifiez nom_serveur pour vous connecter à l'instance par défaut de SQL Server sur cet ordinateur serveur. Spécifiez nom_serveur[\nom_instance] pour vous connecter à une instance nommée de SQL Server sur cet ordinateur serveur. Si aucun ordinateur serveur n'est spécifié, sqlcmd se connecte à l'instance par défaut de SQL Server sur l'ordinateur local. Cette option est indispensable lorsque vous exécutez sqlcmd à partir d'un ordinateur distant connecté au réseau.

Leprotocole peut avoir la valeur tcp (TCP/IP), lpc (mémoire partagée) ou np (canaux nommés).

Si vous ne spécifiez pas nom_serveur[\nom_instance] quand vous démarrez sqlcmd, SQL Server recherche et utilise la variable d'environnement SQLCMDSERVER.

Notes

La variable d'environnement OSQLSERVER a été conservée à des fins de compatibilité descendante. La variable d'environnement SQLCMDSERVER est prioritaire sur la variable d'environnement OSQLSERVER. Il est donc possible d'utiliser sqlcmd et osql côte à côte sans interférence. Les anciens scripts continueront à fonctionner.

-U login_id

Nom de connexion ou nom d'utilisateur de la base de données autonome. Pour les utilisateurs de bases de données autonomes, vous devez fournir l'option de nom de base de données (-d).

Notes

La variable d'environnement OSQLUSER a été conservée à des fins de compatibilité descendante. La variable d'environnement SQLCMDUSER est prioritaire sur la variable d'environnement OSQLUSER. Il est donc possible d'utiliser sqlcmd et osql côte à côte sans interférence. Les anciens scripts continueront à fonctionner.

Si vous ne spécifiez ni l'option -U ni l'option -P, sqlcmd essaie de se connecter en utilisant le mode d'authentification Windows. L'authentification est basée sur le compte Windows de l'utilisateur exécutant sqlcmd.

Si l'option -U est utilisée avec l'option -E (décrite plus loin dans cet article), un message d'erreur est généré. Si l'option -U est suivie de plusieurs arguments, un message d'erreur est généré et le programme se termine.

-z nouveau_mot_de_passe

Pour changer le mot de passe :

sqlcmd -U someuser -P s0mep@ssword -z a_new_p@a$$w0rd
sqlcmd -U someuser -P s0mep@ssword -z a_new_p@a$$w0rd
sqlcmd -U someuser -P s0mep@ssword -z a_new_p@a$$w0rd

-Z nouveau_mot_de_passe

Pour changer le mot de passe et quitter :

sqlcmd -U someuser -P s0mep@ssword -Z a_new_p@a$$w0rd
sqlcmd -U someuser -P s0mep@ssword -Z a_new_p@a$$w0rd
sqlcmd -U someuser -P s0mep@ssword -Z a_new_p@a$$w0rd

Options d'entrée/sortie

-f page_de_codes | i:page_de_codes[,o:page_de_codes] | o:page_de_codes[,i:page_de_codes]

Spécifie les pages de codes d'entrée et de sortie. Le numéro de pages de codes est une valeur numérique spécifiant une page de codes Windows installée.

Règles de conversion des pages de code :

  • Si aucune page de codes n'est spécifiée, sqlcmd utilise la page de codes active pour le fichier d'entrée et le fichier de sortie, sauf si le fichier d'entrée est un fichier Unicode, auquel cas aucune conversion n'est requise.

  • sqlcmd reconnaît automatiquement les fichiers d'entrée Unicode Big-endian et Little-endian. Si l'option -u est spécifiée, la sortie est toujours de type Unicode Little Endian.

  • Si aucun fichier de sortie n'est spécifié, la page de codes de sortie correspond à la page de codes de la console. Cette approche permet aux données de sortie d'être correctement affichées sur la console.

  • Plusieurs fichiers d'entrée sont supposés correspondre à une même page de codes. Les fichiers d'entrée Unicode et non Unicode peuvent être mélangés.

Entrez chcp à l'invite de commandes pour vérifier la page de codes de cmd.exe.

-i fichier_entrée[,fichier_entrée2...]

Identifie le fichier qui contient un lot d'instructions Transact-SQL ou de procédures stockées. Vous pouvez spécifier plusieurs fichiers qui sont lus et traités dans l'ordre. N'utilisez pas d'espace entre les noms de fichiers. sqlcmd vérifie d'abord si tous les fichiers spécifiés existent. Si un ou plusieurs fichiers n'existent pas, sqlcmd se termine. Les options -i et -Q/-q s'excluent mutuellement.

Exemples de chemins :

-i C:\<filename>
-i \\<Server>\<Share$>\<filename>
-i "C:\Some Folder\<file name>"

Les chemins d'accès aux fichiers comportant des espaces doivent être placés entre guillemets.

Cette option peut être utilisée plusieurs fois :

sqlcmd -i <input_file1> -i <input_file2>
sqlcmd -i <input_file1> -i <input_file2>
sqlcmd -i <input_file1> -i <input_file2>

-o output_file

Identifie le fichier recevant une sortie de sqlcmd.

Si -u est spécifié, le fichier_sortie est stocké au format Unicode. Si le nom de fichier n'est pas valide, un message d'erreur est généré et sqlcmd se termine. sqlcmd ne prend pas en charge l'écriture simultanée de plusieurs processus sqlcmd dans le même fichier. La sortie fichier est endommagée ou incorrecte. L'option -f s'applique également aux formats de fichiers. Ce fichier est créé s'il n'existe pas. Un fichier portant le même nom qui provient d'une session sqlcmd antérieure est remplacé. Le fichier spécifié ici n'est pas le fichier stdout. Si un fichier stdout est spécifié, ce fichier n'est pas utilisé.

Exemples de chemins :

-o C:< filename>
-o \\<Server>\<Share$>\<filename>
-o "C:\Some Folder\<file name>"

Les chemins d'accès aux fichiers comportant des espaces doivent être placés entre guillemets.

-r[0 | 1]

Redirige la sortie des messages d'erreur à l'écran (stderr). Si vous n'indiquez aucun paramètre ou si vous spécifiez la valeur 0, seuls les messages d'erreur avec un degré de gravité égal ou supérieur à 11 sont redirigés. Si vous spécifiez 1, toutes les sorties de message d'erreur, notamment PRINT, sont redirigées. Cette option n'a aucun effet si vous utilisez -o. Par défaut, les messages sont envoyés à stdout.

Remarque

Pour l'utilitaire sqlcmd (Go), -r nécessite un argument 0 ou 1.

-R

S'applique à : ODBC sqlcmd uniquement.

Demande à sqlcmd de localiser les colonnes numériques, de devise, de date et heure récupérées auprès de SQL Server, en fonction des paramètres régionaux du client. Par défaut, ces colonnes sont affichées à l'aide des paramètres régionaux du serveur.

-U

Spécifie le stockage de fichier_sortie au format Unicode, quel que soit le format de fichier_entrée.

Remarque

Pour l'utilitaire sqlcmd (Go), la marque d'ordre d'octet (BOM) Little-Endian UTF-16 est écrite sur le fichier de sortie Unicode généré.

Options relatives à l'exécution de requêtes

-E

Écrit des scripts d'entrée sur l'appareil de sortie standard (stdout).

-I

S'applique à : ODBC sqlcmd uniquement.

Définit l'option de connexion SET QUOTED_IDENTIFIER sur ON. OFF est sélectionné par défaut. Pour plus d'informations, consultez SET QUOTED_IDENTIFIER (Transact-SQL).

Remarque

Pour désactiver le comportement des Identificateurs entre guillemets dans l'utilitaire sqlcmd (Go), ajoutez SET QUOTED IDENTIFIER OFF dans vos scripts.

-q "requête cmdline"

Exécute une requête au démarrage de sqlcmd, mais ne quitte pas sqlcmd au terme de l'exécution de la requête. Il est possible d'exécuter des requêtes séparées par plusieurs points-virgules. Placez la requête entre guillemets, comme dans l'exemple suivant.

À l'invite de commandes, tapez :

sqlcmd -d AdventureWorks2022 -q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"

sqlcmd -d AdventureWorks2022 -q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"
sqlcmd -d AdventureWorks2022 -q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"

sqlcmd -d AdventureWorks2022 -q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"
sqlcmd -d AdventureWorks2022 -q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"

sqlcmd -d AdventureWorks2022 -q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"

Important

N'utilisez pas le terminateur GO dans la requête.

Si l'option -b est spécifiée avec cette option, sqlcmd se termine avec une erreur. -b est décrit autre part dans cet article.

-Q "requête cmdline"

Exécute une requête quand sqlcmd démarre, puis quitte immédiatement sqlcmd. Il est possible d'exécuter des requêtes séparées par plusieurs points-virgules.

Placez la requête entre guillemets, comme dans l'exemple suivant.

À l'invite de commandes, tapez :

sqlcmd -d AdventureWorks2022 -Q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"

sqlcmd -d AdventureWorks2022 -Q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"
sqlcmd -d AdventureWorks2022 -Q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"

sqlcmd -d AdventureWorks2022 -Q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"
sqlcmd -d AdventureWorks2022 -Q "SELECT FirstName, LastName FROM Person.Person WHERE LastName LIKE 'Whi%';"

sqlcmd -d AdventureWorks2022 -Q "SELECT TOP 5 FirstName FROM Person.Person;SELECT TOP 5 LastName FROM Person.Person;"

Important

N'utilisez pas le terminateur GO dans la requête.

Si l'option -b est spécifiée avec cette option, sqlcmd se termine avec une erreur. -b est décrit autre part dans cet article.

-t query_timeout

Spécifie le nombre de secondes avant l'expiration d'une commande (ou d'une instruction Transact-SQL). Cette option définit la variable de script sqlcmdSQLCMDSTATTIMEOUT. Si une valeur délai_expiration_requête n'est pas spécifiée, la commande n'expire pas. La valeur délai_expiration_requête doit être un nombre compris entre 1 et 65534. Si la valeur fournie n'est pas numérique ou n'est pas comprise dans cet intervalle, sqlcmd génère un message d'erreur.

Notes

La valeur de délai d'expiration réelle peut différer de quelques secondes de la valeur délai_expiration_requête.

-v var = valeur [ var = valeur... ]

Crée une variable de script sqlcmd qui peut être utilisée dans un script sqlcmd. Placez la valeur entre guillemets si elle contient des espaces. Vous pouvez spécifier plusieurs valeurs <var>="<value>". Si l'une des valeurs spécifiées comporte des erreurs, sqlcmd génère un message d'erreur et se termine.

sqlcmd -v MyVar1=something MyVar2="some thing"

sqlcmd -v MyVar1=something -v MyVar2="some thing"
sqlcmd -v MyVar1=something MyVar2="some thing"

sqlcmd -v MyVar1=something -v MyVar2="some thing"
sqlcmd -v MyVar1=something MyVar2="some thing"

sqlcmd -v MyVar1=something -v MyVar2="some thing"

-X

Demande à sqlcmd d'ignorer les variables de script. Ce paramètre s'avère utile quand un script contient de nombreuses instructions INSERT pouvant contenir des chaînes au même format que les variables normales, par exemple $(<variable_name>).

Options de format

-h en-têtes

Spécifie le nombre de lignes à imprimer entre les en-têtes de colonne. Par défaut, les en-têtes ne sont imprimés qu'une fois pour chaque jeu de résultats d'une requête. Cette option définit la variable de script sqlcmdSQLCMDHEADERS. Utilisez -1 pour indiquer qu'aucun en-tête ne doit être imprimé. En présence d'une valeur non valide, sqlcmd génère un message d'erreur et se termine.

-k [1 | 2]

Supprime de la sortie tous les caractères de contrôle, par exemple les tabulations et les caractères de nouvelle ligne. Ce paramètre préserve la mise en forme des colonnes lorsque des données sont retournées.

  • -k supprime les caractères de contrôle.
  • -k1 remplace chaque caractère de contrôle par un espace.
  • -k2 remplace les caractères de contrôle consécutifs par un espace unique.

-s séparateur_colonne

Spécifie le caractère de séparation des colonnes. Le caractère espace est utilisé par défaut. Cette option définit la variable de script sqlcmdSQLCMDCOLSEP. Pour utiliser des caractères ayant une signification particulière pour le système d'exploitation, tels que l'esperluette (&) ou le point-virgule (;), mettez le caractère entre guillemets ("). Le séparateur des colonnes peut être n'importe quel caractère 8 bits.

-w largeur_écran

Spécifie la largeur d'écran pour la sortie. Cette option définit la variable de script sqlcmdSQLCMDCOLWIDTH. La largeur de colonne doit être un nombre supérieur à 8 et inférieur à 65536. Si la largeur de colonne spécifiée n'est pas comprise dans cette plage, sqlcmd génère un message d'erreur. La largeur par défaut est de 80 caractères. Lorsque la longueur d'une ligne de sortie est supérieure à la largeur de colonne spécifiée, elle revient à la ligne suivante.

-w

Cette option supprime les espaces à droite d'une colonne. Utilisez cette option avec l'option -s lors de la préparation des données à exporter vers une autre application. Vous ne pouvez pas l'utiliser avec l'option -y ou -Y.

-y variable_length_type_display_width

Définit la variable de script sqlcmdSQLCMDMAXVARTYPEWIDTH. Par défaut, il s'agit de 256. Elle limite le nombre de caractères retournés pour les types de données de longueur variable importante :

  • varchar(max)
  • nvarchar(max)
  • varbinary(max)
  • xml
  • types de données définis par l'utilisateur (UDT)
  • text
  • ntext
  • image

Les types UDT peuvent être de longueur fixe, selon la mise en œuvre. Si cette longueur d'un type UDT à longueur fixe est inférieure à largeur_affichage, la valeur du type UDT retournée n'est pas affectée. Cependant, si la longueur est supérieure à largeur_affichage, la sortie est tronquée.

Attention

Utilisez l'option -y 0 avec une extrême prudence, car elle peut créer de graves problèmes de performances sur le serveur et le réseau en fonction de la taille des données retournées.

-Y fixed_length_type_display_width

Définit la variable de script sqlcmdSQLCMDMAXFIXEDTYPEWIDTH. La valeur par défaut est 0 (illimitée). Limite le nombre de caractères retournés pour les types de données suivants :

  • char(n), où 1 <= n<= 8000
  • nchar(n), où 1 <= n<= 4000
  • varchar(n), où 1 <= n<= 8000
  • nvarchar(n), où 1 <= n<= 4000
  • varbinary(n), où 1 <= n<= 4000
  • sql_variant

Options relatives aux rapports d'erreurs

-b

Spécifie que sqlcmd se termine et retourne une valeur DOS ERRORLEVEL quand une erreur se produit. La valeur retournée à la variable ERRORLEVEL est 1 quand le niveau de gravité du message d'erreur SQL Server est supérieur à 10. Sinon, la valeur retournée est 0. Si l'option -V est définie en plus de -b, sqlcmd ne signale pas d'erreur si le niveau de gravité est inférieur aux valeurs définies avec -V. Les fichiers de commandes à l'invite de commandes peuvent tester la valeur de ERRORLEVEL et gérer l'erreur de manière appropriée. sqlcmd ne signale pas les erreurs pour le niveau de gravité 10 (messages d'information).

Si le script sqlcmd contient un commentaire incorrect, une erreur de syntaxe ou une variable de script manquante, la valeur ERRORLEVEL retournée est 1.

-m error_level

Contrôle les messages d'erreur envoyés à stdout. Les messages assortis d'un niveau de gravité supérieur ou égal à ce niveau sont envoyés. Quand cette valeur est égale à -1, tous les messages, notamment les messages d'information, sont envoyés. Les espaces ne sont pas autorisés entre -m et -1. Par exemple, -m-1 est valide, mais pas -m -1.

Cette option définit la variable de script sqlcmdSQLCMDERRORLEVEL. Cette variable a une valeur par défaut de 0.

-V error_severity_level

Contrôle le niveau de gravité utilisé pour définir la variable ERRORLEVEL. Les messages d'erreur assortis de niveaux de gravité supérieurs ou égaux à cette valeur définissent ERRORLEVEL. Les valeurs inférieures à 0 sont signalées comme étant égales à 0. La valeur de la variable ERRORLEVEL peut être testée au moyen de fichiers de commandes et CMD.

Options diverses

-a packet_size

Demande un paquet d'une taille différente. Cette option définit la variable de script sqlcmdSQLCMDPACKETSIZE. taille_paquet doit être une valeur comprise entre 512 et 32767. Par défaut, il s'agit de 4096. Une plus grande taille de paquet peut améliorer les performances d'exécution des scripts comportant un grand nombre d'instructions Transact-SQL entre des commandes GO. Vous pouvez demander une taille de paquet plus élevée. Cependant, si la requête est refusée, sqlcmd adopte la taille par défaut du serveur comme taille de paquet.

-c batch_terminator

Spécifie le terminateur de traitement. Par défaut, vous devez taper le mot GO sur une ligne isolée pour terminer une commande et l'envoyer à SQL Server. Quand vous réinitialisez le terminateur du lot, n'utilisez pas de mots clés réservés de Transact-SQL ou des caractères ayant une signification particulière pour le système d'exploitation, même s'ils sont précédés d'une barre oblique inverse.

-L[c]

Répertorie tous les serveurs configurés localement et le nom des serveurs diffusant sur le réseau. Ce paramètre ne peut pas être utilisé en combinaison avec d'autres paramètres. Le nombre maximal de serveurs pouvant être répertoriés est de 3000. Si la liste de serveurs est tronquée en raison de la taille de la mémoire tampon, un message d'avertissement s'affiche.

Notes

Compte tenu de la nature de la diffusion sur les réseaux, il est possible que sqlcmd ne reçoive pas de réponse de tous les serveurs dans les délais impartis. Par conséquent, la liste des serveurs retournée peut varier à chaque invocation de cette option.

Si le paramètre optionnel c est spécifié, la sortie s'affiche sans les Servers: : la ligne d'en-tête et chaque ligne de serveur apparaissent sans espace de début. Cette présentation est qualifiée comme « propre ». Une sortie propre améliore les performances de traitement des langages de script.

-p[1]

Imprime des statistiques de performances pour chaque jeu de résultats. L'écran suivant illustre le format des statistiques de performances :

Network packet size (bytes): n

x xact[s]:

Clock Time (ms.): total       t1  avg       t2 (t3 xacts per sec.)

Où :

  • x = Nombre de transactions traitées par SQL Server.
  • t1 = Durée totale de toutes les transactions.
  • t2 = Durée moyenne d'une transaction spécifique.
  • t3 = Nombre moyen de transactions par seconde.

Toutes les durées sont exprimées en millisecondes.

Si le paramètre facultatif 1 est spécifié, les statistiques sont séparées par deux points et peuvent être aisément importées dans une feuille de calcul ou traitées par un script.

Si le paramètre facultatif correspond à n'importe quelle valeur autre que 1, une erreur est générée et sqlcmd se termine.

-X[1]

Désactive les commandes pouvant compromettre la sécurité du système quand sqlcmd est exécuté à partir d'un fichier de commandes. Les commandes désactivées sont toujours reconnues ; sqlcmd émet un message d'avertissement et continue. Si le paramètre facultatif 1 est spécifié, sqlcmd génère un message d'erreur, puis il se termine. Les commandes suivantes sont désactivées lorsque l'option -X est utilisée :

  • ED
  • Command !! command

Si l'option -X est spécifiée, elle empêche le passage des variables d'environnement à sqlcmd. Elle interdit également l'exécution du script de démarrage spécifié au moyen de la variable de script SQLCMDINI. Pour plus d'informations sur les variables de script sqlcmd, consultez sqlcmd : utiliser avec des variables de script.

-?

Affiche la version de sqlcmd et un résumé de la syntaxe des options de sqlcmd .

Remarque

Sur macOS, exécutez sqlcmd '-?' (avec des guillemets) à la place.

Notes

Les options ne doivent pas nécessairement être utilisées dans l'ordre indiqué dans la section de la syntaxe.

Lorsque plusieurs résultats sont retournés, sqlcmd imprime une ligne vide entre chaque ensemble de résultats dans un traitement. En outre, le message <x> rows affected ne s'affiche pas lorsqu'il ne concerne pas l'instruction exécutée.

Pour utiliser sqlcmd de façon interactive, tapez sqlcmd dans l'invite de commandes avec une ou plusieurs des options décrites plus haut dans cet article. Pour plus d'informations, consultez Utiliser l'utilitaire sqlcmd.

Notes

Les options -l, -Q, -Z et -i entraîne la fermeture de sqlcmd après l'exécution.

La longueur totale de la ligne de commande sqlcmd dans l'environnement de commande (par exemple cmd.exe ou bash), comprenant tous les arguments et variables développées, est déterminée par le système d'exploitation sous-jacent.

Priorité des variables (faible à élevée)

  1. Variables d'environnement de niveau système
  2. Variables d'environnement au niveau de l'utilisateur.
  3. Interpréteur de commandes (SET X=Y) défini à l'invite de commandes avant l'exécution de sqlcmd
  4. sqlcmd -v X=Y
  5. :Setvar X Y

Notes

Pour afficher les variables d'environnement, dans le Panneau de configuration, ouvrez Système, puis sélectionnez l'onglet Avancé.

Variables de script sqlcmd

Variable Option connexe R/W (Lecture/écriture) Default
SQLCMDUSER -U R ""
SQLCMDPASSWORD -P -- ""
SQLCMDSERVER -S R "DefaultLocalInstance"
SQLCMDWORKSTATION -H R "ComputerName"
SQLCMDDBNAME -d R ""
SQLCMDLOGINTIMEOUT -l R/W (Lecture/écriture) "8" (secondes)
SQLCMDSTATTIMEOUT -T R/W (Lecture/écriture) "0" = Attendre indéfiniment
SQLCMDHEADERS -H R/W (Lecture/écriture) "0"
SQLCMDCOLSEP -S R/W (Lecture/écriture) " "
SQLCMDCOLWIDTH -w R/W (Lecture/écriture) "0"
SQLCMDPACKETSIZE -a R "4096"
SQLCMDERRORLEVEL -M R/W (Lecture/écriture) 0
SQLCMDMAXVARTYPEWIDTH -y R/W (Lecture/écriture) "256"
SQLCMDMAXFIXEDTYPEWIDTH -y R/W (Lecture/écriture) "0" = illimitée
SQLCMDEDITOR R/W (Lecture/écriture) "edit.com"
SQLCMDINI R ""
SQLCMDUSEAAD -G R/W (Lecture/écriture) ""

Les variables SQLCMDUSER, SQLCMDPASSWORD et SQLCMDSERVER sont définies quand :Connect est utilisé.

R indique que la valeur ne peut être définie qu'une seule fois lors de l'initialisation du programme.

R/W indique que la valeur peut être modifiée à l'aide de la commande :setvar et que les commandes ultérieures sont conditionnées par la nouvelle valeur.

commandes sqlcmd

En complément des instructions Transact-SQL dans sqlcmd, vous pouvez également utiliser les commandes suivantes :

GO [ nombre ]

:List

[:]RESET

:Error

[:]ED

:Out

[:]!!

:Perftrace

[:]QUIT

:Connect

[:]EXIT

:On Error

:r

:Help

:ServerList

:XML [ ON | OFF ]

:Setvar

:Listvar

Tenez compte des éléments suivants lorsque vous utilisez des commandes sqlcmd :

  • Toutes les commandes sqlcmd, à l'exception de GO, doivent être précédées d'un signe deux-points (:).

    Important

    Pour assurer la compatibilité descendante avec les scripts osql existants, certaines commandes sont reconnues sans les deux-points. Elles sont indiquées par :.

  • Les commandessqlcmd ne sont reconnues que si elles apparaissent au début d'une ligne.

  • Toutes les commandes sqlcmd ne respectent pas la casse.

  • Chaque commande doit figurer sur une ligne séparée. Une commande ne peut pas être suivie d'une instruction Transact-SQL ou d'une autre commande.

  • Les commandes sont exécutées immédiatement. Elles ne sont pas placées dans le tampon d'exécution comme le sont les instructions Transact-SQL.

Commandes d'édition

[:]ED

Démarre l'éditeur de texte. Cet éditeur peut être utilisé pour modifier le lot Transact-SQL actif ou le dernier lot exécuté. Pour modifier le dernier traitement exécuté, la commande ED doit être tapée immédiatement après la fin de l'exécution du dernier traitement.

L'éditeur de texte est défini par la variable d'environnement SQLCMDEDITOR. L'éditeur par défaut est Edit. Pour changer d'éditeur, définissez la variable d'environnement SQLCMDEDITOR. Par exemple, pour choisir l'éditeur Bloc-notes de Microsoft, à l'invite de commandes, tapez :

SET SQLCMDEDITOR=notepad

[:]RESET

Vide le cache d'instruction.

:List

Imprime le contenu du cache d'instruction.

Variables

:Setvar <var> [ "valeur" ]

Définit les variables de script sqlcmd . Les variables de script possèdent le format suivant : $(VARNAME).

Les noms de variable ne respectent pas la casse.

Les variables de script peuvent être définies comme suit :

  • Implicitement à l'aide d'une option de ligne de commande. Par exemple, l'option -l définit la variable SQLCMDLOGINTIMEOUT sqlcmd.

  • Explicitement à l'aide de la commande :Setvar .

  • En définissant une variable d'environnement avant d'exécuter sqlcmd.

Notes

L'option -X empêche le passage des variables d'environnement à sqlcmd.

Si une variable définie à l'aide de :Setvar et une variable d'environnement possèdent le même nom, la variable définie à l'aide de :Setvar est prioritaire.

Les noms de variable ne doivent pas contenir de caractères espace.

Les noms de variables ne peuvent pas avoir la même forme qu'une expression variable telle que $(var).

Si une valeur de chaîne de la variable de script contient des espaces, placez la valeur entre guillemets. Si aucune valeur n'est spécifiée pour une variable de script, cette dernière est supprimée.

:Listvar

Affiche la liste des variables de script actuellement définies.

Notes

Seules les variables de script qui sont définies par sqlcmdet celles qui sont définies avec la commande :Setvar s'affichent.

Commandes de sortie

:Error <nom_fichier> | STDERR | STDOUT

Redirige l'ensemble de la sortie d'erreur vers le fichier spécifié par nom_fichier vers stderr ou stdout. La commande :Error peut apparaître plusieurs fois dans un script. Par défaut, la sortie d'erreur est envoyée à stderr.

  • filename

    Crée et ouvre un fichier qui reçoit la sortie. Si le fichier existe déjà, il est tronqué à zéro octet. Si le fichier n'est pas disponible car des autorisations sont requises, ou pour d'autres raisons, la sortie n'est pas modifiée et est envoyée à la dernière destination spécifiée ou à celle par défaut.

  • STDERR

    Dirige la sortie d'erreur vers le flux stderr. En cas de redirection, la cible vers laquelle le flux est redirigé reçoit la sortie d'erreur.

  • STDOUT

    Dirige la sortie d'erreur vers le flux stdout. En cas de redirection, la cible vers laquelle le flux est redirigé reçoit la sortie d'erreur.

:Out <nom_fichier> | STDERR | STDOUT

Crée et redirige l'ensemble des résultats de requête dans le fichier spécifié par nom_fichiervers stderr ou vers stdout. Par défaut, la sortie est envoyée à stdout. Si le fichier existe déjà, il est tronqué à zéro octet. La commande :Out peut apparaître plusieurs fois dans un script.

:Perftrace <nom_fichier> | STDERR | STDOUT

Crée et redirige l'ensemble des informations de traces de performances dans le fichier spécifié par nom_fichiervers stderr ou vers stdout. Par défaut, la sortie de traces de performances est envoyée à stdout. Si le fichier existe déjà, il est tronqué à zéro octet. La commande :Perftrace peut apparaître plusieurs fois dans un script.

Commandes de contrôle d'exécution

:On Error [ exit | ignore ]

Définit l'action à effectuer lorsqu'une erreur se produit en cours de script ou d'exécution d'un traitement.

Quand l'option exit est utilisée, sqlcmd se termine avec la valeur d'erreur appropriée.

Quand l'option ignore est utilisée, sqlcmd ignore l'erreur et continue d'exécuter le lot ou le script. Par défaut, un message d'erreur est imprimé.

[:]QUIT

Entraîne la fermeture de sqlcmd .

[:]EXIT [ ( instruction ) ]

Vous permet d'utiliser le résultat d'une instruction SELECT comme valeur de retour de sqlcmd. S'il est numérique, la première colonne de la dernière ligne de résultats est convertie en un entier de 4 octets (entier long). MS-DOS, Linux et macOS passent l'octet de poids faible au processus parent ou au niveau erreur du système d'exploitation. Windows 2000 et versions ultérieures passent la totalité de l'entier 4 octets. La syntaxe est :EXIT(query).

Par exemple :

:EXIT(SELECT @@ROWCOUNT)

Vous pouvez également inclure le paramètre :EXIT dans un fichier de commandes. Par exemple, à l'invite de commandes, tapez :

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

L'utilitaire sqlcmd envoie tout le contenu entre parenthèses (()) au serveur. Si une procédure stockée système sélectionne un ensemble et retourne une valeur, seule la sélection est retournée. L'instruction :EXIT() sans information entre parenthèses exécute tout ce qui la précède dans le lot, puis se termine sans valeur de retour.

Quand une requête incorrecte est spécifiée, sqlcmd se termine sans valeur de retour.

Liste des formats EXIT :

  • :EXIT

    N'exécute pas le lot, puis se termine immédiatement sans retourner de valeur.

  • :EXIT( )

    Exécute le traitement, puis quitte sans retourner de valeur.

  • :EXIT(query)

    Exécute le traitement qui inclut la requête, puis se termine après avoir retourné les résultats de la requête.

Si RAISERROR est utilisé dans un script sqlcmd et qu'une erreur de gravité 127 se produit, sqlcmd se termine et l'ID du message est retourné au client. Par exemple :

RAISERROR(50001, 10, 127)

Cette erreur entraîne l'arrêt du script sqlcmd et retourne l'ID de message 50001 au client.

Les valeurs de retour, de -1 à -99, sont réservées par SQL Server et sqlcmd définit les valeurs de retour supplémentaires suivantes :

Valeur retournée Description
-100 Erreur rencontrée avant la sélection d'une valeur retournée.
-101 Aucune ligne trouvée lors de la sélection d'une valeur retournée.
-102 Erreur de conversion survenue lors de la sélection d'une valeur retournée.

GO [count]

GO signale à la fois la fin d'un lot et l'exécution des instructions Transact-SQL mises en cache. Le lot est exécuté plusieurs fois par lots distincts. Vous ne pouvez pas déclarer une variable plusieurs fois dans un même lot.

Commandes diverses

:r <nom_fichier>

Analyse les instructions Transact-SQL et les commandes sqlcmd supplémentaires du fichier spécifié par nom_fichier dans le cache des instructions. filename est lu par rapport au répertoire de démarrage dans lequel sqlcmd a été exécuté.

Si le fichier contient des instructions Transact-SQL qui ne sont pas suivies par GO, vous devez entrer GO sur la ligne qui suit :r.

Le fichier est lu et exécuté après la rencontre d'un terminateur de traitement. Vous pouvez émettre plusieurs commandes :r . Le fichier peut inclure n'importe quelle commande sqlcmd, y compris la marque de fin de lot GO.

Remarque

Le nombre de lignes affichées en mode interactif augmente de 1 chaque fois qu'une commande :r est rencontrée. La commande :r apparaît dans la sortie de la commande list.

:ServerList

Répertorie tous les serveurs configurés localement et les noms des serveurs émettant sur le réseau.

:Connect nom_serveur[\nom_instance] [-l délai_expiration] [-U nom_utilisateur [-P mot_de_passe]]

Établit une connexion à une instance de SQL Server. Ferme également la connexion actuelle.

Options de délai :

Valeur Comportement
0 Attendre indéfiniment
n>0 Attendre n secondes

La variable de script SQLCMDSERVER reflète la connexion active actuelle.

Si délai_expiration n'est pas spécifié, la valeur de la variable SQLCMDLOGINTIMEOUT est la valeur par défaut.

Si seulement nom_utilisateur est spécifié (en tant qu'option ou en tant que variable d'environnement), , l'utilisateur est invité à entrer un mot de passe. Aucune invite ne s'affiche si les variables d'environnement SQLCMDUSER ou SQLCMDPASSWORD sont définies. Si ni les options ni les variables d'environnement ne sont fournies, le mode d'authentification Windows est employé pour se connecter. Par exemple, pour établir une connexion à une instance instance1 de SQL Server myserver à l'aide de la sécurité intégrée, utilisez la commande suivante :

:connect myserver\instance1

Pour établir une connexion à l'instance par défaut de myserver en utilisant des variables de script, utilisez les paramètres suivants :

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

[:]!! command

Exécute des commandes du système d'exploitation. Pour exécuter une commande du système d'exploitation, commencez une ligne par deux points d'exclamation ( !! ) suivis de la commande du système d'exploitation. Par exemple :

:!! dir

Notes

La commande est exécutée sur l'ordinateur sur lequel sqlcmd s'exécute.

:XML [ ON | OFF ]

Pour plus d'informations, consultez Format de sortie XML et Format de sortie JSON dans cet article.

:Help

Liste les commandes sqlcmd avec une brève description de chaque commande.

Noms de fichiers sqlcmd

Les fichiers d'entréesqlcmd peuvent être spécifiés avec l'option -i ou la commande :r. Les fichiers de sortie peuvent être spécifiés avec l'option -o ou les commandes :Error, :Out et :Perftrace. Voici quelques consignes relatives à l'utilisation de ces fichiers :

  • :Error, :Out et :Perftrace doivent utiliser des valeurs nom_fichier distinctes. Si la même valeur nom_fichier est utilisée, les entrées des commandes peuvent être mélangées.

  • Si un fichier d'entrée situé sur un serveur distant est appelé à partir de sqlcmd sur un ordinateur local et que le fichier contient un chemin de fichier sur un lecteur tel que :Out c:\OutputFile.txt, le fichier de sortie est créé sur l'ordinateur local et non sur le serveur distant.

  • Les chemins d'accès de fichier valides sont les suivants : C:\<filename>, \\<Server>\<Share$>\<filename> et "C:\Some Folder\<file name>". Si le chemin d'accès comporte un espace, utilisez des guillemets.

  • Chaque nouvelle session sqlcmd remplace les fichiers existants qui ont des noms identiques.

Messages d'information

sqlcmd imprime les messages d'information envoyés par le serveur. Dans l'exemple suivant, une fois que les instructions Transact-SQL sont exécutées, un message d'information est affiché.

Démarrer sqlcmd. Dans l'invite de commandes sqlcmd, tapez la requête :

USE AdventureWorks2022;
GO

Lorsque vous appuyez sur ENTRÉE, le message d'information suivant s'affiche :

Changed database context to 'AdventureWorks2022'.

Format de sortie des requêtes Transact-SQL

sqlcmd imprime tout d'abord un en-tête de colonne qui contient les noms de colonne spécifiés dans la liste de sélection. Les noms de colonne sont séparés à l'aide du caractère SQLCMDCOLSEP. Par défaut, il s'agit d'un espace. Si le nom de colonne est plus court que la largeur de colonne, la sortie est complétée avec des espaces jusqu'à la colonne suivante.

Cette ligne est suivie d'un séparateur de ligne qui correspond à une série de tirets. La sortie suivante constitue un exemple.

Démarrer sqlcmd. Dans l'invite de commandes sqlcmd, tapez la requête :

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

Quand vous appuyez sur Entrée, le jeu de résultats suivant est retourné.

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

Bien que la colonne BusinessEntityID ne soit large que de quatre caractères, elle a été étendue pour contenir les noms de colonne plus longs. Par défaut, la sortie se termine à 80 caractères. Cette largeur peut être modifié en utilisant l'option -w ou en définissant la variable de script SQLCMDCOLWIDTH.

format de sortie XML

La sortie XML qui est le résultat d'une clause FOR XML est générée, sans mise en forme, dans un flux continu.

Lorsque vous attendez une sortie XML, utilisez la commande suivante : :XML ON.

Notes

sqlcmd retourne des messages d'erreur au format habituel. Les messages d'erreur sont également générés en sortie dans le flux de texte XML au format XML. Avec :XML ON, sqlcmd n'affiche aucun message d'information.

Pour désactiver le mode XML, utilisez la commande suivante : :XML OFF.

La commande GO ne doit pas apparaître avant l'émission de la commande :XML OFF, car la commande :XML OFF remet sqlcmd en sortie orientée ligne.

Les données XML (diffusées en continu) et les données d'ensemble de lignes ne peuvent être mélangées. Si la commande :XML ON n'a pas été émise avant l'exécution d'une instruction Transact-SQL qui génère des flux XML, la sortie est incohérente. Une fois la commande :XML ON émise, vous ne pouvez pas exécuter d'instructions Transact-SQL qui génèrent des ensembles de lignes réguliers.

Notes

La commande :XML ne prend pas en charge l'instruction SET STATISTICS XML.

Format de sortie JSON

Lorsque vous attendez une sortie JSON, utilisez la commande suivante : :XML ON. Sinon, la sortie inclut à la fois le nom de la colonne et le texte JSON. Cette sortie n'est pas un format JSON valide.

Pour désactiver le mode XML, utilisez la commande suivante : :XML OFF.

Pour plus d'informations, voir Format de sortie XML dans cet article.

Utiliser Authentification Microsoft Entra

Exemples utilisant l’authentification 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

Bonnes pratiques relatives à sqlcmd

Utilisez les méthodes suivantes pour optimiser la sécurité et l'efficacité.

  • Utilisez la sécurité intégrée.

  • Utilisez -X[1] dans des environnements automatisés.

  • Sécurisez les fichiers d'entrée et de sortie en utilisant les autorisations appropriées du système de fichiers.

  • Pour accroître les performances, effectuez autant d'opérations que possible au sein d'une session sqlcmd au lieu de recourir à une série de sessions.

  • Pour l'exécution de requête ou de traitement, définissez des valeurs de délai supérieures à la durée que vous prévoyez pour l'exécution du traitement ou de la requête.

Utilisez les méthodes suivantes pour améliorer l'exactitude :

  • Utilisez -V16 pour consigner les messages de gravité de niveau 16. Les messages de gravité 16 indiquent des erreurs générales qui peuvent être corrigées par l'utilisateur.

  • Une fois le processus terminé, vérifiez le code de sortie et la variable DOS ERRORLEVEL. sqlcmd retourne normalement 0. Sinon, il définit la variable ERRORLEVEL comme configurée par -V. En d'autres termes, ERRORLEVEL ne doit pas afficher la même valeur que le numéro d'erreur signalé par SQL Server. Le numéro d'erreur est une valeur spécifique à SQL Server correspondant à la fonction système @@ERROR. ERRORLEVEL est une valeur spécifique à sqlcmd pour indiquer la raison pour laquelle sqlcmd s'est terminé, et sa valeur est conditionnée par la spécification de l'argument de ligne de commande -b.

L'utilisation de -V16 conjointement avec la vérification du code de sortie et de la variable DOS ERRORLEVEL peut faciliter la détection d'erreurs dans les environnements automatisés, en particulier les contrôles de qualité avant une version de production.