Skip to content

docs: update README for documentation freshness #639

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dlevy-msft-sql wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: update README for documentation freshness #639

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
184392c
docs: update README for documentation freshness
dlevy-msft-sql Jan 26, 2026
7577d45
Merge branch 'main' into docs/fix-readme-freshness
dlevy-msft-sql Apr 16, 2026
86073c5
docs: fix inaccurate ActiveDirectoryIntegrated description and improv…
dlevy-msft-sql Apr 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 30 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -162,16 +162,20 @@ The following switches have different behavior in this version of `sqlcmd` compa

### Switches not available in the new sqlcmd (go-sqlcmd) yet

There are a few switches yet to be implemented in the new `sqlcmd` (go-sqlcmd) compared
to the original ODBC based `sqlcmd`, discussion [#293](https://github.com/microsoft/go-sqlcmd/discussions/292)
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.
Most switches from the original ODBC-based `sqlcmd` have been implemented. The following switches are not yet available:

| Switch | Description |
|--------|-------------|
| `-f` | Input/output code page |
| `-j` | Print raw error messages |
| `-p[1]` | Print statistics (optional colon format) |

For historical context and to provide feedback, see [discussion #292](https://github.com/microsoft/go-sqlcmd/discussions/292).

### Miscellaneous enhancements

- Console output coloring (see below)
- `: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.
- `:Connect` now has an optional `-G` parameter to select one of the authentication methods for Azure SQL Database - `SqlAuthentication`, `ActiveDirectoryDefault`, `ActiveDirectoryIntegrated`, `ActiveDirectoryServicePrincipal`, `ActiveDirectoryManagedIdentity`, `ActiveDirectoryPassword`, `ActiveDirectoryInteractive`, `ActiveDirectoryAzCli`, `ActiveDirectoryDeviceCode`. If `-G` is not provided, either Integrated security or SQL Authentication will be used, dependent on the presence of a `-U` username parameter.
Copy link

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SqlAuthentication is not a supported value in this repo (the code and help text use SqlPassword). Listing SqlAuthentication under :Connect -G will cause users to pass an auth method that the implementation treats as AAD, likely resulting in a connection error. Replace it with SqlPassword (or remove SQL auth from the -G list and document that SQL auth is selected by using -U/-P without -G).

Suggested change
- `:Connect` now has an optional `-G` parameter to select one of the authentication methods for Azure SQL Database - `SqlAuthentication`, `ActiveDirectoryDefault`, `ActiveDirectoryIntegrated`, `ActiveDirectoryServicePrincipal`, `ActiveDirectoryManagedIdentity`, `ActiveDirectoryPassword`, `ActiveDirectoryInteractive`, `ActiveDirectoryAzCli`, `ActiveDirectoryDeviceCode`. If `-G` is not provided, either Integrated security or SQL Authentication will be used, dependent on the presence of a `-U` username parameter.
- `:Connect` now has an optional `-G` parameter to select one of the authentication methods for Azure SQL Database - `SqlPassword`, `ActiveDirectoryDefault`, `ActiveDirectoryIntegrated`, `ActiveDirectoryServicePrincipal`, `ActiveDirectoryManagedIdentity`, `ActiveDirectoryPassword`, `ActiveDirectoryInteractive`, `ActiveDirectoryAzCli`, `ActiveDirectoryDeviceCode`. If `-G` is not provided, either Integrated security or SQL Authentication will be used, dependent on the presence of a `-U` username parameter.

Copilot uses AI. Check for mistakes.
- 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.
- Sqlcmd can now print results using a vertical format. Use the new `--vertical` command line option to set it. It's also controlled by the `SQLCMDFORMAT` scripting variable.

Expand Down Expand Up @@ -219,7 +223,7 @@ To use AAD auth, you can use one of two command line switches:

`ActiveDirectoryIntegrated`

This method is currently not implemented and will fall back to `ActiveDirectoryDefault`.
This method is not fully implemented in the go-mssqldb driver and currently falls back to `ActiveDirectoryDefault`.
Copy link

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PR description says the outdated fallback behavior for ActiveDirectoryIntegrated was removed because it is now fully implemented, but the updated README text still states it "falls back to ActiveDirectoryDefault". Please align the README with the actual intended behavior (or adjust the PR description if fallback is still expected).

Copilot uses AI. Check for mistakes.

`ActiveDirectoryPassword`

Expand All @@ -239,6 +243,26 @@ Use this method when running sqlcmd on an Azure VM that has either a system-assi

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.

`ActiveDirectoryAzCli`

This method uses the Azure CLI to obtain an access token. You must be logged in to Azure CLI (`az login`) before using this method.

`ActiveDirectoryDeviceCode`

This method uses the device code flow for authentication. It displays a code that you enter at https://microsoft.com/devicelogin to authenticate.

#### Additional authentication methods

The following authentication methods are also supported via `--authentication-method`:

- `ActiveDirectoryWorkloadIdentity` - Uses federated token authentication for Kubernetes or GitHub Actions workloads; optionally provide `client_id@tenant_id` as username and `tokenfilepath` parameter (defaults to `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_FEDERATED_TOKEN_FILE` env vars)
- `ActiveDirectoryClientAssertion` - Authenticates with a signed JWT assertion instead of a client secret
- `ActiveDirectoryAzurePipelines` - Authenticates using an Azure Pipelines service connection; requires `client_id@tenant_id` as username, plus `serviceconnectionid` and `systemtoken` connection parameters (or `AZURESUBSCRIPTION_CLIENT_ID`, `AZURESUBSCRIPTION_SERVICE_CONNECTION_ID`, `SYSTEM_ACCESSTOKEN` env vars)
Comment on lines +258 to +260
Copy link

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The bullets for ActiveDirectoryWorkloadIdentity / ActiveDirectoryAzurePipelines mention extra "connection parameters" like tokenfilepath, serviceconnectionid, and systemtoken, but the legacy sqlcmd CLI only accepts -S in the server[\\instance][,port] form and doesn't expose a way to supply arbitrary query parameters. Clarify how users are expected to provide these values (e.g., via specific environment variables only), or remove the parameter mentions to avoid implying unsupported inputs.

Suggested change
- `ActiveDirectoryWorkloadIdentity` - Uses federated token authentication for Kubernetes or GitHub Actions workloads; optionally provide `client_id@tenant_id` as username and `tokenfilepath` parameter (defaults to `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_FEDERATED_TOKEN_FILE` env vars)
- `ActiveDirectoryClientAssertion` - Authenticates with a signed JWT assertion instead of a client secret
- `ActiveDirectoryAzurePipelines` - Authenticates using an Azure Pipelines service connection; requires `client_id@tenant_id` as username, plus `serviceconnectionid` and `systemtoken` connection parameters (or `AZURESUBSCRIPTION_CLIENT_ID`, `AZURESUBSCRIPTION_SERVICE_CONNECTION_ID`, `SYSTEM_ACCESSTOKEN` env vars)
- `ActiveDirectoryWorkloadIdentity` - Uses federated token authentication for Kubernetes or GitHub Actions workloads; optionally provide `client_id@tenant_id` as username, and use `AZURE_FEDERATED_TOKEN_FILE` to specify the token file path (`AZURE_CLIENT_ID` and `AZURE_TENANT_ID` are also used when username is not provided)
- `ActiveDirectoryClientAssertion` - Authenticates with a signed JWT assertion instead of a client secret
- `ActiveDirectoryAzurePipelines` - Authenticates using an Azure Pipelines service connection; requires `client_id@tenant_id` as username, and uses `AZURESUBSCRIPTION_SERVICE_CONNECTION_ID` and `SYSTEM_ACCESSTOKEN` environment variables (`AZURESUBSCRIPTION_CLIENT_ID` can also be used when username is not provided)

Copilot uses AI. Check for mistakes.
- `ActiveDirectoryEnvironment` - Selects a credential type automatically based on which `AZURE_*` environment variables are set (client secret, certificate, or username/password)
- `ActiveDirectoryAzureDeveloperCli` - Uses credentials from `azd auth login` (Azure Developer CLI)
- `ActiveDirectoryServicePrincipalAccessToken` - Uses a pre-obtained bearer token; set `SQLCMDPASSWORD` to the access token value
Copy link

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section says ActiveDirectoryServicePrincipalAccessToken works by setting SQLCMDPASSWORD to the access token, but the current implementation never includes the provided password in the connection string for this auth method (so the token is not passed into GetTokenBasedConnection). Either update the documentation to match current behavior, or update the implementation to propagate the token for this method.

Suggested change
- `ActiveDirectoryServicePrincipalAccessToken` - Uses a pre-obtained bearer token; set `SQLCMDPASSWORD` to the access token value
- `ActiveDirectoryServicePrincipalAccessToken` - Uses a pre-obtained bearer token; `SQLCMDPASSWORD` is not currently used to pass the access token for this method

Copilot uses AI. Check for mistakes.
- `SqlPassword` - SQL Server authentication (equivalent to `-U` and `-P` without `-G`)

#### Environment variables for AAD auth

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`.
Expand Down
Loading