Skip to content

Commit c9de1df

Browse files
Copilotshueybubbles
Copilot
and
shueybubbles
committed
Add .github/copilot-instructions.md with repository guidelines
Co-authored-by: shueybubbles <2224906+shueybubbles@users.noreply.github.com>
1 parent 867cac8 commit c9de1df

File tree

1 file changed

+221
-0
lines changed

1 file changed

+221
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
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 Subcommand
182+
183+
1. Create a new file in `cmd/modern/root/` (e.g., `mycommand.go`)
184+
2. Define the command struct and implement the `Run` method
185+
3. Register the command in the root command
186+
4. Add corresponding tests in `mycommand_test.go`
187+
188+
### Adding a New Configuration Option
189+
190+
1. Update the config struct in `internal/config/config.go`
191+
2. Add validation if needed
192+
3. Update the Viper bindings in `internal/config/viper.go`
193+
4. Add tests
194+
195+
### Working with SQL Connections
196+
197+
- Use `pkg/sqlcmd` for SQL connection management
198+
- Connection options are defined in `pkg/sqlcmd/connect.go`
199+
- Support for various transports: TCP, named pipes, shared memory
200+
201+
## CI/CD
202+
203+
- GitHub Actions workflows are in `.github/workflows/`
204+
- `golangci-lint.yml` - Linting with golangci-lint
205+
- `pr-validation.yml` - Build and test validation for PRs
206+
- Azure Pipelines configurations are in `.pipelines/`
207+
208+
## Linting
209+
210+
The project uses golangci-lint. To run locally:
211+
212+
```bash
213+
golangci-lint run
214+
```
215+
216+
## Useful Resources
217+
218+
- [go-mssqldb driver](https://github.com/microsoft/go-mssqldb)
219+
- [sqlcmd documentation](https://docs.microsoft.com/sql/tools/go-sqlcmd-utility)
220+
- [Cobra CLI library](https://github.com/spf13/cobra)
221+
- [Viper configuration library](https://github.com/spf13/viper)

0 commit comments

Comments
 (0)