This repo contains the sqlcmd command line tool and Go packages for working with Microsoft SQL Server, Azure SQL Database, and Azure Synapse.
Learn more about how sqlcmd is used from a articles/posts written by the community: Community Buzz.
sqlcmd is available in package managers for all major platforms.
sqlcmd is available via Winget, Choco and as a downloadable .msi or .zip from the releases page. The .msi installer is signed with a Microsoft Authenticode certificate.
| Install: | Upgrade: |
|---|---|
winget install sqlcmd |
winget upgrade sqlcmd |
| Install: | Upgrade: |
|---|---|
choco install sqlcmd |
choco upgrade sqlcmd |
sqlcmd is available via Homebrew, and as a downloadable .tar from the releases page.
| Install: | Upgrade: |
|---|---|
brew install sqlcmd |
brew upgrade sqlcmd |
Macs running Apple Silicon require Docker Desktop to use Rosetta for x86/amd64 emulation. Follow these steps before creating a SQL Server instance:
sqlcmd is available via Linuxbrew, and as a downloadable .rpm/.deb and .tar from the releases page.
On Linux, sqlcmd is also available through apt-get, yum and zypper package managers. Instructions can be found here.
The Homebrew package manager may be used on Linux and Windows Subsystem for Linux (WSL) 2. Homebrew was formerly referred to as Linuxbrew when running on Linux or WSL.
| Install: | Upgrade: |
|---|---|
brew install sqlcmd |
brew upgrade sqlcmd |
Use sqlcmd to create SQL Server and Azure SQL Edge instances using a local container runtime (e.g. Docker or Podman)
To create a local SQL Server instance with the AdventureWorksLT database restored, query it, and connect to it using Azure Data Studio, run:
sqlcmd create mssql --accept-eula --using https://aka.ms/AdventureWorksLT.bak
sqlcmd query "SELECT DB_NAME()"
sqlcmd open adsUse sqlcmd --help to view all the available sub-commands. Use sqlcmd -? to view the original ODBC sqlcmd flags.
Each time sqlcmd create completes, a new context is created (e.g. mssql, mssql2, mssql3 etc.). A context contains the endpoint and user configuration detail. To switch between contexts, run sqlcmd config use <context-name>, to view name of the current context, run sqlcmd config current-context, to list all contexts, run sqlcmd config get-contexts.
To view connection strings (ODBC/ADO.NET/JDBC etc.) for the current context and user & endpoint details for all contexts held in the ~/.sqlcmd/sqlconfig file:
sqlcmd config connection-strings
sqlcmd config viewTo see all version tags to choose from (2017, 2019, 2022 etc.), and install a specific version, run:
SET SQLCMD_ACCEPT_EULA=YES
sqlcmd create mssql get-tags
sqlcmd create mssql --tag 2019-latestTo stop, start and delete contexts, run the following commands:
sqlcmd stop
sqlcmd start
sqlcmd deleteTo connect to the current context, and use the original ODBC sqlcmd flags (e.g. -q, -Q, -i, -o etc.), which can be listed with sqlcmd -?, run:
sqlcmd -q "SELECT @@version"
sqlcmdIf no current context exists, sqlcmd (with no connection parameters) reverts to the original ODBC sqlcmd behavior of creating an interactive session to the default local instance on port 1433 using trusted authentication, otherwise it will create an interactive session to the current context.
The sqlcmd project aims to be a complete port of the original ODBC sqlcmd to the Go language, utilizing the go-mssqldb driver. For full documentation of the tool and installation instructions, see go-sqlcmd-utility.
/ is not accepted as a flag specifier, only ---input-file for -i. sqlcmd -? will print those parameter names. Those new names do not preserve backward compatibility with ODBC sqlcmd. For example, to specify multiple input file names using --input-file, the file names must be comma-delimited, not space-delimited.The following switches have different behavior in this version of sqlcmd compared to the original ODBC based sqlcmd.
-R switch is ignored. The go runtime does not provide access to user locale information, and it's not readily available through syscall on all supported platforms.-I switch is ignored; quoted identifiers are always set on. To disable quoted identifier behavior, add SET QUOTED IDENTIFIER OFF in your scripts.-N now takes an optional string value that can be one of s[trict],t[rue],m[andatory], yes,1, o[ptional],no, 0, f[alse], or disable to specify the encryption choice.
-N is passed but no value is provided, true is used.-N and -C are not provided, sqlcmd will negotiate authentication with the server without validating the server certificate.-N is provided but -C is not, sqlcmd will require validation of the server certificate. Note that a false value for encryption could still lead to encryption of the login packet.-C has no effect when strict value is specified for -N.-N and -C are provided, sqlcmd will use their values for encryption negotiation.-u The generated Unicode output file will have the UTF16 Little-Endian Byte-order mark (BOM) written to it.OSQL may be changed, such as alignment of column headers for some data types.EXIT. Interactive mode will not check for open parentheses or quotes for commands and prompt for successive lines. The ODBC sqlcmd allows the query run by EXIT(query) to span multiple lines.-i doesn't handle a comma , in a file name correctly unless the file name argument is triple quoted. For example:
sqlcmd -i """select,100.sql""" will try to open a file named sql,100.sql while sqlcmd -i "select,100.sql" will try to open two files select and 100.sql-i flag to pass multiple file names, there must be a space after the -i. Example: -i file1.sql file2.sql-M switch is ignored. Sqlcmd always enables multi-subnet failover.There are a few switches yet to be implemented in the new sqlcmd (go-sqlcmd) compared
to the original ODBC based sqlcmd, discussion #293
lists these switches. Please provide feedback in the discussion on which
switches are most important to you to have implemented next in the new sqlcmd.
:Connect now has an optional -G parameter to select one of the authentication methods for Azure SQL Database - SqlAuthentication, ActiveDirectoryDefault, ActiveDirectoryIntegrated, ActiveDirectoryServicePrincipal, ActiveDirectoryManagedIdentity, ActiveDirectoryPassword. If -G is not provided, either Integrated security or SQL Authentication will be used, dependent on the presence of a -U username parameter.--driver-logging-level command line parameter allows you to see traces from the go-mssqldb client driver. Use 64 to see all traces.-F vertical command line option to set it. It's also controlled by the SQLCMDFORMAT scripting variable.1> select session_id, client_interface_name, program_name from sys.dm_exec_sessions where session_id=@@spid
2> go
session_id 58
client_interface_name go-mssqldb
program_name sqlcmdsqlcmd supports shared memory and named pipe transport. Use the appropriate protocol prefix on the server name to force a protocol:
lpc for shared memory, only for a localhost. sqlcmd -S lpc:.np for named pipes. Or use the UNC named pipe path as the server name: sqlcmd -S \\myserver\pipe\sql\querytcp for tcp sqlcmd -S tcp:myserver,1234
If no protocol is specified, sqlcmd will attempt to dial in this order: lpc->np->tcp. If dialing a remote host, lpc will be skipped.1> select net_transport from sys.dm_exec_connections where session_id=@@spid
2> go
net_transport Named pipesqlcmd supports a broader range of AAD authentication models (over the original ODBC based sqlcmd), based on the azidentity package. The implementation relies on an AAD Connector in the driver.
To use AAD auth, you can use one of two command line switches:
-G is (mostly) compatible with its usage in the prior version of sqlcmd. If a username and password are provided, it will authenticate using AAD Password authentication. If a username is provided it will use AAD Interactive authentication which may display a web browser. If no username or password is provided, it will use a DefaultAzureCredential which attempts to authenticate through a variety of mechanisms.
--authentication-method= can be used to specify one of the following authentication types.
ActiveDirectoryDefault
Setting environment variables AZURE_TENANT_ID, and AZURE_CLIENT_ID are necessary for DefaultAzureCredential to begin checking the environment configuration and look for one of the following additional environment variables in order to authenticate:
ActiveDirectoryIntegrated
This method is currently not implemented and will fall back to ActiveDirectoryDefault.
ActiveDirectoryPassword
This method will authenticate using a username and password. It will not work if MFA is required.
You provide the username and password using the usual command line switches or SQLCMD environment variables.
Set AZURE_TENANT_ID environment variable to the tenant id of the server if not using the default tenant of the user.
ActiveDirectoryInteractive
This method will launch a web browser to authenticate the user.
ActiveDirectoryManagedIdentity
Use this method when running sqlcmd on an Azure VM that has either a system-assigned or user-assigned managed identity. If using a user-assigned managed identity, set the username to the ID of the managed identity. If using a system-assigned identity, leave username empty.
ActiveDirectoryServicePrincipal
This method authenticates the provided username as a service principal id and the password as the client secret for the service principal. Provide a username in the form <service principal id>@<tenant id>. Set SQLCMDPASSWORD variable to the client secret. If using a certificate instead of a client secret, set AZURE_CLIENT_CERTIFICATE_PATH environment variable to the path of the certificate file.
Some settings for AAD auth do not have command line inputs, and some environment variables are consumed directly by the azidentity package used by sqlcmd.
These environment variables can be set to configure some aspects of AAD auth and to bypass default behaviors. In addition to the variables listed above, the following are sqlcmd-specific and apply to multiple methods.
SQLCMDCLIENTID - set this to the identifier of an application registered in your AAD which is authorized to authenticate to Azure SQL Database. Applies to ActiveDirectoryInteractive and ActiveDirectoryPassword methods.
Sqlcmd now supports syntax coloring the output of :list and the results of TSQL queries when output to the terminal.
To enable coloring use the SQLCMDCOLORSCHEME variable, which can be set as an environment variable or by using :setvar. The valid values are the names of styles supported by the chroma styles project.
To see a list of available styles along with colored syntax samples, use this command in interactive mode:
:list colorBuild sqlcmd
./build/build.shor
.\build\build.cmdpkg/sqlcmd is consumable by other hosts. Go docs for the package are forthcoming. See the test code and main.go for examples of initializing and running sqlcmd.
build/buildThe tests rely on SQLCMD scripting variables to provide the connection string parameters. Set SQLCMDSERVER, SQLCMDDATABASE, SQLCMDUSER, SQLCMDPASSWORD variables appropriately then
go test ./...If you are developing on Windows, you can use docker or WSL to run the tests on Linux. docker run lets you pass the environment variables. For example, if your code is in i:\git\go-sqlcmd you can run tests in a docker container:
docker run -rm -e SQLCMDSERVER=<yourserver> -e SQLCMDUSER=<youruser> -e SQLCMDPASSWORD=<yourpassword> -v i:\git\go-sqlcmd:/go-sqlcmd -w /go-sqlcmd golang:1.16 go test ./...The new sqlcmd (go-sqlcmd) is localized for the following languages: Chinese (Simplified) | Chinese (Traditional) | English (United States) | French | German | Italian | Japanese | Korean | Portuguese (Brazil) | Russian | Spanish
Currently, the user visible strings that also existed in ODBC based sqlcmd are localized in the new sqlcmd, new strings (introduced with the new sqlcmd functionality) will be localized shortly.
To get localized messages from sqlcmd set environment variable SQLCMD_LANG to a language tag as per BCP47 convention.
e.g.
\git\go-sqlcmd>set SQLCMD_LANG=de-de
\git\go-sqlcmd>.\sqlcmd.exe -w 4
sqlcmd.exe: error: sqlcmd.exe: '-w 4': Der Wert muss größer als 8 und kleiner als 65536 sein.This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.