Chapter 13: Using sqlcmd 479 12 Document Control 1 Engineering 16 Executive 14 Facilities and Maintenance 10 Finance 9 Human Resources 11 Information Services 4 Marketing 7 Production 8 Production Control 5 Purchasing 13 Quality Assurance 6 Research and Development 3 Sales 15 Shipping and Receiving 2 Tool Design (16 rows affected) Here you can see how the sqlcmd command is executed to start the sqlcmd command shell. Then two T-SQL commands are added to the batch. The first command sets the current database to the sample AdventureWorks database, and the next command performs a simple T-SQL query that returns the DepartmentID and Name columns from the HumanResources.Department table in the Adventureworks database. Command-Line Parameters The sqlcmd utility supports a number of command-line parameters that influence how the utility works. The following listing shows the complete set of command-line parameters that are supported by the sqlcmd utility: C:\temp>sqlcmd /? Microsoft (R) SQL Server Command Line Tool Version 9.00.1187.07 NT INTEL X86 Copyright (C) 2004 Microsoft Corporation. All rights reserved. usage: sqlcmd [-U login id] [-P password] [-S server] [-H hostname] [-E trusted connection] [-d use database name] [-l login timeout] [-t query timeout] [-h headers] [-s colseparator] [-w screen width] [-a packetsize] [-e echo input] [-I Enable Quoted Identifiers] [-c cmdend] [-L[c] list servers[clean output]] [-q "cmdline query"] [-Q "cmdline query" and exit] 480 Microsoft SQL Server 2005 Developer’s Guide [-m errorlevel] [-V severitylevel] [-W remove trailing spaces] [-u unicode output] [-r[0|1] msgs to stderr] [-i inputfile] [-o outputfile] [-z new password] [-f <codepage> | i:<codepage>[,o:<codepage>]] [-Z new password and exit] [-k[1|2] remove[replace] control characters] [-y variable length type display width] [-Y fixed length type display width] [-p[1] print statistics[colon format]] [-R use client regional setting] [-b On error batch abort] [-v var = "value" ] [-A dedicated admin connection] [-X[1] disable commands, startup script, environment variables [and exit]] [-x disable variable substitution] [-? show syntax summary] NOTE sqlcmd command-line switches are case sensitive. The most important and commonly used parameters are explained in the following section. Listing SQL Server Systems: –L Use the –L switch to list all of the registered SQL Server systems, as is shown here: C:\temp>sqlcmd -L Servers: SQL2005 SQL2005-2 TECA4 SQL Server System/Instance: –S You can use the –S switch to specify the registered SQL Server system that you want to connect to. The following example shows using the –S switch to connect to the SQL Server system named SQL2005: sqlcmd -S sql2005 To connect to a named instance, you need to append the instance name using the slash. For example, the following example shows how to connect to SQLInstance1: sqlcmd -S sql2005/SqlInstance1 Chapter 13: Using sqlcmd 481 User Logon ID and Password: –U –P While it’s usually preferable to connect using integrated security, sqlcmd also supports connections that use SQL Server authentication via the –U and –P switches. As you might expect, the –U parameter enables you to pass in the SQL Server Login ID, while the –P parameter enables you to supply the password. NOTE Unlike the other command line parameters, the –U and –P parameters must not have a space between the switch and its value. The following illustrates using the –U and –P command-line parameters: sqlcmd -S sql2005 -Usa -Pmy1stStrongSAPwd! To accommodate login IDs and passwords that have embedded spaces, you need to surround the value supplied to the –U or –P switch with double quotes (“ ”), as shown in the following listing: sqlcmd -S sql2005 -U"sa" -P"my1stStrongSAPwd!" Database Name: –d The –d parameter can be used to specify the database that you want the sqlcmd utility to connect to. In the following example, you can see how to use the –d switch to connect to the AdventureWorks database on the SQL Server system named SQL2005: sqlcmd -S sql2005 -d AdventureWorks Query: –Q The –Q (or –q) switch enables you to submit a query from the command line. This can be useful when you want to execute an ad hoc query or when you want to dynamically build a query in a batch file. The following example illustrates using the –q switch: C:\temp>sqlcmd -q"select Name from AdventureWorks.Production.Product where ProductID = 777" Name Mountain-100 Black, 44 (1 rows affected) 482 Microsoft SQL Server 2005 Developer’s Guide In this example, the –q switch is used to send a select statement to the SQL Server system. Since the SELECT statement can contain spaces, it needs to be enclosed in double quotes(“ ”). Input Source: –i While directly passing a query as a command-line parameter is a great way to execute simple queries or ad hoc queries that are built into your script, this approach obviously has some shortcomings when it comes to executing more complex sets of instructions. That’s where the –i switch comes in, enabling you to direct the sqlcmd utility to use the contents of a script as its input source. Here is an example of using the –i switch: sqlcmd -S sql2005 -i c:\temp\MySqlCmdScript.sql The contents of the file specified with the –i switch will include a combination of T-SQL statements and sqlcmd extended commands and variables. More information about how you write SqlCmd scripts is presented later in this chapter, in the section titled “Developing sqlcmd Scripts.” Output Destination: –o Much as the –i switch is used to redirect the input source that’s used by the sqlcmd utility, the –o switch can be used to redirect the output of sqlcmd from the screen to a file. Here is an example of using the –o switch: sqlcmd -S sql2005 -i c:\temp\MySqlCmdScript.sql -o c:\temp\MyOutput.txt Here the output that’s generated by MySqlCmdScript.sql will be written to the file MyOutput.txt in the c:\temp directory. The default output format is plain text. However, you can also use the –s switch to change the column separator character, which is useful for creating comma- or tab-delimited files. Performance Statistics: –p Another useful switch is –p, which outputs the performance statistics for the result set. The following listing illustrates using the –p switch in conjunction with the –q switch: C:\temp>sqlcmd -q"select Name from AdventureWorks.Production.Product where ProductID = 777" -p Name Chapter 13: Using sqlcmd 483 Mountain-100 Black, 44 (1 rows affected) Network packet size (bytes): 4096 1 xact[s]: Clock Time (ms.): total 16 avg 16.00 (62.50 xacts per sec.) Administrative Mode: –A One important feature that the sqlcmd utility has in addition to the ability to execute commands is the fact that it can connect to the database using SQL Server 2005’s Dedicated Administrative Connection (DAC). The DAC permits you to connect and run at a higher priority than any other SQL Server process, enabling you to terminate any runaway process. To use the DAC, you must start the sqlcmd utility using the –A switch, as is shown here: sqlcmd -S sql2005 -A Variable Values: –v In addition to supporting the execution of standard T-SQL statements, the sqlcmd utility also supports a number of scripting extensions that enable you to include flow control and variables in your scripts. You can use the –v switch to define scripting variables, or you can set them using the command-shell setvar command. The following example shows how to define a variable using the –v parameter and assign it a value: sqlcmd -S Sql2005 -d AdventureWorks -v ProductID="11" -i MyScript.sql In this example, the –S and the –d parameters are used to connect sqlcmd to the AdventureWorks database on the SQL Server system named Sql2005. Then the –v parameter is used to define a variable named ProductID and to assign the value of 11 to that variable. Next the –i parameter is used to execute the script named MyScript .sql. This script can make use of the ProductID variable and pass its value to a SQL query embedded in the script. More detailed examples showing how to use the –v switch are provided later in this chapter. Online Help: /? You can get a full listing of the supported command-line switches by entering sqlcmd /? at the command prompt. 484 Microsoft SQL Server 2005 Developer’s Guide sqlcmd Extended Commands To enable the creation of scripts that are able to execute complex logic, the sqlcmd utility provides a number of control commands. To make a clear distinction between sqlcmd commands and T-SQL statements, all sqlcmd commands must be prefixed with a colon (:). The extended sqlcmd commands are listed in Table 13-1. sqlcmd Variables In addition to providing for user-defined variables, the sqlcmd utility also includes a set of built-in variables that can be used with sqlcmd scripts. Table 13-2 lists the built-in variables supported by the sqlcmd utility and the command-line switches that can be used to supply values for those variables. Command Description :GO [count] Signals the end of a batch and executes the cached statements. Adding an optional count value executes the statements a given number of times. :RESET Clears the statement cache. :ED Starts the next edit for the current statement cache. :!! Executes operating system commands. :QUIT Ends the sqlcmd utility. :EXIT (results) Uses the value of a result set as a return value. :r <filename> Includes additional sqlcmd statements from the specified file. :ServerList Lists the configured SQL Server systems. :List Lists the contents of the statement cache. :Error <filename> Redirects error output to the specified file. :Out <filename> Redirects query results to the specified file. :Perftrace <filename> Redirects performance statistics to the specified file. :Connect [timeout] Connects to a SQL Server instance. :On Error [exit |retry | ignore] Specifies the action to be performed when an error is encountered. :XML [ON | OFF] Specifies whether XML results will be output as a continuous stream. Table 13-1 sqlcmd Commands Chapter 13: Using sqlcmd 485 Developing sqlcmd Scripts The preceding section presented the basics of the sqlcmd tool. In this section you’ll see some examples of sqlcmd in action. First, this section will cover some of the tools for building sqlcmd scripts. Then you’ll see some sqlcmd scripts illustrating how to use variables, nested scripts, and flow control for building database scripts with sqlcmd. Developing sqlcmd Scripts with Query Editor You can develop sqlcmd scripts using any text editor like Notepad or TextPad. However, you may not realize that SQL Server Management Studio also has the capability of creating sqlcmd scripts. To develop sqlcmd scripts using Query Editor, you first need to open the Query Editor window and then click the sqlcmd icon as is shown in Figure 13-1. Query Editor has the following features that can be helpful in developing sqlcmd scripts: ᭤ Color-coded syntax ᭤ Syntax parsing ᭤ Script execution Variable Command-Line Switch SQLCMDUSER –U SQLCMDPASSWORD –P SQLCMDSERVER –S SQLCMDWORKSTATION –H SQLCMDDBNAME –d SQLCMDLOGINTIMEOUT –l SQLCMDSTATTIMEOUT –t SQLCMDHEADERS –h SQLCMDCOLSEP –s SQLCMDCOLWIDTH –w SQLCMDPACKETSIZE –a SQLCMDERRORLEVEL –m Table 13-2 sqlcmd Built-in Variables 486 Microsoft SQL Server 2005 Developer’s Guide ᭤ Source control integration ᭤ Showplan Entering Query Editor’s sqlcmd mode enables Query Editor to execute all of the commands that would normally only be accessible from the sqlcmd shell. For instance, special sqlcmd variables and commands can be executed, as can operating system commands such as dir and even del if they are prefaced with the !! symbol. To get started using Query Editor to develop sqlcmd scripts, follow these steps: 1. Open SQL Server Management Studio. 2. Click the New Query button to start Query Editor. 3. Click the sqlcmd button. 4. Enter and execute the following script in Query Editor: :setvar DirIn c:\temp !! dir $(DirIn) This script sets the contents of the variable DirIn to c:\temp and then executes the operating system command dir using the contents of the DirIn variable as a parameter. This type of sqlcmd script execution is possible in Query Editor only when the sqlcmd mode has been enabled. You can see the output of the sqlcmd script in Figure 13-2. Figure 13-1 Enabling sqlcmd mode in the Query Editor Chapter 13: Using sqlcmd 487 Using sqlcmd Variables One of the most powerful uses of the sqlcmd lies in its ability to execute scripts and substitute variable values at run time. The following listing shows a simple script named dbBackup.sql that can be used to back up the database that’s specified in the DatabaseName variable: BACKUP DATABASE $(DatabaseName) TO DISK = "c:\temp\$(DatabaseName).bak" You can substitute the value of the variable either from the command line or by using the :setvar command from within the script. The following example illustrates how you can combine the sqlcmd command-line switches with variables used in scripts: C:\temp>sqlcmd -S sql2005-2 -v DatabaseName="AdventureWorks" -i dbbackup.sql Processed 21032 pages for database 'AdventureWorks', file 'AdventureWorks_Data' on file 1. Processed 2 pages for database 'AdventureWorks', file 'AdventureWorks_Log' on file 1. BACKUP DATABASE successfully processed 21034 pages in 16.091 seconds (10.708 MB/sec). Figure 13-2 Executing sqlcmd scripts with Query Editor 488 Microsoft SQL Server 2005 Developer’s Guide NOTE The sqlcmd utility uses a trusted connection by default. This example uses the –S switch to specify the SQL Server system name. The –v switch is used to define a variable named DatabaseName and supply that variable with the value of AdventureWorks. The –i switch is used to tell the sqlcmd utility that the T-SQL command will come out of the file dbbackup.sql. Using sqlcmd Script Nesting Another powerful feature in sqlcmd that promotes code reuse is the ability to nest scripts. By using the built-in :r command, you can direct the sqlcmd utility to read in and execute the content of another sqlcmd script. To illustrate using script nesting, the following example executes the same backup script that was shown in the preceding example, except in this case, instead of executing the script from the command line, the rundbbackup.sql script uses the :r command to read and execute dbbackup.sql: :connect sql2005-2 :setvar DatabaseName AdventureWorks :r "c:\temp\dbbackup.sql" In this example, the :connect command is used to connect to an instance of SQL Server 2005 named sql2005-2. Then the setvar command is used to set the contents of the DatabaseName variable to AdventureWorks. Next, the :r command is used to read and execute the dbbackup.sql script. Since the DatabaseName variable is already set within the runbackup.sql script, there’s no need to pass the dbbackup.sql script any additional parameters. Since rundbacklup.sql supplies the values for its variable internally, when using the setvar command, the only command-line parameter that’s needed is the –I switch, which executes the contents of the rundbbackup.sql file. C:\temp>sqlcmd -i rundbbackup.sql sqlcmd: Successfully connected to server 'sql2005-2'. Processed 21032 pages for database 'AdventureWorks', file 'AdventureWorks_Data' on file 2. Processed 2 pages for database 'AdventureWorks', file 'AdventureWorks_Log' on file 2. BACKUP DATABASE successfully processed 21034 pages in 16.018 seconds (10 .757 MB/sec). . registered SQL Server systems, as is shown here: C: emp>sqlcmd -L Servers: SQL2 005 SQL2 005-2 TECA4 SQL Server System/Instance: –S You can use the –S switch to specify the registered SQL Server. Switch SQLCMDUSER –U SQLCMDPASSWORD –P SQLCMDSERVER –S SQLCMDWORKSTATION –H SQLCMDDBNAME –d SQLCMDLOGINTIMEOUT –l SQLCMDSTATTIMEOUT –t SQLCMDHEADERS –h SQLCMDCOLSEP –s SQLCMDCOLWIDTH –w SQLCMDPACKETSIZE. entering sqlcmd /? at the command prompt. 484 Microsoft SQL Server 2005 Developer’s Guide sqlcmd Extended Commands To enable the creation of scripts that are able to execute complex logic, the sqlcmd