From 93580ac5b808967da343102146d48cdd2623ce41 Mon Sep 17 00:00:00 2001 From: Gaurav Sharma Date: Mon, 5 Jan 2026 19:15:28 +0530 Subject: [PATCH 01/20] feat: add VS Code Copilot prompts for dev workflow - setup-dev-env: One-time environment setup (venv, deps, prerequisites) - build-ddbc: Rebuild C++ pybind11 extensions - run-tests: Run pytest with various options - create-pr: Create well-structured pull requests with GitHub MCP Prompts use agent mode and cross-reference each other for seamless workflow. --- .github/prompts/build-ddbc.prompt.md | 313 +++++++++++++++ .github/prompts/create-pr.prompt.md | 493 ++++++++++++++++++++++++ .github/prompts/run-tests.prompt.md | 365 ++++++++++++++++++ .github/prompts/setup-dev-env.prompt.md | 486 +++++++++++++++++++++++ 4 files changed, 1657 insertions(+) create mode 100644 .github/prompts/build-ddbc.prompt.md create mode 100644 .github/prompts/create-pr.prompt.md create mode 100644 .github/prompts/run-tests.prompt.md create mode 100644 .github/prompts/setup-dev-env.prompt.md diff --git a/.github/prompts/build-ddbc.prompt.md b/.github/prompts/build-ddbc.prompt.md new file mode 100644 index 00000000..88f6451a --- /dev/null +++ b/.github/prompts/build-ddbc.prompt.md @@ -0,0 +1,313 @@ +--- +mode: 'agent' +--- +# Build DDBC Extensions Prompt for microsoft/mssql-python + +You are a development assistant helping rebuild the DDBC C++ pybind11 extensions for the mssql-python driver. + +## PREREQUISITES + +> ⚠️ **This prompt assumes your development environment is already set up.** +> If you haven't set up your environment yet, use `#setup-dev-env` first. + +**Quick sanity check:** +```bash +echo $VIRTUAL_ENV && python -c "import pybind11; print('✅ Ready to build')" +``` + +If this fails, run the setup prompt first. + +--- + +## TASK + +Help the developer rebuild the DDBC bindings after making C++ code changes. Follow this process sequentially. + +--- + +## STEP 0: Understand What You're Building + +### What Are DDBC Bindings? + +The `ddbc_bindings` module is a **C++ pybind11 extension** that provides: +- Low-level ODBC connectivity to SQL Server +- High-performance database operations +- Platform-specific optimizations + +### When to Rebuild + +- ✅ After modifying any `.cpp` or `.h` files in `mssql_python/pybind/` +- ✅ After changing `CMakeLists.txt` +- ✅ After upgrading Python version +- ✅ After pulling changes that include C++ modifications +- ❌ After Python-only changes (no rebuild needed) + +### Key Files + +``` +mssql_python/pybind/ +├── ddbc_bindings.cpp # Main bindings implementation +├── ddbc_bindings.h # Header file +├── logger_bridge.cpp # Python logging bridge +├── logger_bridge.hpp # Logger header +├── connection/ # Connection implementation +│ ├── connection.cpp +│ ├── connection.h +│ ├── connection_pool.cpp +│ └── connection_pool.h +├── CMakeLists.txt # CMake build configuration +├── build.sh # macOS/Linux build script +└── build.bat # Windows build script +``` + +--- + +## STEP 1: Build the Extension + +### 1.1 Navigate to Build Directory + +```bash +cd mssql_python/pybind +``` + +### 1.2 Run Build Script + +#### macOS / Linux + +```bash +# Standard build +./build.sh + +# Build with code coverage instrumentation (Linux only) +./build.sh codecov +``` + +#### Windows (in Developer Command Prompt) + +```cmd +build.bat +``` + +### 1.3 What the Build Does + +1. **Cleans** existing `build/` directory +2. **Detects** Python version and architecture +3. **Configures** CMake with correct paths +4. **Compiles** C++ code to platform-specific extension +5. **Copies** the built extension to `mssql_python/` directory +6. **Signs** the extension (macOS only - for SIP compliance) + +**Output files by platform:** +| Platform | Output File | +|----------|-------------| +| macOS | `ddbc_bindings.cp{version}-universal2.so` | +| Linux | `ddbc_bindings.cp{version}-{arch}.so` | +| Windows | `ddbc_bindings.cp{version}-{arch}.pyd` | + +--- + +## STEP 2: Verify the Build + +### 2.1 Check Output File Exists + +```bash +# macOS/Linux +ls -la ../ddbc_bindings.*.so + +# Windows +dir ..\ddbc_bindings.*.pyd +``` + +### 2.2 Verify Import Works + +```bash +# From repository root (important!) +cd ../.. +python -c "from mssql_python import connect; print('✅ Import successful')" +``` + +### 2.3 Verify Architecture (macOS Only) + +```bash +# Check if universal binary +lipo -info mssql_python/ddbc_bindings.*.so +# Expected: Architectures in the fat file: ... are: x86_64 arm64 +``` + +--- + +## STEP 3: Clean Build (If Needed) + +If you need a completely fresh build: + +```bash +# From repository root +rm -rf mssql_python/pybind/build/ +rm -f mssql_python/ddbc_bindings.*.so +rm -f mssql_python/ddbc_bindings.*.pyd + +# Rebuild +cd mssql_python/pybind +./build.sh # or build.bat on Windows +``` + +--- + +## Troubleshooting + +### ❌ "CMake configuration failed" + +**Cause:** CMake can't find Python or pybind11 paths + +**Fix:** +```bash +# Verify Python include directory exists +python -c "import sysconfig; print(sysconfig.get_path('include'))" +ls $(python -c "import sysconfig; print(sysconfig.get_path('include'))") + +# Verify pybind11 include directory exists +python -c "import pybind11; print(pybind11.get_include())" +ls $(python -c "import pybind11; print(pybind11.get_include())") +``` + +If pybind11 path doesn't exist, run: `pip install pybind11` + +### ❌ "pybind11 not found" during build + +**Cause:** pybind11 not installed in active venv + +**Fix:** +```bash +# Ensure venv is active +source myvenv/bin/activate # adjust path if needed + +# Install pybind11 +pip install pybind11 + +# Verify +python -c "import pybind11; print(pybind11.get_include())" +``` + +### ❌ "sql.h not found" (macOS) + +**Cause:** ODBC development headers not installed + +**Fix:** +```bash +# Install Microsoft ODBC Driver (provides headers) +brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release +ACCEPT_EULA=Y brew install msodbcsql18 + +# Or specify custom path +export ODBC_INCLUDE_DIR=/path/to/odbc/headers +./build.sh +``` + +### ❌ "undefined symbol" errors at runtime + +**Cause:** Built with different Python than you're running + +**Fix:** +```bash +# Check which Python was used to build (look at output filename) +ls mssql_python/ddbc_bindings.*.so +# e.g., ddbc_bindings.cp313-universal2.so means Python 3.13 + +# Check current Python +python --version + +# If mismatch, rebuild with correct Python +rm -rf mssql_python/pybind/build/ +cd mssql_python/pybind +./build.sh +``` + +### ❌ "cmake is not recognized" (Windows) + +**Cause:** Not using Developer Command Prompt + +**Fix:** +1. Close current terminal +2. Open **Start Menu** → search "Developer Command Prompt for VS 2022" +3. Navigate to project: `cd C:\path\to\mssql-python\mssql_python\pybind` +4. Run: `build.bat` + +### ❌ "codesign failed" (macOS) + +**Cause:** macOS SIP (System Integrity Protection) issues + +**Fix:** The build script handles this automatically. If issues persist: +```bash +codesign -s - -f mssql_python/ddbc_bindings.*.so +``` + +### ❌ Build succeeds but import fails + +**Cause:** Usually path issues or old cached files + +**Fix:** +```bash +# Clear Python cache +find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null + +# Clear any .pyc files +find . -name "*.pyc" -delete + +# Reinstall in dev mode +pip install -e . + +# Try import again +python -c "from mssql_python import connect; print('✅ OK')" +``` + +### ❌ "Permission denied" running build.sh + +**Fix:** +```bash +chmod +x mssql_python/pybind/build.sh +./build.sh +``` + +### ❌ Build takes too long / seems stuck + +**Cause:** Universal binary build on macOS compiles for both architectures + +**Info:** This is normal. macOS builds for both arm64 and x86_64. First build takes longer, subsequent builds use cache. + +**If truly stuck (>10 minutes):** +```bash +# Cancel with Ctrl+C, then clean and retry +rm -rf build/ +./build.sh +``` + +--- + +## Quick Reference + +### One-Liner Build Commands + +```bash +# macOS/Linux - Full rebuild from repo root +cd mssql_python/pybind && rm -rf build && ./build.sh && cd ../.. && python -c "from mssql_python import connect; print('✅ Build successful')" +``` + +### Build Output Naming Convention + +| Platform | Python | Architecture | Output File | +|----------|--------|--------------|-------------| +| macOS | 3.13 | Universal | `ddbc_bindings.cp313-universal2.so` | +| Linux | 3.12 | x86_64 | `ddbc_bindings.cp312-x86_64.so` | +| Linux | 3.11 | ARM64 | `ddbc_bindings.cp311-arm64.so` | +| Windows | 3.13 | x64 | `ddbc_bindings.cp313-amd64.pyd` | +| Windows | 3.12 | ARM64 | `ddbc_bindings.cp312-arm64.pyd` | + +--- + +## After Building + +Once the build succeeds: + +1. **Run tests** → Use `#run-tests` +2. **Test manually** with a connection to SQL Server +3. **Create a PR** with your C++ changes → Use `#create-pr` diff --git a/.github/prompts/create-pr.prompt.md b/.github/prompts/create-pr.prompt.md new file mode 100644 index 00000000..225f22ca --- /dev/null +++ b/.github/prompts/create-pr.prompt.md @@ -0,0 +1,493 @@ +--- +mode: 'agent' +--- +# Create Pull Request Prompt for microsoft/mssql-python + +You are a development assistant helping create a pull request for the mssql-python driver. + +## PREREQUISITES + +Before creating a PR, ensure: +1. ✅ All tests pass (use `#run-tests`) +2. ✅ Code changes are complete and working +3. ✅ If C++ changes, extension is rebuilt (use `#build-ddbc`) + +--- + +## TASK + +Help the developer create a well-structured pull request. Follow this process sequentially. + +**Use GitHub MCP tools** (`mcp_github_*`) for PR creation when available. + +--- + +## STEP 1: Verify Current Branch State + +### 1.1 Check Current Branch + +```bash +git branch --show-current +``` + +**If on `main`:** +> ⚠️ You're on the main branch. You need to create a feature branch first. +> Continue to Step 2. + +**If on a feature branch:** +> ✅ You're on a feature branch. Skip to Step 3. + +### 1.2 Check for Uncommitted Changes + +```bash +git status +``` + +**If there are uncommitted changes**, they need to be committed before creating a PR. + +--- + +## STEP 2: Create Feature Branch (If on main) + +### 2.1 Ensure main is Up-to-Date + +```bash +git checkout main +git pull origin main +``` + +### 2.2 Create and Switch to Feature Branch + +**Branch Naming Convention:** `//` or `/` + +**Team Member Prefixes:** +| Name | Branch Prefix | +|------|---------------| +| Gaurav | `bewithgaurav/` | +| Saumya | `saumya/` | +| Jahnvi | `jahnvi/` | +| Saurabh | `saurabh/` | +| Subrata | `subrata/` | +| Other contributors | `/` | + +| Type | Use For | Example | +|------|---------|---------| +| `feat` | New features | `bewithgaurav/feat/connection-timeout` | +| `fix` | Bug fixes | `saumya/fix/cursor-memory-leak` | +| `doc` | Documentation | `jahnvi/doc/api-examples` | +| `refactor` | Refactoring | `saurabh/refactor/simplify-parser` | +| `chore` | Maintenance | `subrata/chore/update-deps` | +| `style` | Code style | `jahnvi/style/format-connection` | +| (no type) | General work | `bewithgaurav/cursor-level-caching` | + +Ask the developer for their name and branch purpose, then: + +```bash +git checkout -b // +``` + +**Examples:** +```bash +git checkout -b bewithgaurav/feat/add-connection-timeout +git checkout -b saumya/fix/cursor-memory-leak +git checkout -b jahnvi/doc/update-readme +git checkout -b bewithgaurav/enhance_logging # without type is also fine +``` + +--- + +## STEP 3: Review Changes + +### 3.1 Check What's Changed + +```bash +# See all changed files +git status + +# See detailed diff +git diff + +# See diff for staged files +git diff --staged +``` + +### 3.2 Verify Changes are Complete + +Ask the developer: +> "Are all your changes ready to be committed? Do you need to make any additional modifications?" + +--- + +## STEP 4: Stage and Commit Changes + +### 4.1 Stage Changes + +> ⚠️ **Important:** Always exclude binary files (`.dylib`, `.so`, `.pyd`, `.dll`) unless explicitly instructed to include them. These are build artifacts. + +> ⚠️ **Avoid `git stash`** - If you stash changes, you MUST remember to `git stash pop` later. It's safer to stage only the specific files you need. + +```bash +# PREFERRED: Stage specific files only +git add + +# Check what's staged +git status + +# AVOID: git add . (stages everything including binaries) +``` + +**Files to typically EXCLUDE from commits:** +- `mssql_python/libs/**/*.dylib` - macOS libraries +- `mssql_python/libs/**/*.so` - Linux libraries +- `mssql_python/*.so` or `*.pyd` - Built extensions +- `*.dll` - Windows libraries +- Virtual environments (`myvenv/`, `testenv/`, etc.) + +**To unstage accidentally added binary files:** +```bash +git restore --staged mssql_python/libs/ +git restore --staged "*.dylib" "*.so" "*.pyd" +``` + +**If you must use git stash (not recommended):** +```bash +git stash # Temporarily saves changes +# ... do other work ... +git stash pop # MUST run this to restore your changes! +git stash list # Check if you have stashed changes +``` + +### 4.2 Create Commit Message + +```bash +git commit -m ": + +" +``` + +**Examples:** +```bash +git commit -m "feat: add connection timeout parameter + +- Added timeout_seconds parameter to connect() +- Default timeout is 30 seconds +- Raises TimeoutError if connection takes too long" +``` + +--- + +## STEP 5: Push Branch + +```bash +# Push branch to remote (first time) +git push -u origin + +# Subsequent pushes +git push +``` + +--- + +## STEP 6: Create Pull Request + +### 6.1 PR Title Format (REQUIRED) + +The PR title **MUST** start with one of these prefixes (enforced by CI): + +| Prefix | Use For | +|--------|---------| +| `FEAT:` | New features | +| `FIX:` | Bug fixes | +| `DOC:` | Documentation changes | +| `CHORE:` | Maintenance tasks | +| `STYLE:` | Code style/formatting | +| `REFACTOR:` | Code refactoring | +| `RELEASE:` | Release-related changes | + +**Examples:** +- `FEAT: Add connection timeout parameter` +- `FIX: Resolve cursor memory leak in fetchall()` +- `DOC: Update README with new examples` + +### 6.2 PR Description Format (REQUIRED) + +The PR description **MUST** include: +1. **A `### Summary` section** with at least 10 characters of content +2. **Either a GitHub issue link OR an ADO work item link** + +**GitHub issue formats:** +- `#123` (short form) +- `https://github.com/microsoft/mssql-python/issues/123` (full URL) + +**ADO Work Item format:** +- `https://sqlclientdrivers.visualstudio.com/.../_workitems/edit/` + +### 6.3 Create PR via GitHub MCP (Preferred) + +Use the `mcp_github_create_pull_request` tool: + +``` +Owner: microsoft +Repo: mssql-python +Title: : +Head: +Base: main +Body: +``` + +**Example PR Body Template:** +```markdown +### Summary + + + +### Changes + +- Change 1 +- Change 2 +- Change 3 + +### Testing + +- [ ] Unit tests pass +- [ ] Integration tests pass +- [ ] Manual testing completed + +### Related Issues + +Closes # + +Related: https://sqlclientdrivers.visualstudio.com/.../_workitems/edit/ +``` + +### 6.4 Alternative: Create PR via GitHub CLI + +If MCP is not available: + +```bash +gh pr create \ + --title "FEAT: Add connection timeout parameter" \ + --body "### Summary + +Added timeout_seconds parameter to connect() function for better control over connection timeouts. + +### Changes + +- Added timeout_seconds parameter with 30s default +- Raises TimeoutError on connection timeout +- Added unit tests for timeout behavior + +### Testing + +- [x] Unit tests pass +- [x] Integration tests pass + +### Related Issues + +Closes #123" \ + --base main +``` + +### 6.5 Alternative: Create PR via Web + +```bash +# Get the URL to create PR +echo "https://github.com/microsoft/mssql-python/compare/main...?expand=1" +``` + +--- + +## STEP 7: PR Checklist + +Before submitting, verify: + +```markdown +## PR Checklist + +- [ ] PR title starts with valid prefix (FEAT:, FIX:, DOC:, etc.) +- [ ] PR description has a ### Summary section with content +- [ ] PR links to a GitHub issue OR ADO work item +- [ ] Branch is based on latest `main` +- [ ] All tests pass locally +- [ ] Code follows project style guidelines +- [ ] No sensitive data (passwords, keys) in code +- [ ] No binary files (.dylib, .so, .pyd) unless explicitly needed +- [ ] Documentation updated if needed +``` + +--- + +## Troubleshooting + +### ❌ CI fails: "PR title must start with one of the allowed prefixes" + +**Cause:** PR title doesn't match required format + +**Valid prefixes:** `FEAT:`, `FIX:`, `DOC:`, `CHORE:`, `STYLE:`, `REFACTOR:`, `RELEASE:` + +**Fix:** Edit PR title in GitHub to start with a valid prefix + +### ❌ CI fails: "PR must contain either a valid GitHub issue link OR ADO Work Item link" + +**Cause:** Missing issue/work item reference + +**Fix:** Edit PR description to include: +- GitHub issue: `#123` or `https://github.com/microsoft/mssql-python/issues/123` +- OR ADO: `https://sqlclientdrivers.visualstudio.com/.../_workitems/edit/` + +### ❌ CI fails: "PR must contain a meaningful summary section" + +**Cause:** Missing or empty `### Summary` section + +**Fix:** Edit PR description to include `### Summary` with at least 10 characters of actual content (not just placeholders) + +### ❌ "Updates were rejected because the remote contains work..." + +**Cause:** Remote has commits you don't have locally + +**Fix:** +```bash +git pull origin main --rebase +git push +``` + +### ❌ "Permission denied" when pushing + +**Cause:** SSH key or token not configured + +**Fix:** +```bash +# Check remote URL +git remote -v + +# If using HTTPS, ensure you have a token +# If using SSH, ensure your key is added to GitHub +``` + +### ❌ Merge conflicts with main + +**Cause:** main has changed since you branched + +**Fix:** +```bash +# Update main +git checkout main +git pull origin main + +# Rebase your branch +git checkout +git rebase main + +# Resolve conflicts if any, then +git push --force-with-lease +``` + +### ❌ Accidentally committed to main + +**Fix:** +```bash +# Create a branch from current state +git branch + +# Reset main to match remote +git checkout main +git reset --hard origin/main + +# Switch to your branch +git checkout +``` + +### ❌ Need to update PR with more changes + +**Fix:** +```bash +# Make your changes +git add . +git commit -m "fix: address PR feedback" +git push + +# PR automatically updates +``` + +### ❌ PR has too many commits, want to squash + +**Fix:** +```bash +# Interactive rebase to squash commits +git rebase -i HEAD~ + +# Change 'pick' to 'squash' for commits to combine +# Save and edit commit message +git push --force-with-lease +``` + +--- + +## Quick Reference + +### Branch Naming Convention + +`//` or `/` + +**Team Member Prefixes:** +| Name | Branch Prefix | +|------|---------------| +| Gaurav | `bewithgaurav/` | +| Saumya | `saumya/` | +| Jahnvi | `jahnvi/` | +| Saurabh | `saurabh/` | +| Subrata | `subrata/` | +| Other contributors | `/` | + +| Type | Example | +|------|---------| +| `feat` | `bewithgaurav/feat/add-retry-logic` | +| `fix` | `saumya/fix/connection-leak` | +| `doc` | `jahnvi/doc/api-examples` | +| `refactor` | `saurabh/refactor/simplify-parser` | +| `chore` | `subrata/chore/update-deps` | +| (no type) | `bewithgaurav/cursor-level-caching` | + +### PR Title Prefixes (Required) + +| Prefix | Use For | +|--------|---------| +| `FEAT:` | New features | +| `FIX:` | Bug fixes | +| `DOC:` | Documentation | +| `CHORE:` | Maintenance | +| `STYLE:` | Formatting | +| `REFACTOR:` | Refactoring | +| `RELEASE:` | Releases | + +### Common Git Commands for PRs + +```bash +# Check current state +git status +git branch --show-current +git log --oneline -5 + +# Create and switch branch +git checkout -b bewithgaurav/feat/my-feature + +# Stage and commit +git add . +git commit -m "feat: description" + +# Push +git push -u origin + +# View PR status (gh CLI) +gh pr status +gh pr view +``` + +--- + +## After PR is Created + +1. **Monitor CI** - Watch for PR format check and test failures +2. **Respond to reviews** - Address reviewer comments +3. **Keep branch updated** - Rebase if main changes significantly +4. **Merge** - Once approved, merge via GitHub (usually squash merge) diff --git a/.github/prompts/run-tests.prompt.md b/.github/prompts/run-tests.prompt.md new file mode 100644 index 00000000..d5b2f749 --- /dev/null +++ b/.github/prompts/run-tests.prompt.md @@ -0,0 +1,365 @@ +--- +mode: 'agent' +--- +# Run Tests Prompt for microsoft/mssql-python + +You are a development assistant helping run pytest for the mssql-python driver. + +## PREREQUISITES + +> ⚠️ **This prompt assumes your development environment is already set up.** +> If you haven't set up your environment yet, use `#setup-dev-env` first. + +**Quick sanity check:** +```bash +echo $VIRTUAL_ENV && python -c "import pytest; print('✅ Ready to test')" +``` + +If this fails, run the setup prompt first. + +--- + +## TASK + +Help the developer run tests to validate their changes. Follow this process based on what they need. + +--- + +## STEP 1: Choose What to Test + +### Test Categories + +| Category | Description | When to Use | +|----------|-------------|-------------| +| **All tests** | Full test suite (excluding stress) | Before creating PR | +| **Specific file** | Single test file | Testing one area | +| **Specific test** | Single test function | Debugging a failure | +| **Stress tests** | Long-running, resource-intensive | Performance validation | +| **With coverage** | Tests + coverage report | Checking coverage | + +### Ask the Developer + +> "What would you like to test?" +> 1. **All tests** - Run full suite (recommended before PR) +> 2. **Specific tests** - Tell me which file(s) or test name(s) +> 3. **Just unit tests** - Skip integration tests requiring DB +> 4. **With coverage** - Generate coverage report + +--- + +## STEP 2: Verify Connection String (For Integration Tests) + +Integration tests require a database connection. Check if it's set: + +```bash +# Check if DB_CONNECTION_STRING is set +if [ -n "$DB_CONNECTION_STRING" ]; then echo "✅ Connection string is set"; else echo "⚠️ Not set - integration tests will fail"; fi +``` + +**If not set and you need integration tests:** +```bash +export DB_CONNECTION_STRING="Driver={ODBC Driver 18 for SQL Server};Server=your_server;Database=your_db;UID=your_user;PWD=your_password;TrustServerCertificate=yes" +``` + +> 💡 Unit tests (test_000, test_001, test_002, test_007) don't require a database. + +--- + +## STEP 3: Run Tests + +### Option A: Run All Tests (Default - Excludes Stress Tests) + +```bash +# From repository root +python -m pytest -v + +# This automatically applies: -m "not stress" (from pytest.ini) +``` + +### Option B: Run All Tests Including Stress Tests + +```bash +python -m pytest -v -m "" +``` + +### Option C: Run Only Stress Tests + +```bash +python -m pytest -v -m stress +``` + +### Option D: Run Specific Test File + +```bash +# Single file +python -m pytest tests/test_003_connection.py -v + +# Multiple files +python -m pytest tests/test_003_connection.py tests/test_004_cursor.py -v +``` + +### Option E: Run Specific Test Function + +```bash +# Specific test +python -m pytest tests/test_003_connection.py::test_connection_basic -v + +# Pattern matching +python -m pytest -k "connection" -v +python -m pytest -k "connection and not close" -v +``` + +### Option F: Run with Coverage + +```bash +# Basic coverage +python -m pytest --cov=mssql_python -v + +# Coverage with HTML report +python -m pytest --cov=mssql_python --cov-report=html -v + +# Coverage with specific report location +python -m pytest --cov=mssql_python --cov-report=html:coverage_report -v +``` + +### Option G: Run Failed Tests Only (Re-run) + +```bash +# Re-run only tests that failed in the last run +python -m pytest --lf -v + +# Re-run failed tests first, then the rest +python -m pytest --ff -v +``` + +### Option H: Run Unit Tests Only (No Database Required) + +```bash +# Tests that don't need a database connection +python -m pytest tests/test_000_dependencies.py tests/test_001_globals.py tests/test_002_types.py tests/test_007_logging.py -v +``` + +--- + +## STEP 4: Understanding Test Output + +### Test Result Indicators + +| Symbol | Meaning | Action | +|--------|---------|--------| +| `.` or `PASSED` | Test passed | ✅ Good | +| `F` or `FAILED` | Test failed | ❌ Fix needed | +| `E` or `ERROR` | Test error (setup/teardown) | ❌ Check fixtures | +| `s` or `SKIPPED` | Test skipped | ℹ️ Usually OK | +| `x` or `XFAIL` | Expected failure | ℹ️ Known issue | +| `X` or `XPASS` | Unexpected pass | ⚠️ Review | + +### Example Output + +``` +tests/test_003_connection.py::test_connection_basic PASSED [ 10%] +tests/test_003_connection.py::test_connection_close PASSED [ 20%] +tests/test_004_cursor.py::test_cursor_execute FAILED [ 30%] + +====================== FAILURES ====================== +________________ test_cursor_execute _________________ + + def test_cursor_execute(cursor): +> cursor.execute("SELECT 1") +E mssql_python.exceptions.DatabaseError: Connection failed + +tests/test_004_cursor.py:25: DatabaseError +====================================================== +``` + +--- + +## STEP 5: Test File Reference + +### Test Files and What They Cover + +| File | Purpose | Requires DB? | +|------|---------|--------------| +| `test_000_dependencies.py` | Dependency checks | No | +| `test_001_globals.py` | Global state | No | +| `test_002_types.py` | Type conversions | No | +| `test_003_connection.py` | Connection lifecycle | **Yes** | +| `test_004_cursor.py` | Cursor operations | **Yes** | +| `test_005_connection_cursor_lifecycle.py` | Lifecycle management | **Yes** | +| `test_006_exceptions.py` | Error handling | Mixed | +| `test_007_logging.py` | Logging functionality | No | +| `test_008_auth.py` | Authentication | **Yes** | + +--- + +## Troubleshooting + +### ❌ "ModuleNotFoundError: No module named 'mssql_python'" + +**Cause:** Package not installed in development mode + +**Fix:** +```bash +pip install -e . +``` + +### ❌ "ModuleNotFoundError: No module named 'pytest'" + +**Cause:** pytest not installed or venv not active + +**Fix:** +```bash +# Check venv is active +echo $VIRTUAL_ENV + +# If empty, activate it (run `#setup-dev-env`) +# If active, install pytest +pip install pytest pytest-cov +``` + +### ❌ "Connection failed" or "Login failed" + +**Cause:** Invalid or missing `DB_CONNECTION_STRING` + +**Fix:** +```bash +# Check the environment variable is set +echo $DB_CONNECTION_STRING + +# Set it with correct values +export DB_CONNECTION_STRING="Driver={ODBC Driver 18 for SQL Server};Server=localhost;Database=testdb;UID=sa;PWD=YourPassword;TrustServerCertificate=yes" +``` + +### ❌ "Timeout error" + +**Cause:** Database server not reachable + +**Fix:** +- Check server is running +- Verify network connectivity +- Check firewall rules +- Increase timeout: add `Connection Timeout=60` to connection string + +### ❌ Tests hang indefinitely + +**Cause:** Connection pool issues, deadlocks, or waiting for unavailable DB + +**Fix:** +```bash +# Run with timeout +pip install pytest-timeout +python -m pytest --timeout=60 -v + +# Run single test in isolation +python -m pytest tests/test_specific.py::test_name -v -s + +# Skip integration tests if no DB available +python -m pytest tests/test_000_dependencies.py tests/test_001_globals.py tests/test_002_types.py tests/test_007_logging.py -v +``` + +### ❌ "ddbc_bindings" import error + +**Cause:** C++ extension not built or Python version mismatch + +**Fix:** +Use `#build-ddbc` to rebuild the extension: +```bash +cd mssql_python/pybind && ./build.sh && cd ../.. +python -c "from mssql_python import connect; print('OK')" +``` + +### ❌ Tests pass locally but fail in CI + +**Cause:** Environment differences (connection string, Python version, OS) + +**Fix:** +- Check CI logs for specific error +- Ensure `DB_CONNECTION_STRING` is set in CI secrets +- Verify Python version matches CI + +### ❌ Coverage report shows 0% + +**Cause:** Package not installed or wrong source path + +**Fix:** +```bash +# Reinstall in dev mode +pip install -e . + +# Run with correct package path +python -m pytest --cov=mssql_python --cov-report=term-missing -v +``` + +### ❌ "collected 0 items" + +**Cause:** pytest can't find tests (wrong directory or pattern) + +**Fix:** +```bash +# Ensure you're in repository root +pwd # Should be /path/to/mssql-python + +# Check tests directory exists +ls tests/ + +# Run with explicit path +python -m pytest tests/ -v +``` + +--- + +## Quick Reference + +### Common Commands + +```bash +# Run all tests (default, excludes stress) +python -m pytest -v + +# Run specific file +python -m pytest tests/test_003_connection.py -v + +# Run with keyword filter +python -m pytest -k "connection" -v + +# Run with coverage +python -m pytest --cov=mssql_python -v + +# Run failed tests only +python -m pytest --lf -v + +# Run with output capture disabled (see print statements) +python -m pytest -v -s + +# Run with max 3 failures then stop +python -m pytest -v --maxfail=3 + +# Run with debugging on failure +python -m pytest -v --pdb +``` + +### pytest.ini Configuration + +The project uses these default settings in `pytest.ini`: + +```ini +[pytest] +markers = + stress: marks tests as stress tests (long-running, resource-intensive) + +# Default: Skips stress tests +addopts = -m "not stress" +``` + +--- + +## After Running Tests + +Based on test results: + +1. **All passed** → Ready to create/update PR → Use `#create-pr` +2. **Some failed** → Review failures, fix issues, re-run +3. **Coverage decreased** → Add tests for new code paths +4. **Need to debug** → Use `-s` flag to see print output, or `--pdb` to drop into debugger + +> 💡 **Tip:** If you made C++ changes, ensure you've rebuilt using `#build-ddbc` first! diff --git a/.github/prompts/setup-dev-env.prompt.md b/.github/prompts/setup-dev-env.prompt.md new file mode 100644 index 00000000..f279ea6f --- /dev/null +++ b/.github/prompts/setup-dev-env.prompt.md @@ -0,0 +1,486 @@ +--- +mode: 'agent' +--- +# Setup Development Environment Prompt for microsoft/mssql-python + +You are a development assistant helping set up the development environment for the mssql-python driver. + +## TASK + +Help the developer set up their local environment for development. This is typically run **once** when: +- Cloning the repository for the first time +- Setting up a new machine +- After a major dependency change +- Troubleshooting environment issues + +--- + +## STEP 1: Verify Python Version + +### 1.1 Check Python Installation + +```bash +python --version +# or +python3 --version +``` + +**Supported versions:** Python 3.10, 3.11, 3.12, 3.13 + +| Version | Status | +|---------|--------| +| 3.10+ | ✅ Supported | +| 3.9 and below | ❌ Not supported | + +### 1.2 Check Python Location + +```bash +which python +# or on Windows +where python +``` + +> ⚠️ Make note of this path - you'll need to ensure your venv uses this Python. + +--- + +## STEP 2: Virtual Environment Setup + +### 2.1 Check for Existing Virtual Environment + +```bash +# Check if a venv is already active +echo $VIRTUAL_ENV +``` + +**If output shows a path** → venv is active, skip to Step 2.4 to verify it + +**If output is empty** → No venv active, continue to Step 2.2 + +### 2.2 Create Virtual Environment (if needed) + +```bash +# From repository root +python -m venv myvenv + +# Or with a specific Python version +python3.13 -m venv myvenv +``` + +### 2.3 Activate Virtual Environment + +```bash +# macOS/Linux +source myvenv/bin/activate + +# Windows (Command Prompt) +myvenv\Scripts\activate.bat + +# Windows (PowerShell) +myvenv\Scripts\Activate.ps1 +``` + +### 2.4 Verify Virtual Environment + +```bash +# Check venv is active +echo $VIRTUAL_ENV +# Expected: /path/to/mssql-python/myvenv + +# Verify Python is from venv +which python +# Expected: /path/to/mssql-python/myvenv/bin/python + +# Verify Python version in venv +python --version +# Expected: Python 3.10+ +``` + +--- + +## STEP 3: Install Python Dependencies + +### 3.1 Upgrade pip (Recommended) + +```bash +pip install --upgrade pip +``` + +### 3.2 Install requirements.txt + +```bash +pip install -r requirements.txt +``` + +### 3.3 Install Development Dependencies + +```bash +# Build dependencies +pip install pybind11 + +# Test dependencies +pip install pytest pytest-cov + +# Linting/formatting (optional) +pip install black flake8 autopep8 +``` + +### 3.4 Install Package in Development Mode + +```bash +pip install -e . +``` + +### 3.5 Verify Python Dependencies + +```bash +# Check critical packages +python -c "import pybind11; print('✅ pybind11:', pybind11.get_include())" +python -c "import pytest; print('✅ pytest:', pytest.__version__)" +python -c "import mssql_python; print('✅ mssql_python installed')" +``` + +--- + +## STEP 4: Platform-Specific Prerequisites + +### 4.0 Detect Platform + +```bash +uname -s +# Darwin → macOS +# Linux → Linux +# (Windows users: skip this, you know who you are) +``` + +--- + +### 4.1 macOS Prerequisites + +#### Check CMake + +```bash +cmake --version +# Expected: cmake version 3.15+ +``` + +**If missing:** +```bash +brew install cmake +``` + +#### Check ODBC Headers + +```bash +ls /opt/homebrew/include/sql.h 2>/dev/null || ls /usr/local/include/sql.h 2>/dev/null +``` + +**If missing:** +```bash +# Install Microsoft ODBC Driver (provides headers for development) +brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release +ACCEPT_EULA=Y brew install msodbcsql18 +``` + +#### Verify macOS Setup + +```bash +echo "=== macOS Development Environment ===" && \ +cmake --version | head -1 && \ +python -c "import pybind11; print('pybind11:', pybind11.get_include())" && \ +ls /opt/homebrew/include/sql.h 2>/dev/null && echo "✅ ODBC headers found" || echo "❌ ODBC headers missing" +``` + +--- + +### 4.2 Linux Prerequisites + +#### Check CMake + +```bash +cmake --version +# Expected: cmake version 3.15+ +``` + +#### Check Compiler + +```bash +gcc --version || clang --version +``` + +**If missing (Debian/Ubuntu):** +```bash +sudo apt-get update +sudo apt-get install -y cmake build-essential python3-dev +``` + +**If missing (RHEL/CentOS/Fedora):** +```bash +sudo dnf install -y cmake gcc-c++ python3-devel +``` + +**If missing (SUSE):** +```bash +sudo zypper install -y cmake gcc-c++ python3-devel +``` + +#### Verify Linux Setup + +```bash +echo "=== Linux Development Environment ===" && \ +cmake --version | head -1 && \ +gcc --version | head -1 && \ +python -c "import pybind11; print('pybind11:', pybind11.get_include())" +``` + +--- + +### 4.3 Windows Prerequisites + +#### Visual Studio Build Tools 2022 + +1. Download from: https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022 +2. Run installer +3. Select **"Desktop development with C++"** workload +4. This includes CMake automatically + +#### Verify Windows Setup + +Open **Developer Command Prompt for VS 2022** and run: + +```cmd +cmake --version +cl +python -c "import pybind11; print('pybind11:', pybind11.get_include())" +``` + +> ⚠️ **Important:** Always use **Developer Command Prompt for VS 2022** for building, not regular cmd or PowerShell. + +--- + +## STEP 5: Configure Environment Variables + +### 5.1 Database Connection String (For Integration Tests) + +```bash +# Set connection string for tests +export DB_CONNECTION_STRING="Driver={ODBC Driver 18 for SQL Server};Server=your_server;Database=your_db;UID=your_user;PWD=your_password;TrustServerCertificate=yes" + +# Verify it's set +echo $DB_CONNECTION_STRING +``` + +**Windows:** +```cmd +set DB_CONNECTION_STRING=Driver={ODBC Driver 18 for SQL Server};Server=your_server;Database=your_db;UID=your_user;PWD=your_password;TrustServerCertificate=yes +``` + +> 💡 **Tip:** Add this to your shell profile (`.bashrc`, `.zshrc`) or venv's `activate` script to persist it. + +### 5.2 Optional: Add to venv activate script + +```bash +# Append to venv activate script so it's set automatically +echo 'export DB_CONNECTION_STRING="your_connection_string"' >> myvenv/bin/activate +``` + +--- + +## STEP 6: Final Verification + +Run this comprehensive check: + +```bash +echo "========================================" && \ +echo "Development Environment Verification" && \ +echo "========================================" && \ +echo "" && \ +echo "1. Virtual Environment:" && \ +if [ -n "$VIRTUAL_ENV" ]; then echo " ✅ Active: $VIRTUAL_ENV"; else echo " ❌ Not active"; fi && \ +echo "" && \ +echo "2. Python:" && \ +echo " $(python --version)" && \ +echo " Path: $(which python)" && \ +echo "" && \ +echo "3. Key Packages:" && \ +python -c "import pybind11; print(' ✅ pybind11:', pybind11.__version__)" 2>/dev/null || echo " ❌ pybind11 not installed" && \ +python -c "import pytest; print(' ✅ pytest:', pytest.__version__)" 2>/dev/null || echo " ❌ pytest not installed" && \ +python -c "import mssql_python; print(' ✅ mssql_python installed')" 2>/dev/null || echo " ❌ mssql_python not installed" && \ +echo "" && \ +echo "4. Build Tools:" && \ +cmake --version 2>/dev/null | head -1 | sed 's/^/ ✅ /' || echo " ❌ cmake not found" && \ +echo "" && \ +echo "5. Connection String:" && \ +if [ -n "$DB_CONNECTION_STRING" ]; then echo " ✅ Set (hidden for security)"; else echo " ⚠️ Not set (integration tests will fail)"; fi && \ +echo "" && \ +echo "========================================" +``` + +--- + +## Troubleshooting + +### ❌ "Python version not supported" + +**Cause:** Python < 3.10 + +**Fix:** +```bash +# Install Python 3.13 (macOS) +brew install python@3.13 + +# Create venv with specific version +python3.13 -m venv myvenv +source myvenv/bin/activate +``` + +### ❌ "No module named venv" + +**Cause:** venv module not installed (some Linux distros) + +**Fix:** +```bash +# Debian/Ubuntu +sudo apt-get install python3-venv + +# Then create venv +python3 -m venv myvenv +``` + +### ❌ "pip install fails with permission error" + +**Cause:** Trying to install globally without sudo, or venv not active + +**Fix:** +```bash +# Verify venv is active +echo $VIRTUAL_ENV + +# If empty, activate it +source myvenv/bin/activate + +# Then retry pip install +pip install -r requirements.txt +``` + +### ❌ "pybind11 installed but not found during build" + +**Cause:** pybind11 installed in different Python than build uses + +**Fix:** +```bash +# Check which Python has pybind11 +python -c "import pybind11; print(pybind11.get_include())" + +# Ensure same Python is used for build +which python + +# Reinstall in correct venv if needed +pip install pybind11 +``` + +### ❌ "cmake not found" (macOS) + +**Fix:** +```bash +brew install cmake + +# Or if Homebrew not in PATH +export PATH="/opt/homebrew/bin:$PATH" +``` + +### ❌ "cmake not found" (Windows) + +**Cause:** Not using Developer Command Prompt + +**Fix:** +1. Close current terminal +2. Open **Developer Command Prompt for VS 2022** from Start Menu +3. Navigate to project and retry + +### ❌ "gcc/g++ not found" (Linux) + +**Fix:** +```bash +# Debian/Ubuntu +sudo apt-get install build-essential + +# RHEL/CentOS/Fedora +sudo dnf groupinstall "Development Tools" +``` + +### ❌ "ODBC headers not found" (macOS) + +**Cause:** Microsoft ODBC Driver not installed + +**Fix:** +```bash +brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release +ACCEPT_EULA=Y brew install msodbcsql18 +``` + +### ❌ "requirements.txt installation fails" + +**Cause:** Network issues, outdated pip, or conflicting packages + +**Fix:** +```bash +# Upgrade pip first +pip install --upgrade pip + +# Try with verbose output +pip install -r requirements.txt -v + +# If specific package fails, install it separately +pip install +``` + +### ❌ PowerShell: "Activate.ps1 cannot be loaded because running scripts is disabled" + +**Cause:** PowerShell execution policy + +**Fix:** +```powershell +# Run PowerShell as Administrator +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser + +# Then activate +.\myvenv\Scripts\Activate.ps1 +``` + +--- + +## Quick Reference + +### One-Liner Fresh Setup (macOS/Linux) + +```bash +# Complete setup from scratch +python3 -m venv myvenv && \ +source myvenv/bin/activate && \ +pip install --upgrade pip && \ +pip install -r requirements.txt && \ +pip install pybind11 pytest pytest-cov && \ +pip install -e . && \ +echo "✅ Setup complete!" +``` + +### Minimum Required Packages + +| Package | Purpose | Required For | +|---------|---------|--------------| +| `pybind11` | C++ bindings | Building | +| `pytest` | Testing | Running tests | +| `pytest-cov` | Coverage | Coverage reports | +| `azure-identity` | Azure auth | Runtime (in requirements.txt) | + +--- + +## After Setup + +Once setup is complete, you can: + +1. **Build DDBC extensions** → Use `#build-ddbc` +2. **Run tests** → Use `#run-tests` + +> 💡 You typically only need to run this setup prompt **once** per machine or after major changes. From 19b83d840474248cfe08ecef443f83ce011a52d3 Mon Sep 17 00:00:00 2001 From: Gaurav Sharma Date: Mon, 5 Jan 2026 19:39:00 +0530 Subject: [PATCH 02/20] fix: update create-pr prompt with correct PR template format --- .github/prompts/create-pr.prompt.md | 142 ++++++++++++++++++++++------ 1 file changed, 112 insertions(+), 30 deletions(-) diff --git a/.github/prompts/create-pr.prompt.md b/.github/prompts/create-pr.prompt.md index 225f22ca..42ffa0ce 100644 --- a/.github/prompts/create-pr.prompt.md +++ b/.github/prompts/create-pr.prompt.md @@ -190,6 +190,13 @@ git push ## STEP 6: Create Pull Request +> ⚠️ **MANDATORY:** Before creating a PR, you MUST confirm **3 things** with the developer: +> 1. **PR Title** - Suggest options, get approval +> 2. **Work Item/Issue Link** - Search and suggest, get explicit confirmation (NEVER auto-add) +> 3. **PR Description** - Show full description, get approval + +--- + ### 6.1 PR Title Format (REQUIRED) The PR title **MUST** start with one of these prefixes (enforced by CI): @@ -204,23 +211,104 @@ The PR title **MUST** start with one of these prefixes (enforced by CI): | `REFACTOR:` | Code refactoring | | `RELEASE:` | Release-related changes | -**Examples:** -- `FEAT: Add connection timeout parameter` -- `FIX: Resolve cursor memory leak in fetchall()` -- `DOC: Update README with new examples` +> ⚠️ **CONFIRM #1 - PR Title:** Suggest 3-5 title options to the developer and ask them to pick or modify one. + +**Example:** +``` +Here are some title options for your PR: + +1. FEAT: Add connection timeout parameter +2. FEAT: Introduce configurable connection timeout +3. FEAT: Add timeout support for database connections + +Which one do you prefer, or would you like to modify one? +``` + +--- + +### 6.2 Work Item / Issue Link (REQUIRED) + +> ⚠️ **CONFIRM #2 - Work Item/Issue:** You MUST explicitly ask the developer which issue or work item this PR is linked to. +> +> **NEVER auto-add an issue number.** Even if you find a similar issue, ask the user to confirm. -### 6.2 PR Description Format (REQUIRED) +**Process:** +1. Search GitHub issues for potentially related issues +2. If found similar ones, list them as **suggestions only** +3. Ask: "Which issue or ADO work item should this PR be linked to?" +4. User can provide: GitHub issue, ADO work item, both, or none (if creating new issue) +5. **Ask if they want "Closes" prefix** (only for GitHub issues) - default is NO -The PR description **MUST** include: -1. **A `### Summary` section** with at least 10 characters of content -2. **Either a GitHub issue link OR an ADO work item link** +**Example prompt to user:** +``` +Which work item or issue should this PR be linked to? + +I found these potentially related GitHub issues: +- #123: Add developer documentation +- #145: Improve onboarding experience + +Options: +- Enter a GitHub issue number (e.g., 123) +- Enter an ADO work item ID (e.g., 41340) +- Enter both +- Say "none" if you'll create an issue separately + +For GitHub issues: Should this PR close the issue? (default: no) +``` + +**Format in PR description (simple hashtag format):** +- ADO Work Item: `#41340` (ADO plugin auto-links) +- GitHub Issue: `#123` (GitHub auto-links) +- GitHub Issue with close: `Closes #123` (only if user confirms) + +> 💡 **Note:** No need for full URLs. Just use `#` - plugins handle the linking automatically. -**GitHub issue formats:** -- `#123` (short form) -- `https://github.com/microsoft/mssql-python/issues/123` (full URL) +--- + +### 6.3 PR Description (REQUIRED) + +> ⚠️ **CONFIRM #3 - PR Description:** Show the full PR description to the developer and get approval before creating the PR. + +**Use EXACTLY this format (from `.github/PULL_REQUEST_TEMPLATE.MD`):** + +```markdown +### Work Item / Issue Reference -**ADO Work Item format:** -- `https://sqlclientdrivers.visualstudio.com/.../_workitems/edit/` + +> AB# + + +> GitHub Issue: # + +------------------------------------------------------------------- +### Summary + + +``` + +> 💡 **Notes:** +> - For team members: Use `AB#` format for ADO work items +> - For external contributors: Use `GitHub Issue: #` format +> - Only one reference is required (either ADO or GitHub) +> - Keep the exact format including the dashed line separator + +**Example prompt to user:** +``` +Here's the PR description I'll use: + +--- +### Work Item / Issue Reference + +> AB#41340 + +------------------------------------------------------------------- +### Summary + +Added VS Code Copilot prompts for developer workflow... +--- + +Does this look good? Should I modify anything before creating the PR? +``` ### 6.3 Create PR via GitHub MCP (Preferred) @@ -236,30 +324,24 @@ Body: ``` **Example PR Body Template:** -```markdown -### Summary - - - -### Changes -- Change 1 -- Change 2 -- Change 3 +```markdown +### Work Item / Issue Reference -### Testing + +> AB# -- [ ] Unit tests pass -- [ ] Integration tests pass -- [ ] Manual testing completed + +> GitHub Issue: # -### Related Issues +------------------------------------------------------------------- +### Summary -Closes # - -Related: https://sqlclientdrivers.visualstudio.com/.../_workitems/edit/ + ``` +> 💡 Use EXACTLY this format from `.github/PULL_REQUEST_TEMPLATE.MD`. Use `AB#ID` for ADO, `GitHub Issue: #ID` for GitHub issues. + ### 6.4 Alternative: Create PR via GitHub CLI If MCP is not available: From 5f048ccfa891acf567c62d38bd167901626b3b51 Mon Sep 17 00:00:00 2001 From: Gaurav Sharma Date: Mon, 5 Jan 2026 19:53:21 +0530 Subject: [PATCH 03/20] fix: address Copilot review feedback on prompts - Add security warnings for credentials and TrustServerCertificate=yes - Reference pyproject.toml for Python version requirements - Remove duplicate team member table, add maintenance note - Fix git add/stash guidance inconsistencies - Clarify that TrustServerCertificate is for local dev only --- .github/prompts/create-pr.prompt.md | 24 ++++++++---------------- .github/prompts/run-tests.prompt.md | 9 +++++++-- .github/prompts/setup-dev-env.prompt.md | 18 ++++++++++++------ 3 files changed, 27 insertions(+), 24 deletions(-) diff --git a/.github/prompts/create-pr.prompt.md b/.github/prompts/create-pr.prompt.md index 42ffa0ce..ef797e73 100644 --- a/.github/prompts/create-pr.prompt.md +++ b/.github/prompts/create-pr.prompt.md @@ -124,7 +124,7 @@ Ask the developer: > ⚠️ **Important:** Always exclude binary files (`.dylib`, `.so`, `.pyd`, `.dll`) unless explicitly instructed to include them. These are build artifacts. -> ⚠️ **Avoid `git stash`** - If you stash changes, you MUST remember to `git stash pop` later. It's safer to stage only the specific files you need. +> ⚠️ **Prefer staging over stashing** - It's safer to stage specific files than to use `git stash`, which can lead to forgotten changes. ```bash # PREFERRED: Stage specific files only @@ -132,10 +132,10 @@ git add # Check what's staged git status - -# AVOID: git add . (stages everything including binaries) ``` +> ⚠️ **AVOID:** `git add .` stages everything including binary files. Always stage specific files. + **Files to typically EXCLUDE from commits:** - `mssql_python/libs/**/*.dylib` - macOS libraries - `mssql_python/libs/**/*.so` - Linux libraries @@ -149,12 +149,12 @@ git restore --staged mssql_python/libs/ git restore --staged "*.dylib" "*.so" "*.pyd" ``` -**If you must use git stash (not recommended):** +**If you use `git stash`, do so carefully and restore your changes:** ```bash -git stash # Temporarily saves changes +git stash # Temporarily saves changes (use only if you understand stashing) # ... do other work ... -git stash pop # MUST run this to restore your changes! -git stash list # Check if you have stashed changes +git stash pop # MUST run this to restore your changes (otherwise they stay hidden)! +git stash list # Check if you still have stashed changes to restore ``` ### 4.2 Create Commit Message @@ -511,15 +511,7 @@ git push --force-with-lease `//` or `/` -**Team Member Prefixes:** -| Name | Branch Prefix | -|------|---------------| -| Gaurav | `bewithgaurav/` | -| Saumya | `saumya/` | -| Jahnvi | `jahnvi/` | -| Saurabh | `saurabh/` | -| Subrata | `subrata/` | -| Other contributors | `/` | +> See "Team Member Prefixes" table in Step 2.2 above for the current list of prefixes. | Type | Example | |------|---------| diff --git a/.github/prompts/run-tests.prompt.md b/.github/prompts/run-tests.prompt.md index d5b2f749..d431ec44 100644 --- a/.github/prompts/run-tests.prompt.md +++ b/.github/prompts/run-tests.prompt.md @@ -57,8 +57,12 @@ if [ -n "$DB_CONNECTION_STRING" ]; then echo "✅ Connection string is set"; els ``` **If not set and you need integration tests:** + +> ⚠️ **SECURITY WARNING:** Replace placeholders with your own values. NEVER commit real credentials to version control. `TrustServerCertificate=yes` should only be used for isolated local development. + ```bash -export DB_CONNECTION_STRING="Driver={ODBC Driver 18 for SQL Server};Server=your_server;Database=your_db;UID=your_user;PWD=your_password;TrustServerCertificate=yes" +# LOCAL DEVELOPMENT ONLY - replace placeholders, never commit real credentials! +export DB_CONNECTION_STRING="Driver={ODBC Driver 18 for SQL Server};Server=localhost;Database=testdb;UID=your_user;PWD=your_password;TrustServerCertificate=yes" ``` > 💡 Unit tests (test_000, test_001, test_002, test_007) don't require a database. @@ -226,7 +230,8 @@ pip install pytest pytest-cov # Check the environment variable is set echo $DB_CONNECTION_STRING -# Set it with correct values +# Set it with correct values (LOCAL DEVELOPMENT ONLY) +# WARNING: Never commit real credentials. TrustServerCertificate=yes is for local dev only. export DB_CONNECTION_STRING="Driver={ODBC Driver 18 for SQL Server};Server=localhost;Database=testdb;UID=sa;PWD=YourPassword;TrustServerCertificate=yes" ``` diff --git a/.github/prompts/setup-dev-env.prompt.md b/.github/prompts/setup-dev-env.prompt.md index f279ea6f..422435d7 100644 --- a/.github/prompts/setup-dev-env.prompt.md +++ b/.github/prompts/setup-dev-env.prompt.md @@ -25,11 +25,11 @@ python --version python3 --version ``` -**Supported versions:** Python 3.10, 3.11, 3.12, 3.13 +**Supported versions:** Refer to `pyproject.toml` or `setup.py` (`python_requires`/classifiers) for the authoritative list. Generally, Python 3.10 or later is required. | Version | Status | |---------|--------| -| 3.10+ | ✅ Supported | +| 3.10+ (per project metadata) | ✅ Supported | | 3.9 and below | ❌ Not supported | ### 1.2 Check Python Location @@ -262,17 +262,23 @@ python -c "import pybind11; print('pybind11:', pybind11.get_include())" ### 5.1 Database Connection String (For Integration Tests) +> ⚠️ **SECURITY WARNING:** +> - **NEVER commit actual credentials** to version control or share them in documentation. +> - `TrustServerCertificate=yes` disables TLS certificate validation and should **ONLY be used for isolated local development**, never for remote or production connections. + ```bash -# Set connection string for tests -export DB_CONNECTION_STRING="Driver={ODBC Driver 18 for SQL Server};Server=your_server;Database=your_db;UID=your_user;PWD=your_password;TrustServerCertificate=yes" +# Set connection string for tests (LOCAL DEVELOPMENT ONLY) +# Replace placeholders with your own values - NEVER commit real credentials! +export DB_CONNECTION_STRING="Driver={ODBC Driver 18 for SQL Server};Server=localhost;Database=testdb;UID=your_user;PWD=your_password;TrustServerCertificate=yes" # Verify it's set echo $DB_CONNECTION_STRING ``` -**Windows:** +**Windows (LOCAL DEVELOPMENT ONLY):** ```cmd -set DB_CONNECTION_STRING=Driver={ODBC Driver 18 for SQL Server};Server=your_server;Database=your_db;UID=your_user;PWD=your_password;TrustServerCertificate=yes +REM Replace placeholders with your own values - NEVER commit real credentials! +set DB_CONNECTION_STRING=Driver={ODBC Driver 18 for SQL Server};Server=localhost;Database=testdb;UID=your_user;PWD=your_password;TrustServerCertificate=yes ``` > 💡 **Tip:** Add this to your shell profile (`.bashrc`, `.zshrc`) or venv's `activate` script to persist it. From 2ecd4bdb5ce8a2691f4c830fbc7fc1dfe9297107 Mon Sep 17 00:00:00 2001 From: Gaurav Sharma Date: Mon, 5 Jan 2026 19:57:01 +0530 Subject: [PATCH 04/20] fix: replace remaining git add . with git add --- .github/prompts/create-pr.prompt.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/prompts/create-pr.prompt.md b/.github/prompts/create-pr.prompt.md index ef797e73..8c8cf76a 100644 --- a/.github/prompts/create-pr.prompt.md +++ b/.github/prompts/create-pr.prompt.md @@ -484,7 +484,7 @@ git checkout **Fix:** ```bash # Make your changes -git add . +git add git commit -m "fix: address PR feedback" git push @@ -546,7 +546,7 @@ git log --oneline -5 git checkout -b bewithgaurav/feat/my-feature # Stage and commit -git add . +git add git commit -m "feat: description" # Push From ee528cd117fd84f22946bf03c81c25ee71c52046 Mon Sep 17 00:00:00 2001 From: Gaurav Sharma Date: Mon, 5 Jan 2026 19:58:12 +0530 Subject: [PATCH 05/20] fix: add maintenance note for team member prefixes --- .github/prompts/create-pr.prompt.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/prompts/create-pr.prompt.md b/.github/prompts/create-pr.prompt.md index 8c8cf76a..b7f94b13 100644 --- a/.github/prompts/create-pr.prompt.md +++ b/.github/prompts/create-pr.prompt.md @@ -61,6 +61,9 @@ git pull origin main **Branch Naming Convention:** `//` or `/` **Team Member Prefixes:** + +> 📝 **Note:** Keep this list up-to-date as team composition changes. + | Name | Branch Prefix | |------|---------------| | Gaurav | `bewithgaurav/` | From 4d3308f9dea808308da7605f1611a41b2b6192a0 Mon Sep 17 00:00:00 2001 From: Gaurav Sharma Date: Mon, 5 Jan 2026 20:55:29 +0530 Subject: [PATCH 06/20] refactor: improve run-tests prompt prerequisites flow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add sequential prerequisite checks: venv → pytest → DB connection - Ask user for connection string if not set (instead of offering unit tests only) - Remove 'unit tests only' option - Consolidate connection string setup in prerequisites section --- .github/prompts/run-tests.prompt.md | 89 ++++++++++++++++------------- 1 file changed, 50 insertions(+), 39 deletions(-) diff --git a/.github/prompts/run-tests.prompt.md b/.github/prompts/run-tests.prompt.md index d431ec44..ba6a15b4 100644 --- a/.github/prompts/run-tests.prompt.md +++ b/.github/prompts/run-tests.prompt.md @@ -7,15 +7,56 @@ You are a development assistant helping run pytest for the mssql-python driver. ## PREREQUISITES -> ⚠️ **This prompt assumes your development environment is already set up.** -> If you haven't set up your environment yet, use `#setup-dev-env` first. +Before running tests, you MUST complete these checks **in order**: + +### Step 1: Activate Virtual Environment + +```bash +source myvenv/bin/activate +``` + +Verify it's active: +```bash +echo $VIRTUAL_ENV +# Expected: /path/to/mssql-python/myvenv +``` + +**If empty or wrong path:** Activate the venv before proceeding. + +### Step 2: Verify pytest is Installed + +```bash +python -c "import pytest; print('✅ pytest ready:', pytest.__version__)" +``` + +**If this fails:** +```bash +pip install pytest pytest-cov +``` + +### Step 3: Verify Database Connection String + +```bash +if [ -n "$DB_CONNECTION_STRING" ]; then echo "✅ Connection string is set"; else echo "❌ Not set"; fi +``` + +**If not set:** Ask the developer for their connection string: + +> "I need your database connection string to run tests. Please provide the connection details: +> - Server (e.g., localhost, your-server.database.windows.net) +> - Database name +> - Username +> - Password +> +> Or provide the full connection string if you have one." + +Once the developer provides the details, set it: -**Quick sanity check:** ```bash -echo $VIRTUAL_ENV && python -c "import pytest; print('✅ Ready to test')" +export DB_CONNECTION_STRING="Driver={ODBC Driver 18 for SQL Server};Server=;Database=;UID=;PWD=;TrustServerCertificate=yes" ``` -If this fails, run the setup prompt first. +> ⚠️ **SECURITY:** `TrustServerCertificate=yes` is for local development only. Never use in production. --- @@ -42,34 +83,11 @@ Help the developer run tests to validate their changes. Follow this process base > "What would you like to test?" > 1. **All tests** - Run full suite (recommended before PR) > 2. **Specific tests** - Tell me which file(s) or test name(s) -> 3. **Just unit tests** - Skip integration tests requiring DB -> 4. **With coverage** - Generate coverage report +> 3. **With coverage** - Generate coverage report --- -## STEP 2: Verify Connection String (For Integration Tests) - -Integration tests require a database connection. Check if it's set: - -```bash -# Check if DB_CONNECTION_STRING is set -if [ -n "$DB_CONNECTION_STRING" ]; then echo "✅ Connection string is set"; else echo "⚠️ Not set - integration tests will fail"; fi -``` - -**If not set and you need integration tests:** - -> ⚠️ **SECURITY WARNING:** Replace placeholders with your own values. NEVER commit real credentials to version control. `TrustServerCertificate=yes` should only be used for isolated local development. - -```bash -# LOCAL DEVELOPMENT ONLY - replace placeholders, never commit real credentials! -export DB_CONNECTION_STRING="Driver={ODBC Driver 18 for SQL Server};Server=localhost;Database=testdb;UID=your_user;PWD=your_password;TrustServerCertificate=yes" -``` - -> 💡 Unit tests (test_000, test_001, test_002, test_007) don't require a database. - ---- - -## STEP 3: Run Tests +## STEP 2: Run Tests ### Option A: Run All Tests (Default - Excludes Stress Tests) @@ -136,16 +154,9 @@ python -m pytest --lf -v python -m pytest --ff -v ``` -### Option H: Run Unit Tests Only (No Database Required) - -```bash -# Tests that don't need a database connection -python -m pytest tests/test_000_dependencies.py tests/test_001_globals.py tests/test_002_types.py tests/test_007_logging.py -v -``` - --- -## STEP 4: Understanding Test Output +## STEP 3: Understanding Test Output ### Test Result Indicators @@ -178,7 +189,7 @@ tests/test_004_cursor.py:25: DatabaseError --- -## STEP 5: Test File Reference +## STEP 4: Test File Reference ### Test Files and What They Cover From 41a11a0aa9963bd3144a90f2e3a0844653939e27 Mon Sep 17 00:00:00 2001 From: Gaurav Sharma Date: Mon, 5 Jan 2026 20:57:23 +0530 Subject: [PATCH 07/20] fix: handle different venv names in run-tests prompt - Check if venv is already active first - Search for common venv directories (myvenv, venv, .venv, testenv) - Offer to create new venv if none found --- .github/prompts/run-tests.prompt.md | 34 ++++++++++++++++++++++++----- 1 file changed, 29 insertions(+), 5 deletions(-) diff --git a/.github/prompts/run-tests.prompt.md b/.github/prompts/run-tests.prompt.md index ba6a15b4..6e0205c1 100644 --- a/.github/prompts/run-tests.prompt.md +++ b/.github/prompts/run-tests.prompt.md @@ -11,17 +11,41 @@ Before running tests, you MUST complete these checks **in order**: ### Step 1: Activate Virtual Environment +First, check if a venv is already active: + ```bash -source myvenv/bin/activate +echo $VIRTUAL_ENV ``` -Verify it's active: +**If a path is shown:** ✅ venv is active, skip to Step 2. + +**If empty:** Look for existing venv directories: + ```bash -echo $VIRTUAL_ENV -# Expected: /path/to/mssql-python/myvenv +ls -d myvenv venv .venv testenv 2>/dev/null | head -1 ``` -**If empty or wrong path:** Activate the venv before proceeding. +- **If found:** Activate it: + ```bash + source /bin/activate + ``` + +- **If not found:** Ask the developer: + > "No virtual environment found. Would you like me to: + > 1. Create a new venv called `myvenv` + > 2. Use a different venv (tell me the path) + > 3. You'll activate it yourself" + + To create a new venv: + ```bash + python3 -m venv myvenv && source myvenv/bin/activate && pip install -r requirements.txt pytest pytest-cov && pip install -e . + ``` + +Verify venv is active: +```bash +echo $VIRTUAL_ENV +# Expected: /path/to/mssql-python/ +``` ### Step 2: Verify pytest is Installed From b6b492d2fec41bca7a638d5c47ad1ea79acc01e9 Mon Sep 17 00:00:00 2001 From: Gaurav Sharma Date: Mon, 5 Jan 2026 21:01:12 +0530 Subject: [PATCH 08/20] refactor: add numeric prefixes to prompt files for workflow order Renamed prompts to reflect natural workflow sequence: - 01-setup-dev-env.prompt.md (first-time setup) - 02-build-ddbc.prompt.md (build C++ extension) - 03-run-tests.prompt.md (run pytest) - 04-create-pr.prompt.md (submit work) Updated all cross-references between prompts --- ...setup-dev-env.prompt.md => 01-setup-dev-env.prompt.md} | 4 ++-- .../{build-ddbc.prompt.md => 02-build-ddbc.prompt.md} | 6 +++--- .../{run-tests.prompt.md => 03-run-tests.prompt.md} | 8 ++++---- .../{create-pr.prompt.md => 04-create-pr.prompt.md} | 4 ++-- 4 files changed, 11 insertions(+), 11 deletions(-) rename .github/prompts/{setup-dev-env.prompt.md => 01-setup-dev-env.prompt.md} (99%) rename .github/prompts/{build-ddbc.prompt.md => 02-build-ddbc.prompt.md} (97%) rename .github/prompts/{run-tests.prompt.md => 03-run-tests.prompt.md} (98%) rename .github/prompts/{create-pr.prompt.md => 04-create-pr.prompt.md} (99%) diff --git a/.github/prompts/setup-dev-env.prompt.md b/.github/prompts/01-setup-dev-env.prompt.md similarity index 99% rename from .github/prompts/setup-dev-env.prompt.md rename to .github/prompts/01-setup-dev-env.prompt.md index 422435d7..91b30bac 100644 --- a/.github/prompts/setup-dev-env.prompt.md +++ b/.github/prompts/01-setup-dev-env.prompt.md @@ -486,7 +486,7 @@ echo "✅ Setup complete!" Once setup is complete, you can: -1. **Build DDBC extensions** → Use `#build-ddbc` -2. **Run tests** → Use `#run-tests` +1. **Build DDBC extensions** → Use `#02-build-ddbc` +2. **Run tests** → Use `#03-run-tests` > 💡 You typically only need to run this setup prompt **once** per machine or after major changes. diff --git a/.github/prompts/build-ddbc.prompt.md b/.github/prompts/02-build-ddbc.prompt.md similarity index 97% rename from .github/prompts/build-ddbc.prompt.md rename to .github/prompts/02-build-ddbc.prompt.md index 88f6451a..fe19b302 100644 --- a/.github/prompts/build-ddbc.prompt.md +++ b/.github/prompts/02-build-ddbc.prompt.md @@ -8,7 +8,7 @@ You are a development assistant helping rebuild the DDBC C++ pybind11 extensions ## PREREQUISITES > ⚠️ **This prompt assumes your development environment is already set up.** -> If you haven't set up your environment yet, use `#setup-dev-env` first. +> If you haven't set up your environment yet, use `#01-setup-dev-env` first. **Quick sanity check:** ```bash @@ -308,6 +308,6 @@ cd mssql_python/pybind && rm -rf build && ./build.sh && cd ../.. && python -c "f Once the build succeeds: -1. **Run tests** → Use `#run-tests` +1. **Run tests** → Use `#03-run-tests` 2. **Test manually** with a connection to SQL Server -3. **Create a PR** with your C++ changes → Use `#create-pr` +3. **Create a PR** with your C++ changes → Use `#04-create-pr` diff --git a/.github/prompts/run-tests.prompt.md b/.github/prompts/03-run-tests.prompt.md similarity index 98% rename from .github/prompts/run-tests.prompt.md rename to .github/prompts/03-run-tests.prompt.md index 6e0205c1..fd750e57 100644 --- a/.github/prompts/run-tests.prompt.md +++ b/.github/prompts/03-run-tests.prompt.md @@ -251,7 +251,7 @@ pip install -e . # Check venv is active echo $VIRTUAL_ENV -# If empty, activate it (run `#setup-dev-env`) +# If empty, activate it (run `#01-setup-dev-env`) # If active, install pytest pip install pytest pytest-cov ``` @@ -302,7 +302,7 @@ python -m pytest tests/test_000_dependencies.py tests/test_001_globals.py tests/ **Cause:** C++ extension not built or Python version mismatch **Fix:** -Use `#build-ddbc` to rebuild the extension: +Use `#02-build-ddbc` to rebuild the extension: ```bash cd mssql_python/pybind && ./build.sh && cd ../.. python -c "from mssql_python import connect; print('OK')" @@ -397,9 +397,9 @@ addopts = -m "not stress" Based on test results: -1. **All passed** → Ready to create/update PR → Use `#create-pr` +1. **All passed** → Ready to create/update PR → Use `#04-create-pr` 2. **Some failed** → Review failures, fix issues, re-run 3. **Coverage decreased** → Add tests for new code paths 4. **Need to debug** → Use `-s` flag to see print output, or `--pdb` to drop into debugger -> 💡 **Tip:** If you made C++ changes, ensure you've rebuilt using `#build-ddbc` first! +> 💡 **Tip:** If you made C++ changes, ensure you've rebuilt using `#02-build-ddbc` first! diff --git a/.github/prompts/create-pr.prompt.md b/.github/prompts/04-create-pr.prompt.md similarity index 99% rename from .github/prompts/create-pr.prompt.md rename to .github/prompts/04-create-pr.prompt.md index b7f94b13..93ee9322 100644 --- a/.github/prompts/create-pr.prompt.md +++ b/.github/prompts/04-create-pr.prompt.md @@ -8,9 +8,9 @@ You are a development assistant helping create a pull request for the mssql-pyth ## PREREQUISITES Before creating a PR, ensure: -1. ✅ All tests pass (use `#run-tests`) +1. ✅ All tests pass (use `#03-run-tests`) 2. ✅ Code changes are complete and working -3. ✅ If C++ changes, extension is rebuilt (use `#build-ddbc`) +3. ✅ If C++ changes, extension is rebuilt (use `#02-build-ddbc`) --- From 407811de81ad7bb3a3b9243c092eb6b61fd76667 Mon Sep 17 00:00:00 2001 From: Gaurav Sharma Date: Mon, 5 Jan 2026 22:06:06 +0530 Subject: [PATCH 09/20] fix: update deprecated 'mode' to 'agent' in prompt frontmatter --- .github/prompts/01-setup-dev-env.prompt.md | 2 +- .github/prompts/02-build-ddbc.prompt.md | 2 +- .github/prompts/03-run-tests.prompt.md | 2 +- .github/prompts/04-create-pr.prompt.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/prompts/01-setup-dev-env.prompt.md b/.github/prompts/01-setup-dev-env.prompt.md index 91b30bac..1d2cec84 100644 --- a/.github/prompts/01-setup-dev-env.prompt.md +++ b/.github/prompts/01-setup-dev-env.prompt.md @@ -1,5 +1,5 @@ --- -mode: 'agent' +agent: 'agent' --- # Setup Development Environment Prompt for microsoft/mssql-python diff --git a/.github/prompts/02-build-ddbc.prompt.md b/.github/prompts/02-build-ddbc.prompt.md index fe19b302..0b93e2be 100644 --- a/.github/prompts/02-build-ddbc.prompt.md +++ b/.github/prompts/02-build-ddbc.prompt.md @@ -1,5 +1,5 @@ --- -mode: 'agent' +agent: 'agent' --- # Build DDBC Extensions Prompt for microsoft/mssql-python diff --git a/.github/prompts/03-run-tests.prompt.md b/.github/prompts/03-run-tests.prompt.md index fd750e57..7028ac15 100644 --- a/.github/prompts/03-run-tests.prompt.md +++ b/.github/prompts/03-run-tests.prompt.md @@ -1,5 +1,5 @@ --- -mode: 'agent' +agent: 'agent' --- # Run Tests Prompt for microsoft/mssql-python diff --git a/.github/prompts/04-create-pr.prompt.md b/.github/prompts/04-create-pr.prompt.md index 93ee9322..be03fdfc 100644 --- a/.github/prompts/04-create-pr.prompt.md +++ b/.github/prompts/04-create-pr.prompt.md @@ -1,5 +1,5 @@ --- -mode: 'agent' +agent: 'agent' --- # Create Pull Request Prompt for microsoft/mssql-python From d8ebe1df10d7156633d7e2b959e660fe91e2106c Mon Sep 17 00:00:00 2001 From: Gaurav Sharma Date: Mon, 5 Jan 2026 22:20:33 +0530 Subject: [PATCH 10/20] feat: enhance prompt frontmatter with description, name, model, and tools - Added short names for easier invocation (/setup, /build, /test, /pr) - Added descriptions for prompt picker - Added argument hints to guide user input - Set claude-sonnet-4 as preferred model - Specified relevant tools for each prompt --- .github/prompts/01-setup-dev-env.prompt.md | 7 +++++++ .github/prompts/02-build-ddbc.prompt.md | 7 +++++++ .github/prompts/03-run-tests.prompt.md | 7 +++++++ .github/prompts/04-create-pr.prompt.md | 8 ++++++++ 4 files changed, 29 insertions(+) diff --git a/.github/prompts/01-setup-dev-env.prompt.md b/.github/prompts/01-setup-dev-env.prompt.md index 1d2cec84..77a40432 100644 --- a/.github/prompts/01-setup-dev-env.prompt.md +++ b/.github/prompts/01-setup-dev-env.prompt.md @@ -1,5 +1,12 @@ --- +description: "Set up development environment for mssql-python" +name: "setup" +argument-hint: "Platform? (macOS/Linux/Windows)" agent: 'agent' +model: 'claude-sonnet-4' +tools: + - terminalLastCommand + - codebase --- # Setup Development Environment Prompt for microsoft/mssql-python diff --git a/.github/prompts/02-build-ddbc.prompt.md b/.github/prompts/02-build-ddbc.prompt.md index 0b93e2be..557703b4 100644 --- a/.github/prompts/02-build-ddbc.prompt.md +++ b/.github/prompts/02-build-ddbc.prompt.md @@ -1,5 +1,12 @@ --- +description: "Build C++ pybind11 extension (ddbc_bindings)" +name: "build" +argument-hint: "Clean build? (yes/no)" agent: 'agent' +model: 'claude-sonnet-4' +tools: + - terminalLastCommand + - codebase --- # Build DDBC Extensions Prompt for microsoft/mssql-python diff --git a/.github/prompts/03-run-tests.prompt.md b/.github/prompts/03-run-tests.prompt.md index 7028ac15..38a95880 100644 --- a/.github/prompts/03-run-tests.prompt.md +++ b/.github/prompts/03-run-tests.prompt.md @@ -1,5 +1,12 @@ --- +description: "Run pytest for mssql-python driver" +name: "test" +argument-hint: "What to test? (all/specific file/with coverage)" agent: 'agent' +model: 'claude-sonnet-4' +tools: + - terminalLastCommand + - codebase --- # Run Tests Prompt for microsoft/mssql-python diff --git a/.github/prompts/04-create-pr.prompt.md b/.github/prompts/04-create-pr.prompt.md index be03fdfc..5bf6b7d5 100644 --- a/.github/prompts/04-create-pr.prompt.md +++ b/.github/prompts/04-create-pr.prompt.md @@ -1,5 +1,13 @@ --- +description: "Create a well-structured PR for mssql-python" +name: "pr" +argument-hint: "Work item ID? (e.g., AB#12345)" agent: 'agent' +model: 'claude-sonnet-4' +tools: + - terminalLastCommand + - codebase + - githubRepo --- # Create Pull Request Prompt for microsoft/mssql-python From 6bb139944288d9e4c0b8a9f488a3d319ffc52ecf Mon Sep 17 00:00:00 2001 From: Gaurav Sharma Date: Mon, 5 Jan 2026 22:24:54 +0530 Subject: [PATCH 11/20] fix: update prompt frontmatter - Remove argument-hint (prompts are interactive) - Update tool names to new prefixed format (read/, search/, web/) - Add github/* MCP server tools for PR creation - Remove model field (use user's selected model) --- .github/prompts/01-setup-dev-env.prompt.md | 6 ++---- .github/prompts/02-build-ddbc.prompt.md | 6 ++---- .github/prompts/03-run-tests.prompt.md | 6 ++---- .github/prompts/04-create-pr.prompt.md | 9 ++++----- 4 files changed, 10 insertions(+), 17 deletions(-) diff --git a/.github/prompts/01-setup-dev-env.prompt.md b/.github/prompts/01-setup-dev-env.prompt.md index 77a40432..cbb8fa39 100644 --- a/.github/prompts/01-setup-dev-env.prompt.md +++ b/.github/prompts/01-setup-dev-env.prompt.md @@ -1,12 +1,10 @@ --- description: "Set up development environment for mssql-python" name: "setup" -argument-hint: "Platform? (macOS/Linux/Windows)" agent: 'agent' -model: 'claude-sonnet-4' tools: - - terminalLastCommand - - codebase + - read/terminalLastCommand + - search/codebase --- # Setup Development Environment Prompt for microsoft/mssql-python diff --git a/.github/prompts/02-build-ddbc.prompt.md b/.github/prompts/02-build-ddbc.prompt.md index 557703b4..0a842fdf 100644 --- a/.github/prompts/02-build-ddbc.prompt.md +++ b/.github/prompts/02-build-ddbc.prompt.md @@ -1,12 +1,10 @@ --- description: "Build C++ pybind11 extension (ddbc_bindings)" name: "build" -argument-hint: "Clean build? (yes/no)" agent: 'agent' -model: 'claude-sonnet-4' tools: - - terminalLastCommand - - codebase + - read/terminalLastCommand + - search/codebase --- # Build DDBC Extensions Prompt for microsoft/mssql-python diff --git a/.github/prompts/03-run-tests.prompt.md b/.github/prompts/03-run-tests.prompt.md index 38a95880..415365ca 100644 --- a/.github/prompts/03-run-tests.prompt.md +++ b/.github/prompts/03-run-tests.prompt.md @@ -1,12 +1,10 @@ --- description: "Run pytest for mssql-python driver" name: "test" -argument-hint: "What to test? (all/specific file/with coverage)" agent: 'agent' -model: 'claude-sonnet-4' tools: - - terminalLastCommand - - codebase + - read/terminalLastCommand + - search/codebase --- # Run Tests Prompt for microsoft/mssql-python diff --git a/.github/prompts/04-create-pr.prompt.md b/.github/prompts/04-create-pr.prompt.md index 5bf6b7d5..e7656834 100644 --- a/.github/prompts/04-create-pr.prompt.md +++ b/.github/prompts/04-create-pr.prompt.md @@ -1,13 +1,12 @@ --- description: "Create a well-structured PR for mssql-python" name: "pr" -argument-hint: "Work item ID? (e.g., AB#12345)" agent: 'agent' -model: 'claude-sonnet-4' tools: - - terminalLastCommand - - codebase - - githubRepo + - read/terminalLastCommand + - search/codebase + - web/githubRepo + - github/* --- # Create Pull Request Prompt for microsoft/mssql-python From ec51a2bf0ec6045685a12e1df564a10592fa72aa Mon Sep 17 00:00:00 2001 From: Gaurav Sharma Date: Mon, 5 Jan 2026 22:39:37 +0530 Subject: [PATCH 12/20] fix: remove tools restriction from prompts Tools field was limiting agent capabilities. Removed to allow full tool access based on VS Code settings. --- .github/prompts/01-setup-dev-env.prompt.md | 3 --- .github/prompts/02-build-ddbc.prompt.md | 3 --- .github/prompts/03-run-tests.prompt.md | 3 --- .github/prompts/04-create-pr.prompt.md | 2 -- 4 files changed, 11 deletions(-) diff --git a/.github/prompts/01-setup-dev-env.prompt.md b/.github/prompts/01-setup-dev-env.prompt.md index cbb8fa39..fe9e666c 100644 --- a/.github/prompts/01-setup-dev-env.prompt.md +++ b/.github/prompts/01-setup-dev-env.prompt.md @@ -2,9 +2,6 @@ description: "Set up development environment for mssql-python" name: "setup" agent: 'agent' -tools: - - read/terminalLastCommand - - search/codebase --- # Setup Development Environment Prompt for microsoft/mssql-python diff --git a/.github/prompts/02-build-ddbc.prompt.md b/.github/prompts/02-build-ddbc.prompt.md index 0a842fdf..ee1d3f5f 100644 --- a/.github/prompts/02-build-ddbc.prompt.md +++ b/.github/prompts/02-build-ddbc.prompt.md @@ -2,9 +2,6 @@ description: "Build C++ pybind11 extension (ddbc_bindings)" name: "build" agent: 'agent' -tools: - - read/terminalLastCommand - - search/codebase --- # Build DDBC Extensions Prompt for microsoft/mssql-python diff --git a/.github/prompts/03-run-tests.prompt.md b/.github/prompts/03-run-tests.prompt.md index 415365ca..031a1f42 100644 --- a/.github/prompts/03-run-tests.prompt.md +++ b/.github/prompts/03-run-tests.prompt.md @@ -2,9 +2,6 @@ description: "Run pytest for mssql-python driver" name: "test" agent: 'agent' -tools: - - read/terminalLastCommand - - search/codebase --- # Run Tests Prompt for microsoft/mssql-python diff --git a/.github/prompts/04-create-pr.prompt.md b/.github/prompts/04-create-pr.prompt.md index e7656834..a0b163ae 100644 --- a/.github/prompts/04-create-pr.prompt.md +++ b/.github/prompts/04-create-pr.prompt.md @@ -3,8 +3,6 @@ description: "Create a well-structured PR for mssql-python" name: "pr" agent: 'agent' tools: - - read/terminalLastCommand - - search/codebase - web/githubRepo - github/* --- From bc14b5f054d009ef3fbcfb76c8a7cd2bfea2b200 Mon Sep 17 00:00:00 2001 From: Gaurav Sharma Date: Mon, 5 Jan 2026 22:43:01 +0530 Subject: [PATCH 13/20] refactor: remove lipo architecture check from build prompt --- .github/prompts/02-build-ddbc.prompt.md | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/.github/prompts/02-build-ddbc.prompt.md b/.github/prompts/02-build-ddbc.prompt.md index ee1d3f5f..2473791d 100644 --- a/.github/prompts/02-build-ddbc.prompt.md +++ b/.github/prompts/02-build-ddbc.prompt.md @@ -2,6 +2,7 @@ description: "Build C++ pybind11 extension (ddbc_bindings)" name: "build" agent: 'agent' +model: Claude Sonnet 4.5 (copilot) --- # Build DDBC Extensions Prompt for microsoft/mssql-python @@ -128,14 +129,6 @@ cd ../.. python -c "from mssql_python import connect; print('✅ Import successful')" ``` -### 2.3 Verify Architecture (macOS Only) - -```bash -# Check if universal binary -lipo -info mssql_python/ddbc_bindings.*.so -# Expected: Architectures in the fat file: ... are: x86_64 arm64 -``` - --- ## STEP 3: Clean Build (If Needed) From c7bfcab456eb49f9a6c79b265eb85f9ef1b49ad9 Mon Sep 17 00:00:00 2001 From: Gaurav Sharma Date: Mon, 5 Jan 2026 22:43:57 +0530 Subject: [PATCH 14/20] refactor: verify build by running main.py instead of import check --- .github/prompts/02-build-ddbc.prompt.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/prompts/02-build-ddbc.prompt.md b/.github/prompts/02-build-ddbc.prompt.md index 2473791d..c5353937 100644 --- a/.github/prompts/02-build-ddbc.prompt.md +++ b/.github/prompts/02-build-ddbc.prompt.md @@ -121,12 +121,12 @@ ls -la ../ddbc_bindings.*.so dir ..\ddbc_bindings.*.pyd ``` -### 2.2 Verify Import Works +### 2.2 Verify Build Works ```bash # From repository root (important!) cd ../.. -python -c "from mssql_python import connect; print('✅ Import successful')" +python main.py ``` --- From b1dc9b3db8b680d17930424123cbe253852b9ccb Mon Sep 17 00:00:00 2001 From: Gaurav Sharma Date: Mon, 5 Jan 2026 22:54:54 +0530 Subject: [PATCH 15/20] fix: enforce returning to repo root after build to prevent directory confusion - Combine cd commands with build script to automatically return to root - Update both macOS/Linux and Windows build commands - Fix verification paths to assume repo root location - Add note documenting the automatic directory return - Prevents directory navigation issues during build verification --- .github/prompts/02-build-ddbc.prompt.md | 40 ++++++++++++++----------- 1 file changed, 22 insertions(+), 18 deletions(-) diff --git a/.github/prompts/02-build-ddbc.prompt.md b/.github/prompts/02-build-ddbc.prompt.md index c5353937..fd2228ef 100644 --- a/.github/prompts/02-build-ddbc.prompt.md +++ b/.github/prompts/02-build-ddbc.prompt.md @@ -15,10 +15,17 @@ You are a development assistant helping rebuild the DDBC C++ pybind11 extensions **Quick sanity check:** ```bash -echo $VIRTUAL_ENV && python -c "import pybind11; print('✅ Ready to build')" +# Verify venv is active +if [ -z "$VIRTUAL_ENV" ]; then + echo "❌ No virtual environment active. Run: source myvenv/bin/activate" + exit 1 +fi + +# Verify pybind11 is installed +python -c "import pybind11; print('✅ Ready to build with Python', __import__('sys').version.split()[0])" ``` -If this fails, run the setup prompt first. +**Important:** The C++ extension will be built for the active Python version. Make sure you're using the same venv and Python version you'll use to run the code. --- @@ -67,31 +74,27 @@ mssql_python/pybind/ ## STEP 1: Build the Extension -### 1.1 Navigate to Build Directory +### 1.1 Run Build Script -```bash -cd mssql_python/pybind -``` - -### 1.2 Run Build Script +**Important:** The commands below will automatically return to the repository root after building. #### macOS / Linux ```bash # Standard build -./build.sh +cd mssql_python/pybind && ./build.sh && cd ../.. # Build with code coverage instrumentation (Linux only) -./build.sh codecov +cd mssql_python/pybind && ./build.sh codecov && cd ../.. ``` #### Windows (in Developer Command Prompt) ```cmd -build.bat +cd mssql_python\pybind && build.bat && cd ..\.. ``` -### 1.3 What the Build Does +### 1.2 What the Build Does 1. **Cleans** existing `build/` directory 2. **Detects** Python version and architecture @@ -99,6 +102,7 @@ build.bat 4. **Compiles** C++ code to platform-specific extension 5. **Copies** the built extension to `mssql_python/` directory 6. **Signs** the extension (macOS only - for SIP compliance) +7. **Returns** to repository root directory **Output files by platform:** | Platform | Output File | @@ -111,22 +115,22 @@ build.bat ## STEP 2: Verify the Build +**These commands assume you're at the repository root** (which you should be after Step 1). + ### 2.1 Check Output File Exists ```bash # macOS/Linux -ls -la ../ddbc_bindings.*.so +ls -la mssql_python/ddbc_bindings.*.so # Windows -dir ..\ddbc_bindings.*.pyd +dir mssql_python\ddbc_bindings.*.pyd ``` -### 2.2 Verify Build Works +### 2.2 Verify Import Works ```bash -# From repository root (important!) -cd ../.. -python main.py +python -c "from mssql_python import connect; print('✅ Import successful')" ``` --- From 13f341e7d9e64bbfe395594cb8fd164af10fe67d Mon Sep 17 00:00:00 2001 From: Gaurav Sharma Date: Mon, 5 Jan 2026 22:56:03 +0530 Subject: [PATCH 16/20] chore: update all Copilot prompts with final improvements - All prompts now use numeric prefixes (01-04) for ordering - Updated frontmatter with agent, description, and name fields - Removed invalid/blocking fields (model, argument-hint, tools) - Fixed tool references to use correct prefixes (read/, search/, web/) - Build prompt enforces returning to repo root - Test prompt has sequential prerequisites with proper venv checks --- .github/prompts/01-setup-dev-env.prompt.md | 1 + .github/prompts/03-run-tests.prompt.md | 1 + .github/prompts/04-create-pr.prompt.md | 1 + 3 files changed, 3 insertions(+) diff --git a/.github/prompts/01-setup-dev-env.prompt.md b/.github/prompts/01-setup-dev-env.prompt.md index fe9e666c..b21a47f2 100644 --- a/.github/prompts/01-setup-dev-env.prompt.md +++ b/.github/prompts/01-setup-dev-env.prompt.md @@ -2,6 +2,7 @@ description: "Set up development environment for mssql-python" name: "setup" agent: 'agent' +model: Claude Sonnet 4.5 (copilot) --- # Setup Development Environment Prompt for microsoft/mssql-python diff --git a/.github/prompts/03-run-tests.prompt.md b/.github/prompts/03-run-tests.prompt.md index 031a1f42..4ddb29b1 100644 --- a/.github/prompts/03-run-tests.prompt.md +++ b/.github/prompts/03-run-tests.prompt.md @@ -2,6 +2,7 @@ description: "Run pytest for mssql-python driver" name: "test" agent: 'agent' +model: Claude Sonnet 4.5 (copilot) --- # Run Tests Prompt for microsoft/mssql-python diff --git a/.github/prompts/04-create-pr.prompt.md b/.github/prompts/04-create-pr.prompt.md index a0b163ae..a78fd015 100644 --- a/.github/prompts/04-create-pr.prompt.md +++ b/.github/prompts/04-create-pr.prompt.md @@ -2,6 +2,7 @@ description: "Create a well-structured PR for mssql-python" name: "pr" agent: 'agent' +model: Claude Sonnet 4.5 (copilot) tools: - web/githubRepo - github/* From 196bfc2bf5fd54b86a9467ac4d630584130f18bc Mon Sep 17 00:00:00 2001 From: Gaurav Sharma Date: Mon, 5 Jan 2026 22:58:00 +0530 Subject: [PATCH 17/20] refactor: use mssql-python prefix for all prompt names - setup -> mssql-python-setup - build -> mssql-python-build - test -> mssql-python-test - pr -> mssql-python-pr This provides better namespace clarity and avoids conflicts with other project prompts. --- .github/prompts/01-setup-dev-env.prompt.md | 2 +- .github/prompts/02-build-ddbc.prompt.md | 2 +- .github/prompts/03-run-tests.prompt.md | 2 +- .github/prompts/04-create-pr.prompt.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/prompts/01-setup-dev-env.prompt.md b/.github/prompts/01-setup-dev-env.prompt.md index b21a47f2..3c0ab3a7 100644 --- a/.github/prompts/01-setup-dev-env.prompt.md +++ b/.github/prompts/01-setup-dev-env.prompt.md @@ -1,6 +1,6 @@ --- description: "Set up development environment for mssql-python" -name: "setup" +name: "mssql-python-setup" agent: 'agent' model: Claude Sonnet 4.5 (copilot) --- diff --git a/.github/prompts/02-build-ddbc.prompt.md b/.github/prompts/02-build-ddbc.prompt.md index fd2228ef..7cc452c0 100644 --- a/.github/prompts/02-build-ddbc.prompt.md +++ b/.github/prompts/02-build-ddbc.prompt.md @@ -1,6 +1,6 @@ --- description: "Build C++ pybind11 extension (ddbc_bindings)" -name: "build" +name: "mssql-python-build" agent: 'agent' model: Claude Sonnet 4.5 (copilot) --- diff --git a/.github/prompts/03-run-tests.prompt.md b/.github/prompts/03-run-tests.prompt.md index 4ddb29b1..41766d6c 100644 --- a/.github/prompts/03-run-tests.prompt.md +++ b/.github/prompts/03-run-tests.prompt.md @@ -1,6 +1,6 @@ --- description: "Run pytest for mssql-python driver" -name: "test" +name: "mssql-python-test" agent: 'agent' model: Claude Sonnet 4.5 (copilot) --- diff --git a/.github/prompts/04-create-pr.prompt.md b/.github/prompts/04-create-pr.prompt.md index a78fd015..25baadec 100644 --- a/.github/prompts/04-create-pr.prompt.md +++ b/.github/prompts/04-create-pr.prompt.md @@ -1,6 +1,6 @@ --- description: "Create a well-structured PR for mssql-python" -name: "pr" +name: "mssql-python-pr" agent: 'agent' model: Claude Sonnet 4.5 (copilot) tools: From 714a469c0d58844a2cfd4f131f2353de452b3dc3 Mon Sep 17 00:00:00 2001 From: Gaurav Sharma Date: Tue, 6 Jan 2026 11:37:06 +0530 Subject: [PATCH 18/20] refactor: remove numeric prefixes from prompt filenames - Rename 01-setup-dev-env.prompt.md -> setup-dev-env.prompt.md - Rename 02-build-ddbc.prompt.md -> build-ddbc.prompt.md - Rename 03-run-tests.prompt.md -> run-tests.prompt.md - Rename 04-create-pr.prompt.md -> create-pr.prompt.md - Update all cross-references to use new names without numbers - Improves discoverability and memorability of prompts - Natural naming makes prompts easier to find via #mssql-python-* --- .../{02-build-ddbc.prompt.md => build-ddbc.prompt.md} | 6 +++--- .../{04-create-pr.prompt.md => create-pr.prompt.md} | 4 ++-- .../{03-run-tests.prompt.md => run-tests.prompt.md} | 8 ++++---- ...01-setup-dev-env.prompt.md => setup-dev-env.prompt.md} | 4 ++-- 4 files changed, 11 insertions(+), 11 deletions(-) rename .github/prompts/{02-build-ddbc.prompt.md => build-ddbc.prompt.md} (97%) rename .github/prompts/{04-create-pr.prompt.md => create-pr.prompt.md} (99%) rename .github/prompts/{03-run-tests.prompt.md => run-tests.prompt.md} (98%) rename .github/prompts/{01-setup-dev-env.prompt.md => setup-dev-env.prompt.md} (99%) diff --git a/.github/prompts/02-build-ddbc.prompt.md b/.github/prompts/build-ddbc.prompt.md similarity index 97% rename from .github/prompts/02-build-ddbc.prompt.md rename to .github/prompts/build-ddbc.prompt.md index 7cc452c0..f55651d7 100644 --- a/.github/prompts/02-build-ddbc.prompt.md +++ b/.github/prompts/build-ddbc.prompt.md @@ -11,7 +11,7 @@ You are a development assistant helping rebuild the DDBC C++ pybind11 extensions ## PREREQUISITES > ⚠️ **This prompt assumes your development environment is already set up.** -> If you haven't set up your environment yet, use `#01-setup-dev-env` first. +> If you haven't set up your environment yet, use `#setup-dev-env` first. **Quick sanity check:** ```bash @@ -307,6 +307,6 @@ cd mssql_python/pybind && rm -rf build && ./build.sh && cd ../.. && python -c "f Once the build succeeds: -1. **Run tests** → Use `#03-run-tests` +1. **Run tests** → Use `#run-tests` 2. **Test manually** with a connection to SQL Server -3. **Create a PR** with your C++ changes → Use `#04-create-pr` +3. **Create a PR** with your C++ changes → Use `#create-pr` diff --git a/.github/prompts/04-create-pr.prompt.md b/.github/prompts/create-pr.prompt.md similarity index 99% rename from .github/prompts/04-create-pr.prompt.md rename to .github/prompts/create-pr.prompt.md index 25baadec..d17c3ae9 100644 --- a/.github/prompts/04-create-pr.prompt.md +++ b/.github/prompts/create-pr.prompt.md @@ -14,9 +14,9 @@ You are a development assistant helping create a pull request for the mssql-pyth ## PREREQUISITES Before creating a PR, ensure: -1. ✅ All tests pass (use `#03-run-tests`) +1. ✅ All tests pass (use `#run-tests`) 2. ✅ Code changes are complete and working -3. ✅ If C++ changes, extension is rebuilt (use `#02-build-ddbc`) +3. ✅ If C++ changes, extension is rebuilt (use `#build-ddbc`) --- diff --git a/.github/prompts/03-run-tests.prompt.md b/.github/prompts/run-tests.prompt.md similarity index 98% rename from .github/prompts/03-run-tests.prompt.md rename to .github/prompts/run-tests.prompt.md index 41766d6c..a0ab15d2 100644 --- a/.github/prompts/03-run-tests.prompt.md +++ b/.github/prompts/run-tests.prompt.md @@ -254,7 +254,7 @@ pip install -e . # Check venv is active echo $VIRTUAL_ENV -# If empty, activate it (run `#01-setup-dev-env`) +# If empty, activate it (run `#setup-dev-env`) # If active, install pytest pip install pytest pytest-cov ``` @@ -305,7 +305,7 @@ python -m pytest tests/test_000_dependencies.py tests/test_001_globals.py tests/ **Cause:** C++ extension not built or Python version mismatch **Fix:** -Use `#02-build-ddbc` to rebuild the extension: +Use `#build-ddbc` to rebuild the extension: ```bash cd mssql_python/pybind && ./build.sh && cd ../.. python -c "from mssql_python import connect; print('OK')" @@ -400,9 +400,9 @@ addopts = -m "not stress" Based on test results: -1. **All passed** → Ready to create/update PR → Use `#04-create-pr` +1. **All passed** → Ready to create/update PR → Use `#create-pr` 2. **Some failed** → Review failures, fix issues, re-run 3. **Coverage decreased** → Add tests for new code paths 4. **Need to debug** → Use `-s` flag to see print output, or `--pdb` to drop into debugger -> 💡 **Tip:** If you made C++ changes, ensure you've rebuilt using `#02-build-ddbc` first! +> 💡 **Tip:** If you made C++ changes, ensure you've rebuilt using `#build-ddbc` first! diff --git a/.github/prompts/01-setup-dev-env.prompt.md b/.github/prompts/setup-dev-env.prompt.md similarity index 99% rename from .github/prompts/01-setup-dev-env.prompt.md rename to .github/prompts/setup-dev-env.prompt.md index 3c0ab3a7..48d9238f 100644 --- a/.github/prompts/01-setup-dev-env.prompt.md +++ b/.github/prompts/setup-dev-env.prompt.md @@ -489,7 +489,7 @@ echo "✅ Setup complete!" Once setup is complete, you can: -1. **Build DDBC extensions** → Use `#02-build-ddbc` -2. **Run tests** → Use `#03-run-tests` +1. **Build DDBC extensions** → Use `#build-ddbc` +2. **Run tests** → Use `#run-tests` > 💡 You typically only need to run this setup prompt **once** per machine or after major changes. From fc636f1e488c1bda009f98b642f69632269111f4 Mon Sep 17 00:00:00 2001 From: Gaurav Sharma Date: Tue, 6 Jan 2026 12:21:10 +0530 Subject: [PATCH 19/20] feat: add SQL Server verification and troubleshooting to test and setup prompts - Add Step 4 in run-tests prompt to verify SQL Server is running before tests - Run main.py to check connectivity and fail fast with helpful guidance - Add comprehensive STEP 6 in setup-dev-env prompt for SQL Server setup - Include Docker, native installation, and Azure SQL Database options - Add detailed troubleshooting section with common issues and solutions - Include connectivity testing with sqlcmd and Python - Add debugging tools: port verification, log locations, network config - Prevent wasted time on connection errors by validating environment first --- .github/prompts/run-tests.prompt.md | 25 +++ .github/prompts/setup-dev-env.prompt.md | 270 +++++++++++++++++++++++- 2 files changed, 294 insertions(+), 1 deletion(-) diff --git a/.github/prompts/run-tests.prompt.md b/.github/prompts/run-tests.prompt.md index a0ab15d2..0e2cd1cd 100644 --- a/.github/prompts/run-tests.prompt.md +++ b/.github/prompts/run-tests.prompt.md @@ -85,6 +85,31 @@ export DB_CONNECTION_STRING="Driver={ODBC Driver 18 for SQL Server};Server= ⚠️ **SECURITY:** `TrustServerCertificate=yes` is for local development only. Never use in production. +### Step 4: Verify SQL Server is Running + +**CRITICAL:** Before running tests, verify SQL Server is accessible: + +```bash +python main.py +``` + +**If this succeeds:** You'll see database listings and "Connection closed successfully" → ✅ Ready to run tests! + +**If this fails with connection errors:** + +> "❌ SQL Server is not accessible. Please complete the environment setup first:" +> +> **Run the setup prompt** (`#setup-dev-env`) which includes: +> 1. Installing/starting SQL Server +> 2. Configuring connection strings +> 3. Verifying ODBC drivers +> +> Common issues: +> - SQL Server not running → See setup prompt for how to start it +> - Wrong connection string → Check server address, port, credentials +> - Firewall blocking connection → Ensure port 1433 is accessible +> - ODBC driver missing → Install "ODBC Driver 18 for SQL Server" + --- ## TASK diff --git a/.github/prompts/setup-dev-env.prompt.md b/.github/prompts/setup-dev-env.prompt.md index 48d9238f..b1e887e1 100644 --- a/.github/prompts/setup-dev-env.prompt.md +++ b/.github/prompts/setup-dev-env.prompt.md @@ -295,7 +295,275 @@ echo 'export DB_CONNECTION_STRING="your_connection_string"' >> myvenv/bin/activa --- -## STEP 6: Final Verification +## STEP 6: Start/Verify SQL Server + +### 6.1 Check if SQL Server is Running + +#### Option A: Using Docker (Recommended for Development) + +**Check if SQL Server container exists:** + +```bash +docker ps -a | grep mssql +``` + +**If container exists but is stopped:** + +```bash +docker start mssql-dev +``` + +**If no container exists, create and start one:** + +```bash +docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=YourStrongPassword123!" \ + -p 1433:1433 --name mssql-dev \ + -d mcr.microsoft.com/mssql/server:2022-latest +``` + +**Verify container is healthy:** + +```bash +# Check container status +docker ps | grep mssql + +# Check SQL Server logs for "ready" message +docker logs mssql-dev 2>&1 | grep "SQL Server is now ready" +``` + +**Useful Docker commands:** + +```bash +# Stop SQL Server container +docker stop mssql-dev + +# Start SQL Server container +docker start mssql-dev + +# Restart SQL Server container +docker restart mssql-dev + +# View SQL Server logs +docker logs -f mssql-dev + +# Remove container (will delete data!) +docker rm -f mssql-dev +``` + +#### Option B: Native SQL Server Installation + +**macOS:** + +SQL Server doesn't run natively on macOS. Use Docker (Option A) or connect to a remote server. + +**Linux (Ubuntu/Debian):** + +```bash +# Check if SQL Server service is running +sudo systemctl status mssql-server + +# Start SQL Server service +sudo systemctl start mssql-server + +# Enable auto-start on boot +sudo systemctl enable mssql-server + +# Restart SQL Server +sudo systemctl restart mssql-server + +# Stop SQL Server +sudo systemctl stop mssql-server +``` + +**Linux (RHEL/CentOS):** + +```bash +# Check status +sudo systemctl status mssql-server + +# Start/Stop/Restart commands are the same as Ubuntu/Debian above +``` + +**Windows:** + +```powershell +# Check SQL Server service status (PowerShell as Admin) +Get-Service -Name 'MSSQL$*' | Select-Object Name, Status + +# Start SQL Server service +Start-Service -Name 'MSSQL$MSSQLSERVER' + +# Stop SQL Server service +Stop-Service -Name 'MSSQL$MSSQLSERVER' + +# Restart SQL Server service +Restart-Service -Name 'MSSQL$MSSQLSERVER' + +# Or use SQL Server Configuration Manager (GUI) +``` + +#### Option C: Azure SQL Database + +No local SQL Server needed. Just ensure: +- Your Azure SQL Database is running +- Firewall rules allow your IP address +- Connection string is correct with proper credentials + +### 6.2 Test SQL Server Connectivity + +#### Using sqlcmd (SQL Server Command Line Tool) + +**Test local SQL Server connection:** + +```bash +sqlcmd -S localhost -U sa -P 'YourPassword' -Q "SELECT @@VERSION" +``` + +**If sqlcmd is not installed:** + +```bash +# macOS (via Homebrew) +brew install sqlcmd + +# Linux (Ubuntu/Debian) +curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add - +sudo add-apt-repository "$(wget -qO- https://packages.microsoft.com/config/ubuntu/20.04/prod.list)" +sudo apt-get update +sudo apt-get install sqlcmd + +# Windows +# Download from: https://learn.microsoft.com/en-us/sql/tools/sqlcmd/sqlcmd-utility +``` + +#### Using Python (Test with main.py) + +```bash +# This should connect and list databases +python main.py +``` + +**Expected output:** +``` +...Connection logs... +Database ID: 1, Name: master +Database ID: 2, Name: tempdb +... +Connection closed successfully. +``` + +**If this fails:** See troubleshooting section below. + +### 6.3 Troubleshoot SQL Server Connectivity + +#### Common Issues and Solutions + +| Issue | Symptoms | Solution | +|-------|----------|----------| +| **SQL Server not running** | "Cannot open server", "No connection could be made" | Start SQL Server (see 6.1) | +| **Wrong credentials** | "Login failed for user" | Check username/password in connection string | +| **Port not accessible** | "TCP Provider: No connection could be made" | Check firewall, verify port 1433 is open | +| **SSL/TLS errors** | "SSL Provider: The certificate chain was issued by an authority" | Add `TrustServerCertificate=yes` to connection string (dev only) | +| **ODBC driver missing** | "Driver not found" | Install ODBC Driver 18 (see Step 4) | +| **Network timeout** | Connection times out | Check server address, network connectivity | + +#### Verify SQL Server Port + +```bash +# Check if port 1433 is listening (macOS/Linux) +lsof -i :1433 + +# Or use netstat +netstat -an | grep 1433 + +# Test port connectivity with telnet +telnet localhost 1433 + +# Or use nc (netcat) +nc -zv localhost 1433 +``` + +**If port 1433 is not listening:** +- SQL Server is not running → Start it +- SQL Server is using a different port → Check configuration +- Firewall is blocking the port → Configure firewall + +#### Check SQL Server Logs + +**Docker:** + +```bash +docker logs mssql-dev --tail 100 +``` + +**Linux:** + +```bash +# View error log +sudo cat /var/opt/mssql/log/errorlog + +# View last 50 lines +sudo tail -50 /var/opt/mssql/log/errorlog + +# Follow logs in real-time +sudo tail -f /var/opt/mssql/log/errorlog +``` + +**Windows:** + +``` +C:\Program Files\Microsoft SQL Server\MSSQL15.MSSQLSERVER\MSSQL\Log\ERRORLOG +``` + +Or use SQL Server Management Studio (SSMS) → Management → SQL Server Logs + +#### Enable SQL Server Network Access (Linux) + +```bash +# Allow SQL Server through firewall +sudo ufw allow 1433/tcp + +# Configure SQL Server to listen on TCP port 1433 +sudo /opt/mssql/bin/mssql-conf set network.tcpport 1433 + +# Enable remote connections +sudo /opt/mssql/bin/mssql-conf set network.tcpenabled true + +# Restart SQL Server +sudo systemctl restart mssql-server +``` + +#### Docker Networking Issues + +```bash +# Check Docker network +docker network inspect bridge + +# Check if container is using the correct port mapping +docker port mssql-dev + +# Recreate container with explicit port mapping +docker rm -f mssql-dev +docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=YourStrongPassword123!" \ + -p 1433:1433 --name mssql-dev \ + -d mcr.microsoft.com/mssql/server:2022-latest +``` + +#### Azure SQL Database Firewall + +```bash +# Get your current IP address +curl -s https://api.ipify.org + +# Add this IP to Azure SQL Database firewall rules: +# 1. Go to Azure Portal +# 2. Navigate to your SQL Server +# 3. Settings → Networking +# 4. Add your IP address to firewall rules +``` + +--- + +## STEP 7: Final Verification Run this comprehensive check: From eebbd506dfef6f857411520da81e92c4f66a0166 Mon Sep 17 00:00:00 2001 From: Gaurav Sharma Date: Fri, 9 Jan 2026 11:34:39 +0000 Subject: [PATCH 20/20] fix: correct connection string format in prompts (remove Driver keyword) - Remove Driver={ODBC Driver 18 for SQL Server} from all connection string examples - Driver is reserved and automatically added by the driver - Update format to use SERVER=, DATABASE=, UID=, PWD= keywords - Add Encrypt=yes parameter for security - Add clarifying notes about Driver being auto-added - Addresses Saurabh's review comment on PR #393 --- .github/prompts/run-tests.prompt.md | 7 +++++-- .github/prompts/setup-dev-env.prompt.md | 6 ++++-- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/.github/prompts/run-tests.prompt.md b/.github/prompts/run-tests.prompt.md index 0e2cd1cd..da8bcfa8 100644 --- a/.github/prompts/run-tests.prompt.md +++ b/.github/prompts/run-tests.prompt.md @@ -80,10 +80,12 @@ if [ -n "$DB_CONNECTION_STRING" ]; then echo "✅ Connection string is set"; els Once the developer provides the details, set it: ```bash -export DB_CONNECTION_STRING="Driver={ODBC Driver 18 for SQL Server};Server=;Database=;UID=;PWD=;TrustServerCertificate=yes" +export DB_CONNECTION_STRING="SERVER=;DATABASE=;UID=;PWD=;Encrypt=yes;TrustServerCertificate=yes" ``` > ⚠️ **SECURITY:** `TrustServerCertificate=yes` is for local development only. Never use in production. +> +> 💡 **Note:** Do NOT include `Driver=` in your connection string. The driver automatically adds the correct ODBC driver. ### Step 4: Verify SQL Server is Running @@ -295,7 +297,8 @@ echo $DB_CONNECTION_STRING # Set it with correct values (LOCAL DEVELOPMENT ONLY) # WARNING: Never commit real credentials. TrustServerCertificate=yes is for local dev only. -export DB_CONNECTION_STRING="Driver={ODBC Driver 18 for SQL Server};Server=localhost;Database=testdb;UID=sa;PWD=YourPassword;TrustServerCertificate=yes" +# Note: Do NOT include Driver= - the driver automatically adds the correct ODBC driver. +export DB_CONNECTION_STRING="SERVER=localhost;DATABASE=testdb;UID=sa;PWD=YourPassword;Encrypt=yes;TrustServerCertificate=yes" ``` ### ❌ "Timeout error" diff --git a/.github/prompts/setup-dev-env.prompt.md b/.github/prompts/setup-dev-env.prompt.md index b1e887e1..95003406 100644 --- a/.github/prompts/setup-dev-env.prompt.md +++ b/.github/prompts/setup-dev-env.prompt.md @@ -272,7 +272,8 @@ python -c "import pybind11; print('pybind11:', pybind11.get_include())" ```bash # Set connection string for tests (LOCAL DEVELOPMENT ONLY) # Replace placeholders with your own values - NEVER commit real credentials! -export DB_CONNECTION_STRING="Driver={ODBC Driver 18 for SQL Server};Server=localhost;Database=testdb;UID=your_user;PWD=your_password;TrustServerCertificate=yes" +# Note: Do NOT include Driver= - the driver automatically adds the correct ODBC driver. +export DB_CONNECTION_STRING="SERVER=localhost;DATABASE=testdb;UID=your_user;PWD=your_password;Encrypt=yes;TrustServerCertificate=yes" # Verify it's set echo $DB_CONNECTION_STRING @@ -281,7 +282,8 @@ echo $DB_CONNECTION_STRING **Windows (LOCAL DEVELOPMENT ONLY):** ```cmd REM Replace placeholders with your own values - NEVER commit real credentials! -set DB_CONNECTION_STRING=Driver={ODBC Driver 18 for SQL Server};Server=localhost;Database=testdb;UID=your_user;PWD=your_password;TrustServerCertificate=yes +REM Note: Do NOT include Driver= - the driver automatically adds the correct ODBC driver. +set DB_CONNECTION_STRING=SERVER=localhost;DATABASE=testdb;UID=your_user;PWD=your_password;Encrypt=yes;TrustServerCertificate=yes ``` > 💡 **Tip:** Add this to your shell profile (`.bashrc`, `.zshrc`) or venv's `activate` script to persist it.