go-sqlcmd: The New Command Line Tool for SQL Server

Check which executable runs before trusting a command-line database job. The newer go-sqlcmd adds capabilities beyond the traditional utility, while familiar script options still need a version-aware check.

Identify the Utility Before Changing a Script

There are two sqlcmd variants: the newer implementation written in Go and the traditional ODBC implementation. They can both exist on a Windows computer. The executable selected by PATH determines which one runs when a script uses the short command name. Keep that choice explicit in scheduled work.

Inspect the resolved locations and help output before assuming the new client is active. The following commands target Windows Command Prompt. Their first comment marks the block as command-line input rather than T-SQL.

REM Command line
where sqlcmd
sqlcmd -?
sqlcmd --version

The long version option belongs to the newer variant; the help output can identify either client. Capture the actual variant and build with the deployment record. I check this before investigating a changed flag behavior, because two identically named executables can interpret an old script differently.

A package-manager installation can change PATH precedence without removing the older executable. Reopen the command window after an accepted installation and verify resolution again. Use the full approved executable path in a critical job when that provides a stable deployment contract. A short command name is convenient, but it does not remember which version you meant.

Install the go-sqlcmd Windows Build Through an Approved Route

Use the official Download and Install the sqlcmd Utility instructions for the current Windows package. The documented Windows Package Manager route is shown below. Review the selected package and the organization's software policy before installation.

REM Command line
winget install sqlcmd

An approved go-sqlcmd deployment can instead extract the Windows executable from the official release package into the chosen application folder. Select the build for the machine's architecture. Preserve the accepted version and verify the executable before changing production automation. This article does not require a compiler or a source-build workflow.

Check current release details rather than assuming every package channel contains the same newest version. An installed client can have capabilities that differ from another workstation's client. The cross-platform availability of the utility does not change these Windows examples or justify using platform-specific commands from a different operating system.

Connect With an Explicit Destination and Identity

The familiar server option selects the destination. Use the approved authentication method and encryption configuration for the deployed client. The example uses Windows integrated authentication and an explicitly named lab database.

REM Command line
sqlcmd -S TestServer\LAB -d CommandLab -E -Q "SELECT DB_NAME() AS DatabaseName, @@SPID AS SessionID;" -b

The named instance and database must already exist and allow the intended Windows identity. Check certificate validation and encryption defaults for the actual variant and version. Do not add a trust-certificate bypass merely to silence a connection failure. A successful query under the wrong security setting is not an accepted connection test.

The batch-error option is useful for automation, but validate its exact error handling under the installed client. A connection error, SQL error, and warning can have different reporting behavior. Capture the process exit code and appropriate diagnostic output in the calling job. Do not judge success solely by whether an output file was created.

Run a Local Script and Trusted Variables

Create a small local script through PowerShell. It contains a SQLCMD variable that the client substitutes before SQL Server receives the statement. The file-writing block is PowerShell because the unsubstituted text is not standalone T-SQL.

# PowerShell
$ScriptPath = 'C:\SqlScripts\Inventory.sql'
$SqlText = 'SET NOCOUNT ON;' + [Environment]::NewLine +
    'SELECT object_id,name FROM sys.tables WHERE object_id >= $(MinimumID) ORDER BY object_id;' +
    [Environment]::NewLine + 'GO' + [Environment]::NewLine
[System.IO.File]::WriteAllText($ScriptPath,$SqlText,[System.Text.Encoding]::UTF8)

The directory must already exist and be an approved script location. Then execute that file with a trusted numeric variable and write its result to the chosen local output path.

REM Command line
sqlcmd -S TestServer\LAB -d CommandLab -E -i "C:\SqlScripts\Inventory.sql" -v MinimumID=100 -o "C:\SqlOutput\Inventory.txt" -b

SQLCMD variables are textual substitutions, not typed SQL parameters. Accept only reviewed values and fixed script fragments from the deployment process. Do not pass arbitrary user input into that substitution boundary. For application data, use an appropriate parameterized SQL execution design instead.

Test paths containing spaces with the necessary quotes, and preserve Windows backslashes. Keep included files and SQLCMD commands in the reviewed script package. A script that depends on a local file not present under the scheduled identity is incomplete even when its main file was copied successfully.

Choose an Output Contract Deliberately

Human-readable output and machine-readable data have different requirements. Separator and whitespace options can produce a simple delimited result for controlled values. They do not automatically supply robust CSV quoting for commas, quotes, embedded line breaks, or NULL semantics.

REM Command line
sqlcmd -S TestServer\LAB -d CommandLab -E -Q "SET NOCOUNT ON; SELECT object_id,name FROM sys.tables ORDER BY object_id;" -s "," -W -h -1 -o "C:\SqlOutput\TableList.txt" -b

For a JSON contract, have the query generate JSON and verify the client output widths and formatting for the installed build. Large-value and display settings can truncate or wrap output if they are not configured deliberately. Check the resulting document with the receiving parser rather than assuming a .json extension certifies valid JSON.

Which consumer reads the file after the command completes? Define encoding, headers, separators, NULLs, error output, and exit status for that consumer. I include those requirements in the script's acceptance test so a pretty console result does not become a broken import contract.

Review the go-sqlcmd Container Capability Separately

The newer utility exposes a create command for a disposable local SQL Server container. That capability requires a supported, already approved container runtime and appropriate local resources. It is separate from connecting to an existing Windows SQL Server instance and does not install all of its prerequisites automatically.

REM Command line
sqlcmd create mssql --help

Review the installed help for image selection, ports, storage, access, and cleanup before creating anything. In an approved disposable container environment, the basic command includes explicit license acceptance. It can retrieve images and create local runtime resources, so it belongs to that planned lab setup.

REM Command line
sqlcmd create mssql --accept-eula

Do not assume that example selects a permanently stable engine version. Choose and record an approved image tag according to the current help when repeatability matters. Container defaults and local context behavior are version-sensitive. Use an existing approved server for ordinary script execution when container creation is unnecessary.

Migrate Existing Automation to go-sqlcmd With Evidence

Review flags, authentication, encryption, input encoding, output formatting, and exit behavior before replacing the traditional client. Test representative successful and failed scripts under the scheduled identity. Preserve the older approved executable until the replacement passes that comparison.

Go-sqlcmd is useful when its supported capabilities match the operating requirement. Adopt it with a verified executable and an explicit script contract. A newer client should make automation more reproducible, not silently change which program, destination, or output format a job uses.

Related reading on this blog: SQLCMD Mode in SSMS: Variables, :CONNECT and :r Includes and Performance Test: sqlcmd vs SSMS.

A client upgrade is not a transparent guarantee, it is a tool change whose connection and script behavior need verification.

Published by Pinal Dave on SQLAuthority. More of my work at pinaldave.com.