Skip to content

Commit 56b1fb1

Browse files
Copilotshueybubblesdlevy-msft-sql
authored
Add copilot-instructions.md for go-sqlcmd repository (#611)
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: shueybubbles <2224906+shueybubbles@users.noreply.github.com> Co-authored-by: David Levy <dlevy@microsoft.com>
1 parent 758fca9 commit 56b1fb1

File tree

1 file changed

+259
-0
lines changed

1 file changed

+259
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 259 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,259 @@
1+
# GitHub Copilot Instructions for go-sqlcmd
2+
3+
This document provides guidance for GitHub Copilot when working with the go-sqlcmd repository.
4+
5+
## Project Overview
6+
7+
go-sqlcmd is a Go-based command line tool (`sqlcmd`) for working with Microsoft SQL Server, Azure SQL Database, and Azure Synapse. The project aims to be a complete port of the original ODBC sqlcmd to Go, utilizing the [go-mssqldb](https://github.com/microsoft/go-mssqldb) driver.
8+
9+
## Repository Structure
10+
11+
```
12+
/
13+
├── cmd/ # Entry points for the application
14+
│ ├── modern/ # Modern CLI entry point (Cobra-based)
15+
│ │ ├── root/ # Root command and subcommands
16+
│ │ └── sqlconfig/ # SQL configuration management
17+
│ └── sqlcmd/ # Legacy CLI entry point (Kong-based)
18+
├── pkg/ # Public packages consumable by other hosts
19+
│ └── sqlcmd/ # Core sqlcmd functionality
20+
├── internal/ # Internal packages (not for external use)
21+
│ ├── buffer/ # Buffer management
22+
│ ├── cmdparser/ # Command parsing utilities
23+
│ ├── color/ # Console coloring
24+
│ ├── config/ # Configuration management
25+
│ ├── container/ # Docker/Podman container management
26+
│ ├── credman/ # Credential management
27+
│ ├── http/ # HTTP utilities
28+
│ ├── io/ # I/O utilities
29+
│ ├── localizer/ # Localization support
30+
│ ├── net/ # Network utilities
31+
│ ├── output/ # Output formatting
32+
│ ├── pal/ # Platform abstraction layer
33+
│ ├── secret/ # Secret/credential management
34+
│ ├── sql/ # SQL-related utilities
35+
│ ├── test/ # Test utilities
36+
│ ├── tools/ # Development tools
37+
│ └── translations/ # Localized string translations
38+
├── build/ # Build scripts and templates
39+
├── testdata/ # Test data files
40+
├── release/ # Release-related files
41+
└── .github/ # GitHub workflows and configurations
42+
```
43+
44+
## Building the Project
45+
46+
### Build Commands
47+
48+
```bash
49+
# Build the sqlcmd executable
50+
./build/build.sh # Linux/macOS
51+
.\build\build.cmd # Windows
52+
53+
# Or build directly with Go
54+
go build -o sqlcmd ./cmd/modern
55+
```
56+
57+
### Dependencies
58+
59+
The project uses Go modules. Run `go mod download` to fetch dependencies.
60+
61+
## Testing
62+
63+
### Running Tests
64+
65+
```bash
66+
# Run all tests
67+
go test ./...
68+
69+
# Run tests with verbose output
70+
go test -v ./...
71+
72+
# Run tests for a specific package
73+
go test -v ./pkg/sqlcmd/...
74+
go test -v ./internal/config/...
75+
```
76+
77+
### Test Environment Variables
78+
79+
Tests may require the following environment variables for database connectivity:
80+
- `SQLCMDSERVER` - SQL Server hostname
81+
- `SQLCMDPORT` - SQL Server port (default: 1433)
82+
- `SQLCMDUSER` - Username (e.g., `sa`)
83+
- `SQLCMDPASSWORD` - Password
84+
- `SQLCMDDATABASE` - Database name
85+
86+
## Code Style and Conventions
87+
88+
### Go Standards
89+
90+
- Follow standard Go conventions and idioms
91+
- Use `gofmt` for formatting
92+
- Use tabs for indentation (as specified in `.editorconfig`)
93+
- Follow effective Go guidelines: https://go.dev/doc/effective_go
94+
95+
### File Headers
96+
97+
All Go files should include the following copyright header:
98+
```go
99+
// Copyright (c) Microsoft Corporation.
100+
// Licensed under the MIT license.
101+
```
102+
103+
### Package Documentation
104+
105+
Each package should have a `doc.go` file with package-level documentation.
106+
107+
### Error Handling
108+
109+
- Use the standard Go error handling patterns
110+
- For user-facing errors, prefer localized error messages via the `internal/localizer` package
111+
- Wrap errors with context when propagating
112+
113+
### Naming Conventions
114+
115+
- Use camelCase for unexported identifiers
116+
- Use PascalCase for exported identifiers
117+
- Acronyms should be all uppercase (e.g., `SQL`, `URL`, `HTTP`)
118+
- Package names should be lowercase, single-word if possible
119+
120+
## CLI Architecture
121+
122+
### Modern CLI (Cobra-based)
123+
124+
The modern CLI is located in `cmd/modern/` and uses the [Cobra](https://github.com/spf13/cobra) library. Key points:
125+
- Root command is in `cmd/modern/root.go`
126+
- Subcommands are in `cmd/modern/root/` directory
127+
- Uses dependency injection for testability
128+
129+
### Legacy CLI (Kong-based)
130+
131+
The legacy CLI is in `cmd/sqlcmd/` and maintains backward compatibility with the original ODBC sqlcmd.
132+
133+
### Command Structure
134+
135+
When adding new commands:
136+
1. Create the command in `cmd/modern/root/`
137+
2. Follow the existing pattern for subcommands (see `query.go`, `start.go`, `stop.go`)
138+
3. Add corresponding tests with `_test.go` suffix
139+
140+
## Configuration
141+
142+
- Configuration files are stored in `~/.sqlcmd/sqlconfig`
143+
- Use the `internal/config` package for configuration management
144+
- Viper is used for configuration parsing (`internal/config/viper.go`)
145+
146+
## Container Support
147+
148+
The project supports creating SQL Server instances using Docker or Podman:
149+
- Container management is in `internal/container/`
150+
- Supports SQL Server and Azure SQL Edge images
151+
152+
## Localization
153+
154+
- Localized strings are in `internal/translations/`
155+
- Use the `internal/localizer` package for localized messages
156+
- Supported languages: Chinese (Simplified/Traditional), English, French, German, Italian, Japanese, Korean, Portuguese (Brazil), Russian, Spanish
157+
158+
## Azure Authentication
159+
160+
- Azure AD authentication is supported via the `azidentity` package
161+
- Authentication code is in `pkg/sqlcmd/azure_auth.go`
162+
- Supports multiple authentication methods: DefaultAzureCredential, Password, Interactive, ManagedIdentity, ServicePrincipal
163+
164+
## Security Considerations
165+
166+
- Never commit secrets or credentials
167+
- Use environment variables or secure credential stores for sensitive data
168+
- Follow the Microsoft Security Development Lifecycle (SDL)
169+
- Report security vulnerabilities via SECURITY.md
170+
171+
## Pull Request Guidelines
172+
173+
1. Ensure all tests pass locally
174+
2. Follow the existing code style
175+
3. Update documentation if adding new features
176+
4. Add tests for new functionality
177+
5. Keep commits focused and well-described
178+
179+
## Common Tasks
180+
181+
### Adding a New Command (Modern CLI)
182+
183+
For new commands related to context management, container operations, or configuration:
184+
185+
1. Create a new file in `cmd/modern/root/` (e.g., `mycommand.go`)
186+
2. Define a command struct that embeds `cmdparser.Cmd`
187+
3. Implement the `DefineCommand` method to set up command options, flags, and examples
188+
4. Implement the `run` method with the command logic
189+
5. Add corresponding tests in `mycommand_test.go`
190+
191+
Example structure:
192+
```go
193+
type MyCommand struct {
194+
cmdparser.Cmd
195+
// flags
196+
}
197+
198+
func (c *MyCommand) DefineCommand(...cmdparser.CommandOptions) {
199+
options := cmdparser.CommandOptions{
200+
Use: "mycommand",
201+
Short: localizer.Sprintf("Description"),
202+
Run: c.run,
203+
}
204+
c.Cmd.DefineCommand(options)
205+
// Add flags
206+
}
207+
208+
func (c *MyCommand) run() {
209+
// Command logic
210+
}
211+
```
212+
213+
### Adding a New Configuration Option (Modern CLI)
214+
215+
1. Update the config struct in `internal/config/config.go`
216+
2. Add validation if needed
217+
3. Update the Viper bindings in `internal/config/viper.go`
218+
4. Add tests
219+
220+
### Adding Features (Legacy CLI)
221+
222+
For new features related to querying SQL Server and displaying query results, add them to the legacy CLI:
223+
224+
1. Add new fields to the `SQLCmdArguments` struct in `cmd/sqlcmd/sqlcmd.go`
225+
2. Register new flags in the `setFlags` function
226+
3. Add validation logic in the `Validate` method if needed
227+
4. Determine from existing patterns whether to add a SQLCMD variable to support it
228+
5. Update `setVars` or `setConnect` functions to use the new arguments
229+
6. Implement the feature logic in the `run` function or related functions
230+
7. Add corresponding tests in `cmd/sqlcmd/sqlcmd_test.go`
231+
8. Update README.md to show example usage
232+
233+
### Working with SQL Connections
234+
235+
- Use `pkg/sqlcmd` for SQL connection management
236+
- Connection options are defined in `pkg/sqlcmd/connect.go`
237+
- Support for various transports: TCP, named pipes, shared memory
238+
239+
## CI/CD
240+
241+
- GitHub Actions workflows are in `.github/workflows/`
242+
- `golangci-lint.yml` - Linting with golangci-lint
243+
- `pr-validation.yml` - Build and test validation for PRs
244+
- Azure Pipelines configurations are in `.pipelines/`
245+
246+
## Linting
247+
248+
The project uses golangci-lint. To run locally:
249+
250+
```bash
251+
golangci-lint run
252+
```
253+
254+
## Useful Resources
255+
256+
- [go-mssqldb driver](https://github.com/microsoft/go-mssqldb)
257+
- [sqlcmd documentation](https://docs.microsoft.com/sql/tools/go-sqlcmd-utility)
258+
- [Cobra CLI library](https://github.com/spf13/cobra)
259+
- [Viper configuration library](https://github.com/spf13/viper)

0 commit comments

Comments
 (0)