{"id":13775171,"url":"https://github.com/microsoft/go-sqlcmd","last_synced_at":"2025-05-14T19:07:45.986Z","repository":{"id":37775661,"uuid":"376924587","full_name":"microsoft/go-sqlcmd","owner":"microsoft","description":"The new sqlcmd, CLI for SQL Server and Azure SQL (winget install sqlcmd / sqlcmd create mssql / sqlcmd open ads)","archived":false,"fork":false,"pushed_at":"2025-05-05T15:29:39.000Z","size":58575,"stargazers_count":438,"open_issues_count":127,"forks_count":65,"subscribers_count":41,"default_branch":"main","last_synced_at":"2025-05-07T23:46:52.869Z","etag":null,"topics":["azure-sql","mssql","sql-server","sqlcmd"],"latest_commit_sha":null,"homepage":"https://learn.microsoft.com/sql/tools/sqlcmd/go-sqlcmd-utility","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/microsoft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-06-14T18:47:18.000Z","updated_at":"2025-05-07T04:07:05.000Z","dependencies_parsed_at":"2023-10-12T12:51:53.857Z","dependency_job_id":"88d1c8cc-ca9c-4465-96ad-5bcd5a0cf3d2","html_url":"https://github.com/microsoft/go-sqlcmd","commit_stats":{"total_commits":283,"total_committers":25,"mean_commits":11.32,"dds":0.7067137809187279,"last_synced_commit":"0221d93de85506dbb3564603666f60708ce6804c"},"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fgo-sqlcmd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fgo-sqlcmd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fgo-sqlcmd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fgo-sqlcmd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microsoft","download_url":"https://codeload.github.com/microsoft/go-sqlcmd/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254209859,"owners_count":22032897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["azure-sql","mssql","sql-server","sqlcmd"],"created_at":"2024-08-03T17:01:34.834Z","updated_at":"2025-05-14T19:07:44.544Z","avatar_url":"https://github.com/microsoft.png","language":"Go","readme":"# SQLCMD CLI\n\nThis repo contains the `sqlcmd` command line tool and Go packages for working with Microsoft SQL Server, Azure SQL Database, and Azure Synapse.  \n\nLearn more about how `sqlcmd` is used from a articles/posts written by the community: [Community Buzz][].\n\n## Installation\n\n`sqlcmd` is available in package managers for all major platforms.\n\n### Windows\n\n`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.\n\n#### WinGet\n\n| Install:                | Upgrade:                    |\n| ----------------------- |-----------------------------|\n| `winget install sqlcmd` | `winget upgrade sqlcmd`     |\n\n#### Choco\n\n| Install:                | Upgrade:                |\n| ----------------------- |-------------------------|\n| `choco install sqlcmd`  | `choco upgrade sqlcmd`  |\n\n### macOS\n\n`sqlcmd` is available via [Homebrew][], and as a downloadable .tar from the [releases page][].\n\n#### Homebrew\n\n| Install:              | Upgrade:              |\n| --------------------- | --------------------- |\n| `brew install sqlcmd` | `brew upgrade sqlcmd` |\n\n##### Apple Silicon Macs (M1/M2)\nMacs running Apple Silicon require [Docker][] Desktop to use Rosetta for x86/amd64 emulation. Follow these steps before creating a SQL Server instance:\n- Open Docker Desktop.\n- Go to the settings/preferences menu.\n- Find the “Features in development” section.\n- Enable the \"Use Rosetta for x86/amd64 emulation on Apple Silicon\" checkbox.\n\n### Linux\n\n`sqlcmd` is available via [Linuxbrew][], and as a downloadable .rpm/.deb and .tar from the [releases page][].\n\nOn Linux, `sqlcmd` is also available through `apt-get`, `yum` and `zypper` package managers.  Instructions can be found [here](https://learn.microsoft.com/sql/tools/sqlcmd/go-sqlcmd-utility?view=sql-server-ver16#download-and-install-go-sqlcmd).\n\n#### Linuxbrew\n\nThe 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.\n\n| Install:              | Upgrade:              |\n| --------------------- | --------------------- |\n| `brew install sqlcmd` | `brew upgrade sqlcmd` |\n\n## Use sqlcmd to create local SQL Server and Azure SQL Edge instances\n\nUse `sqlcmd` to create SQL Server and Azure SQL Edge instances using a local container runtime (e.g. [Docker][] or [Podman][])\n\n### Create SQL Server instance using local container runtime and connect using Azure Data Studio\n\nTo create a local SQL Server instance with the AdventureWorksLT database restored, query it, and connect to it using Azure Data Studio, run:\n\n```\nsqlcmd create mssql --accept-eula --using https://aka.ms/AdventureWorksLT.bak\nsqlcmd query \"SELECT DB_NAME()\"\nsqlcmd open ads\n```\n\nUse `sqlcmd --help` to view all the available sub-commands.  Use `sqlcmd -?` to view the original ODBC `sqlcmd` flags.\n\n### The ~/.sqlcmd/sqlconfig file\n\nEach 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 \u003ccontext-name\u003e`, to view name of the current context, run `sqlcmd config current-context`, to list all contexts, run `sqlcmd config get-contexts`.\n\nTo view connection strings (ODBC/ADO.NET/JDBC etc.) for the current context and user \u0026 endpoint details for all contexts held in the `~/.sqlcmd/sqlconfig` file:\n\n```\nsqlcmd config connection-strings\nsqlcmd config view\n```\n\n### Versions\n\nTo see all version tags to choose from (2017, 2019, 2022 etc.), and install a specific version, run:\n\n```\nSET SQLCMD_ACCEPT_EULA=YES\n\nsqlcmd create mssql get-tags\nsqlcmd create mssql --tag 2019-latest\n```\n\nTo stop, start and delete contexts, run the following commands:\n\n```\nsqlcmd stop\nsqlcmd start\nsqlcmd delete\n```\n\n### Backwards compatibility with ODBC sqlcmd\n\nTo 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:\n\n```\nsqlcmd -q \"SELECT @@version\"\nsqlcmd\n```\n\nIf 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.\n\n## Sqlcmd\n\nThe `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][].\n\n### Changes in behavior from the ODBC based sqlcmd\n\n- `/` is not accepted as a flag specifier, only `-`\n- There are new posix-style versions of each flag, such as `--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.\n\nThe following switches have different behavior in this version of `sqlcmd` compared to the original ODBC based `sqlcmd`.\n- `-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.\n- `-I` switch is ignored; quoted identifiers are always set on. To disable quoted identifier behavior, add `SET QUOTED IDENTIFIER OFF` in your scripts.\n- `-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  - If `-N` is passed but no value is provided, `true` is used.\n  - If `-N` and `-C` are not provided, sqlcmd will negotiate authentication with the server without validating the server certificate.\n  - If `-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.\n  - `-C` has no effect when `strict` value is specified for `-N`.\n  - If both `-N` and `-C` are provided, sqlcmd will use their values for encryption negotiation.\n  - More information about client/server encryption negotiation can be found at \u003chttps://docs.microsoft.com/openspecs/windows_protocols/ms-tds/60f56408-0188-4cd5-8b90-25c6f2423868\u003e\n- `-u` The generated Unicode output file will have the UTF16 Little-Endian Byte-order mark (BOM) written to it.\n- Some behaviors that were kept to maintain compatibility with `OSQL` may be changed, such as alignment of column headers for some data types.\n- All commands must fit on one line, even `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.\n- `-i` doesn't handle a comma `,` in a file name correctly unless the file name argument is triple quoted. For example:\n  `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`\n- If using a single `-i` flag  to pass multiple file names, there must be a space after the `-i`. Example: `-i file1.sql file2.sql`\n- `-M` switch is ignored. Sqlcmd always enables multi-subnet failover.\n\n### Switches not available in the new sqlcmd (go-sqlcmd) yet\n\nThere are a few switches yet to be implemented in the new `sqlcmd` (go-sqlcmd) compared\nto the original ODBC based `sqlcmd`, discussion [#293](https://github.com/microsoft/go-sqlcmd/discussions/292) \nlists these switches. Please provide feedback in the discussion on which \nswitches are most important to you to have implemented next in the new sqlcmd.\n\n\n### Miscellaneous enhancements\n\n- Console output coloring (see below)\n- `: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.\n- The new `--driver-logging-level` command line parameter allows you to see traces from the `go-mssqldb` client driver. Use `64` to see all traces.\n- Sqlcmd can now print results using a vertical format. Use the new `-F vertical` command line option to set it. It's also controlled by the `SQLCMDFORMAT` scripting variable.\n\n```\n1\u003e select session_id, client_interface_name, program_name from sys.dm_exec_sessions where session_id=@@spid\n2\u003e go\nsession_id            58\nclient_interface_name go-mssqldb\nprogram_name          sqlcmd\n```\n\n- `sqlcmd` supports shared memory and named pipe transport. Use the appropriate protocol prefix on the server name to force a protocol:\n  * `lpc` for shared memory, only for a localhost.                           `sqlcmd -S lpc:.`\n  * `np` for named pipes. Or use the UNC named pipe path as the server name: `sqlcmd -S \\\\myserver\\pipe\\sql\\query`\n  * `tcp` for tcp                                                            `sqlcmd -S tcp:myserver,1234`\n  If no protocol is specified, sqlcmd will attempt to dial in this order: lpc-\u003enp-\u003etcp. If dialing a remote host, `lpc` will be skipped.\n\n```\n1\u003e select net_transport from sys.dm_exec_connections where session_id=@@spid\n2\u003e go\nnet_transport Named pipe\n```\n\n### Azure Active Directory Authentication\n\n`sqlcmd` supports a broader range of AAD authentication models (over the original ODBC based `sqlcmd`), based on the [azidentity package](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity). The implementation relies on an AAD Connector in the [driver](https://github.com/microsoft/go-mssqldb).\n\n#### Command line\n\nTo use AAD auth, you can use one of two command line switches:\n\n`-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.\n\n`--authentication-method=` can be used to specify one of the following authentication types.\n\n`ActiveDirectoryDefault`\n\n- For an overview of the types of authentication this mode will use, see (\u003chttps://github.com/Azure/azure-sdk-for-go/tree/main/sdk/azidentity#defaultazurecredential\u003e).\n- Choose this method if your database automation scripts are intended to run in both local development environments and in a production deployment in Azure. You'll be able to use a client secret or an Azure CLI login on your development environment and a managed identity or client secret on your production deployment without changing the script.\n- 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:\n\n  - Setting environment variable AZURE_CLIENT_SECRET configures the DefaultAzureCredential to choose ClientSecretCredential.\n  - Setting environment variable AZURE_CLIENT_CERTIFICATE_PATH configures the DefaultAzureCredential to choose ClientCertificateCredential if AZURE_CLIENT_SECRET is not set.\n  - Setting environment variable AZURE_USERNAME configures the DefaultAzureCredential to choose UsernamePasswordCredential if AZURE_CLIENT_SECRET and AZURE_CLIENT_CERTIFICATE_PATH are not set.\n\n`ActiveDirectoryIntegrated`\n\nThis method is currently not implemented and will fall back to `ActiveDirectoryDefault`.\n\n`ActiveDirectoryPassword`\n\nThis method will authenticate using a username and password. It will not work if MFA is required.\nYou provide the username and password using the usual command line switches or SQLCMD environment variables.\nSet `AZURE_TENANT_ID` environment variable to the tenant id of the server if not using the default tenant of the user.\n\n`ActiveDirectoryInteractive`\n\nThis method will launch a web browser to authenticate the user.\n\n`ActiveDirectoryManagedIdentity`\n\nUse 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.\n\n`ActiveDirectoryServicePrincipal`\n\nThis 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 `\u003cservice principal id\u003e@\u003ctenant id\u003e`. 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.\n\n#### Environment variables for AAD auth\n\nSome settings for AAD auth do not have command line inputs, and some environment variables are consumed directly by the `azidentity` package used by `sqlcmd`.\nThese 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.\n\n`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.\n\n### Console colors\n\nSqlcmd now supports syntax coloring the output of `:list` and the results of TSQL queries when output to the terminal.\nTo 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](https://github.com/alecthomas/chroma/tree/master/styles) project. \n\nTo see a list of available styles along with colored syntax samples, use this command in interactive mode:\n\n```\n:list color\n```\n\n### Packages\n\n#### sqlcmd executable\n\nBuild [sqlcmd](cmd/modern)\n\n```sh\n./build/build.sh\n```\nor\n```\n.\\build\\build.cmd\n```\n\n#### sqlcmd package\n\npkg/sqlcmd is consumable by other hosts. Go docs for the package are forthcoming. See the test code and [main.go](cmd/sqlcmd/main.go) for examples of initializing and running sqlcmd.\n\n## Building\n\n```sh\nbuild/build\n```\n\n## Testing\n\nThe tests rely on SQLCMD scripting variables to provide the connection string parameters. Set SQLCMDSERVER, SQLCMDDATABASE, SQLCMDUSER, SQLCMDPASSWORD variables appropriately then\n\n```sh\ngo test ./...\n```\n\nIf 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:\n\n```cmd\ndocker run -rm -e SQLCMDSERVER=\u003cyourserver\u003e -e SQLCMDUSER=\u003cyouruser\u003e -e SQLCMDPASSWORD=\u003cyourpassword\u003e -v i:\\git\\go-sqlcmd:/go-sqlcmd -w /go-sqlcmd golang:1.16 go test ./...\n```\n\n## Localization\nThe new sqlcmd (go-sqlcmd) is localized for the following languages:\nChinese (Simplified) | Chinese (Traditional) | English (United States) | French | German | Italian | Japanese | Korean | Portuguese (Brazil) | Russian | Spanish\n\nCurrently, 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.\n\nTo get localized messages from `sqlcmd` set environment variable SQLCMD_LANG to a language tag as per BCP47 convention.\ne.g.\n```\n\\git\\go-sqlcmd\u003eset SQLCMD_LANG=de-de\n\\git\\go-sqlcmd\u003e.\\sqlcmd.exe -w 4\nsqlcmd.exe: error: sqlcmd.exe: '-w 4': Der Wert muss größer als 8 und kleiner als 65536 sein.\n```\n\n## Contributing\n\nThis project welcomes contributions and suggestions.  Most contributions require you to agree to a\nContributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us\nthe rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.\n\nWhen you submit a pull request, a CLA bot will automatically determine whether you need to provide\na CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions\nprovided by the bot. You will only need to do this once across all repos using our CLA.\n\nThis project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).\nFor more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or\ncontact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.\n\n## Trademarks\n\nThis project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft\ntrademarks or logos is subject to and must follow\n[Microsoft's Trademark \u0026 Brand Guidelines](https://www.microsoft.com/legal/intellectualproperty/trademarks/usage/general).\nUse of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.\nAny use of third-party trademarks or logos are subject to those third-party's policies.\n\n[Community Buzz]: https://github.com/microsoft/go-sqlcmd/discussions/367\n[Homebrew]: https://formulae.brew.sh/formula/sqlcmd\n[Linuxbrew]: https://docs.brew.sh/Homebrew-on-Linux\n[Winget]: https://github.com/microsoft/winget-pkgs/tree/master/manifests/m/Microsoft/Sqlcmd\n[Choco]: https://community.chocolatey.org/packages/sqlcmd\n[Docker]: https://www.docker.com/products/docker-desktop/\n[Podman]: https://podman-desktop.io/downloads/\n[releases page]: https://github.com/microsoft/go-sqlcmd/releases/latest\n[go-mssqldb]: https://github.com/microsoft/go-mssqldb\n[go-sqlcmd-utility]: https://docs.microsoft.com/sql/tools/go-sqlcmd-utility\n","funding_links":[],"categories":["Tools"],"sub_categories":["Vectors"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2Fgo-sqlcmd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrosoft%2Fgo-sqlcmd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2Fgo-sqlcmd/lists"}