feat: implement :perftrace and :help commands

[dlevy-msft-sql]

Summary

Adds two new interactive commands: :help and :perftrace.

:help displays a reference of all available sqlcmd commands with short descriptions. It can also show help for a single command: :help connect.

:perftrace redirects performance statistics output (from the -p flag, PR #631) to a file, stderr, or stdout -- the same way :out and :error redirect query and error output.

New commands

Command	Description
:help	Lists all available commands with descriptions
:help <command>	Shows help for a single command (case-insensitive)
:perftrace <file>	Redirects timing output to a file, stderr, or stdout

Usage

1> :help
:!! [<command>]
  - Executes a command in the operating system shell.
:connect server[\instance] [-l timeout] [-U user [-P password]]
  - Connects to a SQL Server instance.
...

1> :help connect
:connect server[\instance] [-l timeout] [-U user [-P password]]
  - Connects to a SQL Server instance.

1> :perftrace c:/logs/perf.txt
1> select 1
2> go

Implementation

• Added a help field to the Command struct. Every registered command carries its own help text, so :help output is always in sync with the command registry. A TestAllCommandsHaveHelp test guards against drift.
• :help <command> does a case-insensitive lookup into the command map. Unknown names fall through to the full listing.
• Extracted redirectWriter() to share file/stderr/stdout resolution logic across :out, :error, and :perftrace (was duplicated between outCommand and errorCommand).
• Added stat (io.WriteCloser) field to Sqlcmd with GetStat()/SetStat() accessors. GetStat() falls back to GetOutput() when no :perftrace redirection is active, so existing -p output is unaffected.
• SetStat(nil) called during cleanup in cmd/sqlcmd/sqlcmd.go to close any open perf trace file.

Testing

• TestHelpCommand: full listing, per-command filtering, case-insensitive lookup, unknown command fallback
• TestAllCommandsHaveHelp: drift guard ensuring every command has help text
• TestPerftraceCommand: empty arg error, stdout, stderr, file redirect, variable resolution
• TestCommandParsing: parsing for :help, :help CONNECT, :perftrace stderr, etc.
• All tests run without a database connection

Merge notes

• Merge after PR feat: implement -p flag for print statistics #631 (-p flag). After both merge, update the printStatistics() call site to use GetStat() instead of GetOutput().
• PR feat: implement :serverlist command #630 (:serverlist) also registers a HELP command. Merge this PR first, then rebase feat: implement :serverlist command #630.

Fixes #622.

[Copilot]

Pull request overview

This PR implements the :perftrace command to redirect performance statistics output to a file, stderr, or stdout, working in conjunction with the -p flag from PR #631.

Changes:

• Added stat writer infrastructure with GetStat/SetStat methods following the established pattern for output/error writers
• Implemented PERFTRACE command supporting file paths, "stdout", and "stderr" with variable substitution
• Added comprehensive test coverage for the command functionality

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
pkg/sqlcmd/sqlcmd.go	Added stat field and GetStat()/SetStat() methods for managing performance statistics output writer
pkg/sqlcmd/commands.go	Registered PERFTRACE command and implemented perftraceCommand() function with file/stdout/stderr support
pkg/sqlcmd/commands_test.go	Added TestPerftraceCommand() with comprehensive test scenarios and added PERFTRACE parsing tests
README.md	Documented the :perftrace command with usage example

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.