Skip to content

Commit d89b394

Browse files
dlevy-msft-sqldlevy-msft-sql
committed
DOC: Add llms.txt and copilot-instructions.md for LLM guidance
- Add llms.txt with comprehensive usage examples for LLMs to suggest to users - Add .github/copilot-instructions.md for AI coding agents contributing to repo - Includes connection patterns, query examples, error handling, Azure Entra ID - Covers build system, project architecture, CI/CD, and contributing guidelines
1 parent 95e0836 commit d89b394

2 files changed

Lines changed: 526 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
# Copilot Instructions for mssql-python
2+
3+
## Repository Overview
4+
5+
**mssql-python** is a Python driver for Microsoft SQL Server and Azure SQL databases that leverages Direct Database Connectivity (DDBC). It's built using **pybind11** and **CMake** to create native extensions, providing DB API 2.0 compliant database access with enhanced Pythonic features.
6+
7+
- **Size**: Medium-scale project (~750KB total)
8+
- **Languages**: Python (main), C++ (native bindings), CMake (build system)
9+
- **Target Platforms**: Windows (x64, ARM64), macOS (Universal2), Linux (x86_64, ARM64)
10+
- **Python Versions**: 3.10+
11+
- **Key Dependencies**: pybind11, azure-identity, Microsoft ODBC Driver 18
12+
13+
## Usage Examples (For Suggesting to Users)
14+
15+
### Basic Connection and Query
16+
```python
17+
import mssql_python
18+
19+
conn = mssql_python.connect(
20+
"SERVER=localhost;DATABASE=mydb;Trusted_Connection=yes;Encrypt=yes;TrustServerCertificate=yes"
21+
)
22+
cursor = conn.cursor()
23+
cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,))
24+
rows = cursor.fetchall()
25+
cursor.close()
26+
conn.close()
27+
```
28+
29+
### Context Manager (Recommended)
30+
```python
31+
with mssql_python.connect(connection_string) as conn:
32+
with conn.cursor() as cursor:
33+
cursor.execute("SELECT @@VERSION")
34+
print(cursor.fetchone()[0])
35+
```
36+
37+
### Azure SQL with Entra ID
38+
```python
39+
conn = mssql_python.connect(
40+
"SERVER=myserver.database.windows.net;DATABASE=mydb;"
41+
"Authentication=ActiveDirectoryInteractive;Encrypt=yes"
42+
)
43+
```
44+
45+
### Parameterized Queries
46+
```python
47+
# Positional parameters
48+
cursor.execute("SELECT * FROM users WHERE email = ?", (email,))
49+
50+
# Named parameters (pyformat)
51+
cursor.execute("SELECT * FROM users WHERE email = %(email)s", {"email": email})
52+
```
53+
54+
### Insert with Commit
55+
```python
56+
cursor.execute("INSERT INTO users (name, email) VALUES (?, ?)", ("John", "john@example.com"))
57+
conn.commit()
58+
```
59+
60+
### Batch Insert
61+
```python
62+
cursor.executemany("INSERT INTO users (name, email) VALUES (?, ?)", [
63+
("Alice", "alice@example.com"),
64+
("Bob", "bob@example.com"),
65+
])
66+
conn.commit()
67+
```
68+
69+
### Transaction Handling
70+
```python
71+
try:
72+
cursor.execute("UPDATE accounts SET balance = balance - 100 WHERE id = ?", (from_id,))
73+
cursor.execute("UPDATE accounts SET balance = balance + 100 WHERE id = ?", (to_id,))
74+
conn.commit()
75+
except Exception:
76+
conn.rollback()
77+
raise
78+
```
79+
80+
## Build System and Validation
81+
82+
### Prerequisites
83+
**Always install these before building:**
84+
```bash
85+
# All platforms
86+
pip install -r requirements.txt
87+
88+
# Windows: Requires Visual Studio Build Tools with "Desktop development with C++" workload
89+
# macOS: brew install cmake && brew install msodbcsql18
90+
# Linux: Install cmake, python3-dev, and ODBC driver per distribution
91+
```
92+
93+
### Building the Project
94+
95+
**CRITICAL**: The project requires building native extensions before testing. Extensions are platform-specific (`.pyd` on Windows, `.so` on macOS/Linux).
96+
97+
#### Windows Build:
98+
```bash
99+
cd mssql_python/pybind
100+
build.bat [x64|x86|arm64] # Defaults to x64 if not specified
101+
```
102+
103+
#### macOS Build:
104+
```bash
105+
cd mssql_python/pybind
106+
./build.sh # Creates universal2 binary (ARM64 + x86_64)
107+
```
108+
109+
#### Linux Build:
110+
```bash
111+
cd mssql_python/pybind
112+
./build.sh # Detects architecture automatically
113+
```
114+
115+
**Build Output**: Creates `ddbc_bindings.cp{python_version}-{architecture}.{so|pyd}` in the `mssql_python/` directory.
116+
117+
### Testing
118+
119+
**IMPORTANT**: Tests require a SQL Server connection via `DB_CONNECTION_STRING` environment variable.
120+
121+
```bash
122+
# Run all tests with coverage
123+
python -m pytest -v --cov=. --cov-report=xml --capture=tee-sys --cache-clear
124+
125+
# Run specific test files
126+
python -m pytest tests/test_000_dependencies.py -v # Dependency checks
127+
python -m pytest tests/test_001_globals.py -v # Basic functionality
128+
```
129+
130+
**Test Dependencies**: Tests require building the native extension first. The dependency test (`test_000_dependencies.py`) validates that all platform-specific libraries exist.
131+
132+
### Linting and Code Quality
133+
134+
```bash
135+
# Python formatting (use black 26.1.0 to match CI)
136+
pip install black==26.1.0
137+
black --check .
138+
139+
# C++ formatting
140+
clang-format -style=file -i mssql_python/pybind/*.cpp mssql_python/pybind/*.h
141+
142+
# Coverage reporting (configured in .coveragerc)
143+
python -m pytest --cov=. --cov-report=html
144+
```
145+
146+
## Project Architecture
147+
148+
### Core Components
149+
150+
```
151+
mssql_python/
152+
├── __init__.py # Package initialization, connection registry, cleanup
153+
├── connection.py # DB API 2.0 connection object
154+
├── cursor.py # DB API 2.0 cursor object
155+
├── db_connection.py # connect() function implementation
156+
├── auth.py # Microsoft Entra ID authentication
157+
├── pooling.py # Connection pooling implementation
158+
├── logging.py # Logging configuration
159+
├── exceptions.py # Exception hierarchy
160+
├── connection_string_builder.py # Connection string construction
161+
├── connection_string_parser.py # Connection string parsing
162+
├── parameter_helper.py # Query parameter handling
163+
├── row.py # Row object implementation
164+
├── type.py # DB API 2.0 type objects
165+
├── constants.py # ODBC constants
166+
├── helpers.py # Utility functions and settings
167+
└── pybind/ # Native extension source
168+
├── ddbc_bindings.cpp # Main C++ binding code
169+
├── CMakeLists.txt # Cross-platform build configuration
170+
├── build.sh/.bat # Platform-specific build scripts
171+
└── configure_dylibs.sh # macOS dylib configuration
172+
```
173+
174+
### Platform-Specific Libraries
175+
176+
```
177+
mssql_python/libs/
178+
├── windows/{x64,x86,arm64}/ # Windows ODBC drivers and dependencies
179+
├── macos/{arm64,x86_64}/lib/ # macOS dylibs
180+
└── linux/{debian_ubuntu,rhel,suse,alpine}/{x86_64,arm64}/lib/ # Linux distributions
181+
```
182+
183+
### Configuration Files
184+
185+
- **`.clang-format`**: C++ formatting (Google style, 100 column limit)
186+
- **`.coveragerc`**: Coverage exclusions (main.py, setup.py, tests/)
187+
- **`requirements.txt`**: Development dependencies (pytest, pybind11, coverage)
188+
- **`setup.py`**: Package configuration with platform detection
189+
- **`pyproject.toml`**: Modern Python packaging configuration
190+
- **`.gitignore`**: Excludes build artifacts (*.so, *.pyd, build/, __pycache__)
191+
192+
## CI/CD Pipeline Details
193+
194+
### GitHub Workflows
195+
- **`devskim.yml`**: Security scanning (runs on PRs and main)
196+
- **`pr-format-check.yml`**: PR validation (title format, GitHub issue/ADO work item links)
197+
198+
### Azure DevOps Pipelines (`eng/pipelines/`)
199+
- **`pr-validation-pipeline.yml`**: Comprehensive testing across all platforms
200+
- **`build-whl-pipeline.yml`**: Wheel building for distribution
201+
- **Platform Coverage**: Windows (LocalDB), macOS (Docker SQL Server), Linux (Ubuntu, Debian, RHEL, Alpine) with both x86_64 and ARM64
202+
203+
### Build Matrix
204+
The CI system tests:
205+
- **Python versions**: 3.10, 3.11, 3.12, 3.13
206+
- **Windows**: x64, ARM64 architectures
207+
- **macOS**: Universal2 (ARM64 + x86_64)
208+
- **Linux**: Multiple distributions (Debian, Ubuntu, RHEL, Alpine) on x86_64 and ARM64
209+
210+
## Common Build Issues and Workarounds
211+
212+
### macOS-Specific Issues
213+
- **dylib path configuration**: Run `configure_dylibs.sh` after building to fix library paths
214+
- **codesigning**: Script automatically codesigns libraries for compatibility
215+
216+
### Linux Distribution Differences
217+
- **Debian/Ubuntu**: Use `apt-get install python3-dev cmake pybind11-dev`
218+
- **RHEL**: Requires enabling CodeReady Builder repository for development tools
219+
- **Alpine**: Uses musl libc, requires special handling in build scripts
220+
221+
### Windows Build Dependencies
222+
- **Visual Studio Build Tools**: Must include "Desktop development with C++" workload
223+
- **Architecture Detection**: Build scripts auto-detect target architecture from environment
224+
225+
### Known Limitations (from TODOs)
226+
- Linux RPATH configuration pending for driver .so files
227+
- Some Unicode support gaps in executemany operations
228+
- Platform-specific test dependencies in exception handling
229+
230+
## Architecture Detection and Loading
231+
232+
The `__init__.py` module implements sophisticated architecture detection:
233+
- **Windows**: Normalizes `win64/amd64/x64` → `x64`, `win32/x86` → `x86`, `arm64` → `arm64`
234+
- **macOS**: Runtime architecture detection, always loads from universal2 binary
235+
- **Linux**: Maps `x64/amd64` → `x86_64`, `arm64/aarch64` → `arm64`
236+
237+
## Contributing Guidelines
238+
239+
### PR Requirements
240+
- **Title Format**: Must start with `FEAT:`, `CHORE:`, `FIX:`, `DOC:`, `STYLE:`, `REFACTOR:`, or `RELEASE:`
241+
- **Issue Linking**: Must link to either GitHub issue or ADO work item
242+
- **Summary**: Minimum 10 characters of meaningful content under "### Summary"
243+
244+
### Development Workflow
245+
1. **Always build native extensions first** before running tests
246+
2. **Use virtual environments** for dependency isolation
247+
3. **Test on target platform** before submitting PRs
248+
4. **Check CI pipeline results** for cross-platform compatibility
249+
250+
## Trust These Instructions
251+
252+
These instructions are comprehensive and tested. Only search for additional information if:
253+
- Build commands fail with unexpected errors
254+
- New platform support is being added
255+
- Dependencies or requirements have changed
256+
257+
For any ambiguity, refer to the platform-specific README in `mssql_python/pybind/README.md` or the comprehensive CI pipeline configurations in `eng/pipelines/`.

0 commit comments

Comments
 (0)