DOC: Add llms.txt and copilot-instructions.md for LLM guidance by dlevy-msft-sql · Pull Request #406 · microsoft/mssql-python

dlevy-msft-sql · 2026-01-19T22:34:41Z

GitHub Issue: #247

Summary

This PR adds comprehensive documentation to help LLMs work effectively with the mssql-python driver, both for suggesting usage examples to end users and for contributing to the repository.

Changes

New Files:

llms.txt (243 lines) - Usage guide for LLMs suggesting code to users
- Quick start examples
- All connection string formats (Windows auth, SQL auth, Azure Entra ID variants)
- Context manager patterns (recommended usage)
- Parameterized queries (both ? and %(name)s styles)
- CRUD operations with transactions
- Error handling with exception hierarchy
- Comparison to pyodbc with migration example
.github/copilot-instructions.md (283 lines) - Instructions for AI coding agents contributing to the repo
- Repository overview and architecture
- Usage examples section (for context when helping users)
- Build system for all platforms (Windows, macOS, Linux)
- Testing procedures and coverage
- CI/CD pipeline details
- Common build issues and workarounds
- Contributing guidelines (PR title format, issue linking)

Related Issues

Supersedes #247 - This PR includes a corrected and expanded version of the copilot-instructions.md file with:

Fixed file references (logging.py instead of logging_config.py)
Fixed architecture detection reference (__init__.py instead of ddbc_bindings.py)
Added usage examples section
Added Black formatter version (26.1.0)
Complete file listing in architecture section
Added pyproject.toml reference

Testing

No code changes - documentation only. Verified:

File paths and names are accurate
Code examples are syntactically correct
Build commands match actual scripts
Connection string formats match driver API

- 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

github-actions · 2026-01-19T22:40:00Z

📊 Code Coverage Report

🔥 Diff Coverage 100%	🎯 Overall Coverage 76%	📈 Total Lines Covered: `5472` out of `7137` 📁 Project: `mssql-python`

Diff Coverage

Diff: main...HEAD, staged and unstaged changes

No lines with coverage information in this diff.

📋 Files Needing Attention

📉 Files with overall lowest coverage (click to expand)

mssql_python.pybind.logger_bridge.hpp: 58.8%
mssql_python.pybind.logger_bridge.cpp: 59.2%
mssql_python.row.py: 66.2%
mssql_python.pybind.ddbc_bindings.cpp: 69.3%
mssql_python.pybind.ddbc_bindings.h: 69.7%
mssql_python.pybind.connection.connection.cpp: 75.3%
mssql_python.ddbc_bindings.py: 79.6%
mssql_python.pybind.connection.connection_pool.cpp: 79.6%
mssql_python.connection.py: 84.1%
mssql_python.cursor.py: 84.7%

🔗 Quick Links

⚙️ Build Summary	📋 Coverage Details
View Azure DevOps Build	Browse Full Coverage Report

Copilot

Pull request overview

This PR adds comprehensive LLM guidance documentation to help AI coding assistants work effectively with the mssql-python driver. It includes two new documentation files: llms.txt for end-user code suggestions and .github/copilot-instructions.md for repository contributors.

Changes:

Added llms.txt (269 lines) with usage examples, connection patterns, query syntax, error handling, and migration guidance
Added .github/copilot-instructions.md (257 lines) with build instructions, architecture overview, CI/CD details, and contributing guidelines

Reviewed changes

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

File	Description
llms.txt	Provides comprehensive usage documentation for LLMs suggesting mssql-python code to end users, including connection strings, CRUD operations, and error handling
.github/copilot-instructions.md	Guides AI coding agents contributing to the repository with build system details, testing procedures, and architecture information

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

.github/copilot-instructions.md

llms.txt

- Fix architecture detection reference: ddbc_bindings.py not __init__.py - Fix stored procedure syntax: use positional params without named param mixing

Copilot

Pull request overview

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

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

.github/copilot-instructions.md

CI uses unpinned black, not 26.1.0. Also add --line-length=100 to match CI command.

bewithgaurav

@dlevy-msft-sql - this is a great addition, I used copilot to review this PR on some more context that I have been working with, below are the details I'd like to add in this PR for both the files

Review Feedback - Elevating the LLM Guidance

Here are suggestions to make these instructions even more effective:

1. Reference Existing Prompts (copilot-instructions.md)

The repo already has excellent .prompt.md files in .github/prompts/. Instead of duplicating build/test instructions, reference them:

Development Workflows

This repository includes detailed prompt files for common tasks. Use these with `#`:

Task	Prompt	When to Use
First-time setup	`#setup-dev-env`	New machine, fresh clone
Build C++ extension	`#build-ddbc`	After modifying `.cpp`/`.h` files
Run tests	`#run-tests`	Validating changes
Create PR	`#create-pr`	Ready to submit changes

Workflow order for new contributors:

#setup-dev-env → Set up venv and dependencies
#build-ddbc → Build native extension
Make your changes
#run-tests → Validate
#create-pr → Submit

2. Add Anti-Patterns Section (copilot-instructions.md)

Telling AI what NOT to do is as important as what to do:

Critical Anti-Patterns (DO NOT)

NEVER hardcode connection strings - always use DB_CONNECTION_STRING env var
NEVER use pyodbc imports - this driver doesn't require external ODBC
NEVER modify files in mssql_python/libs/ - these are pre-built binaries
NEVER skip conn.commit() after INSERT/UPDATE/DELETE operations

3. Add Exception Hierarchy (copilot-instructions.md)

Critical for error handling guidance:

Error (base)
├── DatabaseError
│   ├── InterfaceError      # Driver/interface issues
│   ├── OperationalError    # Connection/timeout issues  
│   ├── IntegrityError      # Constraint violations
│   ├── ProgrammingError    # SQL syntax errors
│   └── DataError           # Invalid data processing
└── Warning

4. Add AI Agent Behavioral Instructions (copilot-instructions.md)

When Modifying Code

Python Changes

Preserve existing error handling patterns from exceptions.py
Use context managers (with) for all connection/cursor operations
Update __all__ exports if adding public API
Add corresponding test in tests/test_*.py

C++ Changes

Follow RAII patterns for resource management
Use py::gil_scoped_release for blocking ODBC operations
Update mssql_python.pyi type stubs if changing Python API

5. Add Debugging Quick Reference (copilot-instructions.md)

Symptom	Likely Cause	Solution
`ImportError: ddbc_bindings`	Extension not built	Run `#build-ddbc`
`Connection timeout`	Missing env var	Set `DB_CONNECTION_STRING`
`dylib not found` (macOS)	Library paths	Run `configure_dylibs.sh`

6. Resolve Black Version Comment

The existing review comment about Black version pinning is unresolved - either remove the version pin or add explicit rationale.

Overall:
The distinction between llms.txt (user-facing API docs) and copilot-instructions.md (contributor-facing) is well thought out! The existing .prompt.md files are nice and well-used - consider cross-referencing them to avoid duplication. 👍

…n hierarchy

Copilot

Pull request overview

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

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

llms.txt

.github/copilot-instructions.md

llms.txt

.github/copilot-instructions.md

…ecurity notes

Copilot

Pull request overview

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

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

.github/copilot-instructions.md

…ents

Copilot

Pull request overview

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

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

Copilot AI review requested due to automatic review settings January 19, 2026 22:34

Copilot started reviewing on behalf of dlevy-msft-sql January 19, 2026 22:35 View session

Copilot AI reviewed Jan 19, 2026

View reviewed changes

.github/copilot-instructions.md Outdated Show resolved Hide resolved

llms.txt Outdated Show resolved Hide resolved

FIX: Address Copilot review feedback

0895b8d

- Fix architecture detection reference: ddbc_bindings.py not __init__.py - Fix stored procedure syntax: use positional params without named param mixing

dlevy-msft-sql requested a review from Copilot January 19, 2026 22:47

Copilot started reviewing on behalf of dlevy-msft-sql January 19, 2026 22:47 View session

Copilot AI reviewed Jan 19, 2026

View reviewed changes

.github/copilot-instructions.md Outdated Show resolved Hide resolved

dlevy-msft-sql added 2 commits January 19, 2026 16:53

FIX: Remove incorrect Black version pin

c8f3c60

CI uses unpinned black, not 26.1.0. Also add --line-length=100 to match CI command.

Merge branch 'main' into docs/llm-usage-guide

ef2f3c4

dlevy-msft-sql added the pr-size: small Minimal code update label Jan 22, 2026

Merge branch 'main' into docs/llm-usage-guide

024ccce

bewithgaurav requested changes Jan 29, 2026

View reviewed changes

This was referenced Jan 29, 2026

DOC: Add comprehensive BUILDGUIDE.md with cross-platform build instructions and VS Code setup #156

Closed

DOC: Add comprehensive .github/copilot-instructions.md for coding agent onboarding #247

Closed

dlevy-msft-sql added 2 commits January 29, 2026 18:03

Merge branch 'main' into docs/llm-usage-guide

098b028

FIX: Address review feedback - add workflows, anti-patterns, exceptio…

c57fb34

…n hierarchy

dlevy-msft-sql requested a review from Copilot January 30, 2026 00:12

Copilot started reviewing on behalf of dlevy-msft-sql January 30, 2026 00:12 View session

DOC: Add platform-specific dependencies and uv example to llms.txt

4e2515b

Copilot AI reviewed Jan 30, 2026

View reviewed changes

llms.txt Show resolved Hide resolved

.github/copilot-instructions.md Outdated Show resolved Hide resolved

llms.txt Show resolved Hide resolved

llms.txt Show resolved Hide resolved

llms.txt Show resolved Hide resolved

.github/copilot-instructions.md Show resolved Hide resolved

FIX: Address Copilot review - fix exception hierarchy, Linux archs, s…

a90e2fa

…ecurity notes

dlevy-msft-sql requested a review from Copilot January 30, 2026 01:14

Copilot started reviewing on behalf of dlevy-msft-sql January 30, 2026 01:14 View session

Copilot AI reviewed Jan 30, 2026

View reviewed changes

.github/copilot-instructions.md Show resolved Hide resolved

FIX: Add missing ddbc_bindings.py and mssql_python.pyi to Core Compon…

03444db

…ents

dlevy-msft-sql requested a review from Copilot January 30, 2026 01:29

Copilot started reviewing on behalf of dlevy-msft-sql January 30, 2026 01:50 View session

Copilot AI reviewed Jan 30, 2026

View reviewed changes

Merge branch 'main' into docs/llm-usage-guide

716cb7d

dlevy-msft-sql requested a review from bewithgaurav February 2, 2026 02:29

Merge branch 'main' into docs/llm-usage-guide

6ffc89f

Conversation

dlevy-msft-sql commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Related Issues

Testing

Uh oh!

github-actions bot commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Code Coverage Report

🔥 Diff Coverage

100%

🎯 Overall Coverage

76%

Diff Coverage

Diff: main...HEAD, staged and unstaged changes

📋 Files Needing Attention

🔗 Quick Links

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

bewithgaurav left a comment

Choose a reason for hiding this comment

Review Feedback - Elevating the LLM Guidance

1. Reference Existing Prompts (copilot-instructions.md)

Development Workflows

2. Add Anti-Patterns Section (copilot-instructions.md)

Critical Anti-Patterns (DO NOT)

3. Add Exception Hierarchy (copilot-instructions.md)

4. Add AI Agent Behavioral Instructions (copilot-instructions.md)

When Modifying Code

Python Changes

C++ Changes

5. Add Debugging Quick Reference (copilot-instructions.md)

6. Resolve Black Version Comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dlevy-msft-sql commented Jan 19, 2026 •

edited

Loading

github-actions bot commented Jan 19, 2026 •

edited

Loading