Skip to content

Commit f7deb1f

Browse files
stuartpastuartpa
authored
Update README to cover new sceanrios (#302)
1 parent 57aedc8 commit f7deb1f

File tree

1 file changed

+115
-22
lines changed

1 file changed

+115
-22
lines changed

‎README.md‎

Lines changed: 115 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,109 @@
1-
# Go-based SQL Utilities - Preview
1+
# SQLCMD CLI - Preview
22

3-
This repo contains command line tools and go packages for working with Microsoft SQL Server, Azure SQL Database, and Azure Synapse.
3+
This repo contains the `sqlcmd` command line tool and go packages for working with Microsoft SQL Server, Azure SQL Database, and Azure Synapse.
4+
5+
## Installation
6+
7+
`sqlcmd` is available in package managers for all major platforms.
8+
9+
### Windows
10+
11+
`sqlcmd` is available via [Winget][], and as a downloadable .msi or .zip from the [releases page][]. The .msi installer is signed with a Microsoft Authenticode certificate.
12+
13+
#### WinGet
14+
15+
| Install: | Upgrade: |
16+
| ----------------------- | ----------------------- |
17+
| `winget install sqlcmd` | `winget upgrade sqlcmd` |
18+
19+
### macOS
20+
21+
`sqlcmd` is available via [Homebrew][], and as a downloadable .tar from the [releases page][].
22+
23+
#### Homebrew
24+
25+
| Install: | Upgrade: |
26+
| --------------------- | --------------------- |
27+
| `brew install sqlcmd` | `brew upgrade sqlcmd` |
28+
29+
### Linux
30+
31+
`sqlcmd` is available via [Linuxbrew][], and as a downloadable .rpm/.deb and .tar from the [releases page][].
32+
33+
On 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).
34+
35+
#### Linuxbrew
36+
37+
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.
38+
39+
| Install: | Upgrade: |
40+
| --------------------- | --------------------- |
41+
| `brew install sqlcmd` | `brew upgrade sqlcmd` |
42+
43+
## Use sqlcmd to create local SQL Server and Azure SQL Edge instances
44+
45+
Use `sqlcmd` to create SQL Server and Azure SQL Edge instances using a local container runtime (e.g. [Docker][] or [Podman][])
46+
47+
### Create SQL Server instance using local container runtime and connect using Azure Data Studio
48+
49+
To create a local SQL Server instance with the AdventureWorksLT database restored, query it, and connect to it using Azure Data Studio, run:
50+
51+
```
52+
sqlcmd create mssql --accept-eula --using https://aka.ms/AdventureWorksLT.bak
53+
sqlcmd query "SELECT DB_NAME()"
54+
sqlcmd open ads
55+
```
56+
57+
Use `sqlcmd --help` to view all the available sub-commands. Use `sqlcmd -?` to view the original ODBC `sqlcmd` flags.
58+
59+
### The ~/.sqlcmd/sqlconfig file
60+
61+
Each time `sqlcmd create` completes, a new context is created (e.g. mssql, mssql2, mssql3 etc.). A context contains the endpoint and user configuation 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`.
62+
63+
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:
64+
65+
```
66+
sqlcmd config connection-strings
67+
sqlcmd config view
68+
```
69+
70+
### Versions
71+
72+
To see all version tags to choose from (2017, 2019, 2022 etc.), and install a specific version, run:
73+
74+
```
75+
SET SQLCMD_ACCEPT_EULA=YES
76+
77+
sqlcmd create mssql get-tags
78+
sqlcmd create mssql --tag 2019-latest
79+
```
80+
81+
To stop, start and delete contexts, run the following commands:
82+
83+
```
84+
sqlcmd stop
85+
sqlcmd start
86+
sqlcmd delete
87+
```
88+
89+
### Backwards compatibility with ODBC sqlcmd
90+
91+
To connect to the current context, and use the original ODBC sqlcmd flags (e.g. -q, -Q, -i, -o etc.), that can be listed with `sqlcmd -?`, run:
92+
93+
```
94+
sqlcmd -q "SELECT @@version"
95+
sqlcmd
96+
```
97+
98+
If no current context exists, `sqlcmd` (with no connection parameters) reverts to the original ODBC `sqlcmd` behavior of connecting to the default local instance on port 1433 using trusted authentication.
499

5100
## Sqlcmd
6101

7-
The `sqlcmd` project aims to be a complete port of the native sqlcmd to the `Go` language, utilizing the [go-mssqldb](https://github.com/microsoft/go-mssqldb) driver. For full documentation of the tool and installation instructions, see https://docs.microsoft.com/sql/tools/go-sqlcmd-utility
102+
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][].
8103

9-
### Breaking changes
104+
### Changes in behavior from the ODBC based sqlcmd
10105

11-
We will be implementing command line switches and behaviors over time. Several switches and behaviors are expected to change in this implementation.
106+
The following switches have different behavior in this version of `sqlcmd` compared to the oroignla ODBC based `sqlcmd`.
12107

13108
- `-P` switch will be removed. Passwords for SQL authentication can only be provided through these mechanisms:
14109

@@ -36,15 +131,14 @@ We will be implementing command line switches and behaviors over time. Several s
36131
- 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.
37132

38133
```
39-
40134
1> select session_id, client_interface_name, program_name from sys.dm_exec_sessions where session_id=@@spid
41135
2> go
42136
session_id 58
43137
client_interface_name go-mssqldb
44138
program_name sqlcmd
45-
46139
```
47-
- Sqlcmd now supports shared memory and named pipe transport. Use the appropriate protocol prefix on the server name to force a protocol
140+
141+
- `sqlcmd` supports shared memory and named pipe transport. Use the appropriate protocol prefix on the server name to force a protocol:
48142
* `lpc` for shared memory, only for a localhost. `sqlcmd -S lpc:.`
49143
* `np` for named pipes. Or use the UNC named pipe path as the server name: `sqlcmd -S \\myserver\pipe\sql\query`
50144
* `tcp` for tcp `sqlcmd -S tcp:myserver,1234`
@@ -54,16 +148,15 @@ program_name sqlcmd
54148
1> select net_transport from sys.dm_exec_connections where session_id=@@spid
55149
2> go
56150
net_transport Named pipe
57-
58151
```
59152

60153
### Azure Active Directory Authentication
61154

62-
This version of sqlcmd supports a broader range of AAD authentication models, 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).
155+
`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).
63156

64157
#### Command line
65158

66-
To use AAD auth, you can use one of two command line switches
159+
To use AAD auth, you can use one of two command line switches:
67160

68161
`-G` is (mostly) compatible with its usage in the prior version of sqlcmd. If a user name and password are provided, it will authenticate using AAD Password authentication. If a user name is provided it will use AAD Interactive authentication which may display a web browser. If no user name or password is provided, it will use a DefaultAzureCredential which attempts to authenticate through a variety of mechanisms.
69162

@@ -81,7 +174,7 @@ To use AAD auth, you can use one of two command line switches
81174

82175
`ActiveDirectoryIntegrated`
83176

84-
This method is currently not implemented and will fall back to `ActiveDirectoryDefault`
177+
This method is currently not implemented and will fall back to `ActiveDirectoryDefault`.
85178

86179
`ActiveDirectoryPassword`
87180

@@ -101,14 +194,14 @@ Use this method when running sqlcmd on an Azure VM that has either a system-assi
101194

102195
This method authenticates the provided user name as a service principal id and the password as the client secret for the service principal. Provide a user name 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.
103196

104-
### Environment variables for AAD auth
197+
#### Environment variables for AAD auth
105198

106199
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`.
107200
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.
108201

109202
`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.
110203

111-
## Console colors
204+
### Console colors
112205

113206
Sqlcmd now supports syntax coloring the output of `:list` and the results of TSQL queries when output to the terminal.
114207
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](https://github.com/alecthomas/chroma/tree/master/styles) project.
@@ -139,30 +232,22 @@ pkg/sqlcmd is consumable by other hosts. Go docs for the package are forthcoming
139232

140233
## Building
141234

142-
143235
```sh
144-
145236
build/build
146-
147237
```
148238

149-
150239
## Testing
151240

152241
The tests rely on SQLCMD scripting variables to provide the connection string parameters. Set SQLCMDSERVER, SQLCMDDATABASE, SQLCMDUSER, SQLCMDPASSWORD variables appropriately then
153242

154243
```sh
155-
156244
go test ./...
157-
158245
```
159246

160247
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:
161248

162249
```cmd
163-
164250
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 ./...
165-
166251
```
167252

168253
## Contributing
@@ -187,3 +272,11 @@ trademarks or logos is subject to and must follow
187272
Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
188273
Any use of third-party trademarks or logos are subject to those third-party's policies.
189274

275+
[Homebrew]: https://formulae.brew.sh/formula/sqlcmd
276+
[Linuxbrew]: https://docs.brew.sh/Homebrew-on-Linux
277+
[Winget]: https://github.com/microsoft/winget-pkgs/tree/master/manifests/m/Microsoft/Sqlcmd
278+
[Docker]: https://www.docker.com/products/docker-desktop/
279+
[Podman]: https://podman-desktop.io/downloads/
280+
[releases page]: https://github.com/microsoft/go-sqlcmd/releases/latest
281+
[go-mssqldb]: https://github.com/microsoft/go-mssqldb
282+
[go-sqlcmd-utility]: https://docs.microsoft.com/sql/tools/go-sqlcmd-utility

0 commit comments

Comments
 (0)