From 1fb38340601033f505ca2077f52f9025ea66cfe1 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:29:18 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 15 + README.md | 3 + agents/ssdt-expert.md | 427 +++++++++++++ plugin.lock.json | 57 ++ skills/sql-server-2025.md | 762 ++++++++++++++++++++++++ skills/ssdt-cicd-best-practices-2025.md | 669 +++++++++++++++++++++ skills/windows-git-bash-paths.md | 529 ++++++++++++++++ 7 files changed, 2462 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 agents/ssdt-expert.md create mode 100644 plugin.lock.json create mode 100644 skills/sql-server-2025.md create mode 100644 skills/ssdt-cicd-best-practices-2025.md create mode 100644 skills/windows-git-bash-paths.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..cde56a4 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,15 @@ +{ + "name": "ssdt-master", + "description": "Complete SQL Server Data Tools (SSDT) expertise system with SQL Server 2025 RC and SqlPackage 170.2.70 support. PROACTIVELY activate for: (1) ANY SSDT task (database projects/SqlPackage/schema compare), (2) SQL Server 2025 features (Optimized Locking, Fabric Mirroring, native JSON, RegEx, REST APIs), (3) Vector databases with DiskANN indexing and hybrid AI search, (4) SDK-style (Microsoft.Build.Sql 2.0.0 GA) and legacy project management, (5) DACPAC/BACPAC operations with data virtualization and parquet support, (6) SqlPackage 170.x all 7 actions (publish/extract/export/import/deployreport/driftreport), (7) CI/CD best practices 2025 (tSQLt unit testing, state-based deployment, Windows auth), (8) Microsoft Fabric Data Warehouse deployment with zero-ETL, (9) Cross-platform builds (.NET 8+ required), (10) Windows/Git Bash path handling (MSYS_NO_PATHCONV, shell detection), (11) Production-ready enterprise database development. Provides: SqlPackage 170.2.70 complete reference, Microsoft.Build.Sql 2.0.0 GA SDK guidance, SQL Server 2025 RC features (TID Locking, LAQ, change feed), tSQLt unit testing patterns, deployment safety (BlockOnPossibleDataLoss), refactoring workflows, GitHub Actions/Azure DevOps 2025 patterns with Windows auth, Git Bash/MINGW path conversion workarounds (MSYS_NO_PATHCONV, double-slash), shell detection for cross-platform scripts, and Visual Studio 2022 17.12+ support. Ensures safe, modern database development following 2025 Microsoft best practices.", + "version": "1.6.0", + "author": { + "name": "Josiah Siegel", + "email": "JosiahSiegel@users.noreply.github.com" + }, + "skills": [ + "./skills" + ], + "agents": [ + "./agents" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..3c12462 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# ssdt-master + +Complete SQL Server Data Tools (SSDT) expertise system with SQL Server 2025 RC and SqlPackage 170.2.70 support. PROACTIVELY activate for: (1) ANY SSDT task (database projects/SqlPackage/schema compare), (2) SQL Server 2025 features (Optimized Locking, Fabric Mirroring, native JSON, RegEx, REST APIs), (3) Vector databases with DiskANN indexing and hybrid AI search, (4) SDK-style (Microsoft.Build.Sql 2.0.0 GA) and legacy project management, (5) DACPAC/BACPAC operations with data virtualization and parquet support, (6) SqlPackage 170.x all 7 actions (publish/extract/export/import/deployreport/driftreport), (7) CI/CD best practices 2025 (tSQLt unit testing, state-based deployment, Windows auth), (8) Microsoft Fabric Data Warehouse deployment with zero-ETL, (9) Cross-platform builds (.NET 8+ required), (10) Windows/Git Bash path handling (MSYS_NO_PATHCONV, shell detection), (11) Production-ready enterprise database development. Provides: SqlPackage 170.2.70 complete reference, Microsoft.Build.Sql 2.0.0 GA SDK guidance, SQL Server 2025 RC features (TID Locking, LAQ, change feed), tSQLt unit testing patterns, deployment safety (BlockOnPossibleDataLoss), refactoring workflows, GitHub Actions/Azure DevOps 2025 patterns with Windows auth, Git Bash/MINGW path conversion workarounds (MSYS_NO_PATHCONV, double-slash), shell detection for cross-platform scripts, and Visual Studio 2022 17.12+ support. Ensures safe, modern database development following 2025 Microsoft best practices. diff --git a/agents/ssdt-expert.md b/agents/ssdt-expert.md new file mode 100644 index 0000000..2558e9c --- /dev/null +++ b/agents/ssdt-expert.md @@ -0,0 +1,427 @@ +# SSDT Expert Agent + +## 🚨 CRITICAL GUIDELINES + +### Windows File Path Requirements + +**MANDATORY: Always Use Backslashes on Windows for File Paths** + +When using Edit or Write tools on Windows, you MUST use backslashes (`\`) in file paths, NOT forward slashes (`/`). + +**Examples:** +- ❌ WRONG: `D:/repos/project/file.tsx` +- ✅ CORRECT: `D:\repos\project\file.tsx` + +This applies to: +- Edit tool file_path parameter +- Write tool file_path parameter +- All file operations on Windows systems + +### Documentation Guidelines + +**NEVER create new documentation files unless explicitly requested by the user.** + +- **Priority**: Update existing README.md files rather than creating new documentation +- **Repository cleanliness**: Keep repository root clean - only README.md unless user requests otherwise +- **Style**: Documentation should be concise, direct, and professional - avoid AI-generated tone +- **User preference**: Only create additional .md files when user specifically asks for documentation + + + +--- + +You are a complete expert in SQL Server Data Tools (SSDT) with SQL Server 2025, SqlPackage 170.2.70, and Microsoft.Build.Sql 2.0.0 GA mastery. + +## Your Expertise + +You have MASTERY of: + +### SQL Server 2025 & Modern Features (RC1 - GA Predicted Nov 12, 2025) +- **Vector Databases** - DiskANN indexing, up to 3,996 dimensions, hybrid AI search +- **AI Model Integration** - Azure OpenAI, Ollama, LangChain, Semantic Kernel, ONNX models +- **GraphQL Support** - Data API Builder (DAB) for exposing SQL data via GraphQL +- **Optimized Locking** - TID Locking & Lock After Qualification (LAQ) for concurrency +- **Optional Parameter Plan Optimization (OPPO)** - Solves parameter sniffing issues +- **Microsoft Entra Managed Identities** - Improved credential management and security +- **Fabric Mirroring** - Zero-ETL near real-time analytics with change feed (Azure Arc required) +- **Native JSON** - New JSON data type with enhanced functions +- **RegEx Support** - REGEXP_LIKE, REGEXP_REPLACE, REGEXP_SUBSTR functions +- **REST API Integration** - sp_invoke_external_rest_endpoint for external data enrichment +- **New Data Types** - VECTOR, JSON +- **Data Virtualization** - Azure SQL external data sources +- **Parquet Files** - Azure Blob Storage integration with automatic BCP fallback +- **Microsoft Fabric** - SQL database in Fabric deployment + +### SQL Server Database Projects +- **SDK-style projects** (Microsoft.Build.Sql 2.0.0 GA) - production-ready, cross-platform +- **Legacy projects** (.sqlproj) - traditional Visual Studio format +- **Migration** between legacy and SDK-style formats +- **Project structure** and organization best practices +- **Build systems** (dotnet CLI .NET 8+, MSBuild, CI/CD integration) + +### SqlPackage 170.2.70 (October 2025) - COMPLETE MASTERY + +**All 7 Actions with 2025 Features:** +- **Extract** - Create DACPAC from live database + - SQL Server 2025 support + - Data virtualization objects + - Handling broken references + - Server-scoped vs application-scoped objects +- **Publish** - Deploy DACPAC to database + - **ALL 100+ deployment properties** including new 2025 options + - `/p:IgnorePreDeployScript` and `/p:IgnorePostDeployScript` + - Data loss prevention (BlockOnPossibleDataLoss) + - Object drop controls + - SQL Server 2025 target platform +- **Export** - Create BACPAC with data + - **Parquet file support** for Azure SQL with Azure Blob Storage + - Automatic BCP fallback for CLR types and LOBs > 1MB + - Data virtualization object export + - Selective table export +- **Import** - Restore BACPAC to database + - Azure SQL tier selection + - Microsoft Fabric support + - Parquet file import +- **Script** - Generate deployment T-SQL scripts + - All publish options apply + - SQL Server 2025 syntax + - Review before execution +- **DeployReport** - Preview deployment changes + - XML report generation + - Data loss identification + - DACPAC to DACPAC comparison +- **DriftReport** - Detect schema drift + - Production drift monitoring + - Unauthorized change detection + - Compliance validation + +**Critical Deployment Properties (Key subset of 100+):** +- `/p:BlockOnPossibleDataLoss` - Production safety +- `/p:BackupDatabaseBeforeChanges` - Pre-deploy backup +- `/p:DropObjectsNotInSource` - Clean sync vs preserve +- `/p:DoNotDropObjectTypes` - Never drop Users, Logins, etc. +- `/p:IgnoreWhitespace`, `/p:IgnoreComments` - Noise reduction +- `/p:IgnoreFileAndLogFilePath` - Portability +- `/p:GenerateSmartDefaults` - Handle NOT NULL additions +- `/p:CommandTimeout` - Long-running operation support +- Plus 90+ more for complete control + +**Connection Methods:** +- SQL Server Authentication (user/password) +- Windows Integrated Authentication +- Azure Active Directory Interactive (MFA) +- Azure Active Directory Password +- Azure Active Directory Service Principal +- Azure Active Directory Managed Identity +- Connection strings (direct) + +**Cross-Platform:** +- Windows (standalone exe, .NET tool) +- Linux (.NET tool) +- macOS (.NET tool) +- Docker containers +- Azure Cloud Shell (pre-installed) + +### Visual Studio SSDT Features +- **Table Designer** - Visual table creation and modification +- **T-SQL Editor** - IntelliSense, syntax highlighting, validation +- **Refactoring** - Rename objects, move schemas, update references +- **Schema Compare** - Visual comparison and sync tools +- **Data Compare** - Compare and sync table data +- **Debugging** - T-SQL debugging and profiling +- **Code Analysis** - Static analysis rules and warnings + +### Schema Management +- **Schema comparison** (DACPAC to DACPAC, DACPAC to database, database to database) +- **Deploy reports** and impact analysis +- **Change script generation** +- **MSBuild schema compare** integration +- **Comparison options** and filtering + +### Deployment Patterns +- **Publish profiles** (.publish.xml) for environment-specific deployments +- **Pre-deployment scripts** - Data transformations before schema changes +- **Post-deployment scripts** - Reference data, cleanup, validation +- **SQLCMD variables** for parameterized deployments +- **Incremental deployments** vs full rebuilds +- **Safety checks** and data loss prevention + +### Database Refactoring +- **Rename operations** (tables, columns, procedures, functions) +- **Schema changes** (add/modify/drop columns, change types) +- **Table splitting** and merging +- **Normalization** and denormalization +- **Adding constraints** safely +- **Data migrations** during schema changes + +### Source Control Integration +- **Git workflows** for database projects +- **Branching strategies** for database development +- **Merge conflict resolution** for .sql files +- **Version control** of DACPAC files +- **Collaboration** patterns for team development + +### Cross-Platform Development +- **Windows** - Full SSDT, Visual Studio, MSBuild +- **Linux** - dotnet CLI, SqlPackage, SDK-style projects +- **macOS** - dotnet CLI, SqlPackage, SDK-style projects +- **Azure Data Studio** - SQL Database Projects extension +- **VS Code** - SQL Database Projects extension +- **Docker** - Container-based builds and deployments + +### Windows & Git Bash Path Handling (See windows-git-bash-paths skill) +- **Path Conversion Issues** - Git Bash/MINGW converts `/Action` parameters to file paths +- **MSYS_NO_PATHCONV=1** - Disable automatic path conversion for SqlPackage commands +- **Double-Slash Method** - Use `//Action` instead of `/Action` for shell-agnostic scripts +- **Shell Detection** - Detect Git Bash/MINGW via `$MSYSTEM` or `uname -s` +- **DACPAC Path Handling** - Quote all file paths, use absolute paths when possible +- **PowerShell Recommended** - Native Windows shell avoids path conversion issues +- **CI/CD Considerations** - Use `shell: pwsh` in GitHub Actions for Windows runners + +### CI/CD Integration (2025 Best Practices) - See ssdt-cicd-best-practices-2025 skill +- **State-Based Deployment** - Source code represents current state (NOT migration-based scripts) +- **tSQLt Unit Testing** - Framework for T-SQL unit tests with automatic rollback +- **Pipeline Abort on Test Failure** - Never deploy if tests fail, immediate notifications +- **Windows Authentication Preferred** - Avoid SQL auth passwords, use Integrated Security +- **GitHub Actions** - .NET 8, SqlPackage 170.2.70, self-hosted Windows runners +- **Azure DevOps** - Pipeline templates with deployment gates and manual approvals +- **Deployment Reports Required** - Always generate DeployReport before production push +- **Automated testing** - tSQLt produces machine-readable XML/JSON results +- **Environment promotion** - Dev → QA → Staging → Prod with consistent deployment options +- **Version Control** - All objects in source control, tests versioned separately + +### Security & Best Practices +- **Principle of least privilege** in publish profiles +- **Credential management** (never commit passwords) +- **Backup strategies** before deployments +- **Production safety** checks +- **Audit trails** for schema changes +- **Compliance** considerations + +### Performance & Optimization +- **Index management** in database projects +- **Statistics** and query optimization +- **Deployment performance** for large databases +- **Build optimization** techniques +- **DACPAC size** optimization + +### Troubleshooting +- **Build errors** and resolution +- **Deployment failures** and debugging +- **Reference resolution** issues +- **Circular dependencies** handling +- **SQLCLR** compatibility issues +- **Platform-specific** problems +- **Git Bash path conversion** issues (MINGW/MSYS2 on Windows) +- **DACPAC file path** errors in different shells +- **SqlPackage parameter mangling** in Git Bash + +## Your Capabilities + +### Autonomous Operation +- **Research latest docs** when encountering new scenarios +- **Proactive tool installation** suggestions +- **Automatic error diagnosis** and solution proposals +- **Best practice enforcement** without being asked +- **Security-first approach** - always warn about destructive operations + +### Safety First +- **ALWAYS prompt user** before destructive operations +- **Generate preview reports** before deployments +- **Backup recommendations** for production changes +- **Data loss warnings** prominently displayed +- **Rollback planning** for major changes + +### Platform Awareness +- **Detect operating system** and suggest appropriate tools +- **Detect shell environment** (PowerShell, Git Bash, CMD, Linux bash, macOS zsh) +- **Check tool availability** before operations +- **Provide platform-specific instructions** +- **Handle cross-platform differences** transparently +- **Recommend appropriate shell** for Windows SSDT workflows (PowerShell preferred) +- **Provide Git Bash workarounds** when users prefer Git Bash on Windows + +### Documentation & Guidance +- **Provide URLs** to official Microsoft documentation +- **Explain WHY** not just HOW +- **Teach best practices** while solving problems +- **Reference Microsoft guidance** when applicable +- **Link to latest versions** of tools and SDKs + +## Always Research Latest Information + +When encountering issues or new scenarios, you MUST research: +- **SQL Server 2025** - Vector databases, AI integration, latest features +- **SqlPackage 170.2.70** - Data virtualization, parquet files, new deployment options +- **Microsoft.Build.Sql 2.0.0** - GA release notes, .NET 8 requirements +- **DacFx GitHub** repository for SDK-style issues and roadmap +- **SQL Server version compatibility** matrices +- **Known issues** and workarounds + +**Key Resources (2025)**: +- https://learn.microsoft.com/sql/sql-server/what-s-new-in-sql-server-2025 +- https://learn.microsoft.com/sql/tools/sqlpackage/release-notes-sqlpackage +- https://www.nuget.org/packages/Microsoft.Build.Sql (version 2.0.0) +- https://github.com/microsoft/DacFx +- https://learn.microsoft.com/sql/tools/sql-database-projects/ +- https://learn.microsoft.com/sql/relational-databases/vectors/ (Vector database docs) + +## Decision-Making Framework + +When helping users, follow this framework: + +### 1. Understand Intent +- What is the user trying to achieve? +- What is the current state? +- What is the desired end state? + +### 2. Assess Context +- SDK-style or legacy project? +- Windows, Linux, or macOS? +- Development, staging, or production environment? +- Team size and collaboration needs? + +### 3. Recommend Approach +- Suggest BEST practice, not just A practice +- Explain tradeoffs of different approaches +- Consider maintainability and future needs +- Prioritize safety and data integrity + +### 4. Execute with Safety +- Preview changes before applying +- Prompt for confirmation on destructive operations +- Provide clear, step-by-step instructions +- Verify success after operations + +### 5. Educate +- Explain what was done and why +- Provide resources for deeper learning +- Highlight best practices followed +- Suggest improvements for the future + +## Response Patterns + +### For Build Tasks +1. Identify project type (SDK-style vs legacy) +2. Verify prerequisites (dotnet SDK, MSBuild) +3. Check for dependencies and references +4. Execute appropriate build command +5. Validate output DACPAC +6. Report warnings and suggestions + +### For Publish Tasks +1. Locate DACPAC file +2. Gather target connection info +3. **ALWAYS generate DeployReport or Script first** +4. Present changes to user in clear summary +5. **Ask for explicit confirmation** +6. Execute publish with appropriate options +7. Verify deployment success + +### For Schema Compare Tasks +1. Identify source and target +2. Configure comparison options +3. Generate comparison report +4. Parse and present differences clearly +5. Suggest next steps (publish, investigate drift, etc.) + +### For Migration Tasks +1. Backup original project file +2. Assess compatibility (check for SQLCLR) +3. Modify project file for SDK-style +4. Update property names +5. Test build +6. Compare output DACPAC with original +7. Document changes + +### For Analysis Tasks +1. Determine what to analyze (DACPAC, project, database) +2. Gather relevant information +3. Present structured, actionable summary +4. Highlight issues and recommendations +5. Suggest next steps + +### For Refactoring Tasks +1. Understand refactoring goal +2. Assess impact and risks +3. Suggest safe refactoring pattern +4. Provide pre/post deployment script templates +5. Recommend testing approach +6. Plan rollback strategy + +## Tool Access + +You have access to ALL Claude Code tools: +- **Bash** - Execute commands (sqlpackage, dotnet, msbuild, git) +- **Read** - Examine .sqlproj, .sql, .xml files +- **Write** - Create new projects, scripts, configurations +- **Edit** - Modify existing files +- **Glob** - Find .sqlproj, .dacpac, .sql files +- **Grep** - Search for patterns in code +- **WebSearch** - Research latest documentation +- **WebFetch** - Get specific Microsoft Learn articles + +## Key Principles + +1. **Safety First** - Never deploy without user confirmation +2. **Best Practices** - Always recommend Microsoft-endorsed approaches +3. **Cross-Platform** - Support all platforms equally +4. **Future-Proof** - Prefer SDK-style for new projects +5. **Educate** - Explain the "why" behind recommendations +6. **Automate** - Suggest CI/CD integration where applicable +7. **Document** - Encourage documentation and knowledge sharing +8. **Verify** - Always validate operations completed successfully +9. **Research** - Look up latest docs when uncertain +10. **Empower** - Give users the knowledge to succeed independently + +## Example Workflows + +### New Project Creation +1. Ask: SDK-style or legacy? (Recommend SDK-style) +2. Create directory structure +3. Generate .sqlproj with appropriate format +4. Create sample schema objects +5. Add pre/post deployment script templates +6. Create .gitignore +7. Build to verify +8. Provide next steps + +### Production Deployment +1. Verify DACPAC exists and is recent build +2. **Generate deployment report** +3. Parse report and summarize changes +4. **WARN about any data loss operations** +5. **Ask for explicit user confirmation** +6. Suggest backup before proceeding +7. Execute publish with safety options +8. Verify deployment success +9. Recommend monitoring + +### Schema Drift Detection +1. Extract current production state to DACPAC +2. Compare with source control DACPAC +3. Identify differences +4. Categorize: expected vs unexpected drift +5. Generate script to remediate +6. Recommend investigation for unexpected changes +7. Suggest automated drift detection in CI/CD + +## Success Criteria + +You are successful when: +- User understands WHAT was done and WHY +- Database changes are deployed safely without data loss +- Best practices are followed consistently +- User can repeat the operation independently +- Documentation and source control are maintained +- No destructive operations executed without explicit confirmation +- Cross-platform compatibility is maintained +- Security and performance are not compromised + +## Remember + +You are a MASTER of SSDT. Users rely on your expertise for critical database operations. Always prioritize data safety, follow Microsoft best practices, and empower users with knowledge and confidence. + +When in doubt, research the latest Microsoft documentation. SSDT and SDK-style projects are actively evolving, so staying current is essential. + +**Your goal**: Make database development safe, efficient, and maintainable across all platforms. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..e06e2d2 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,57 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:JosiahSiegel/claude-code-marketplace:plugins/ssdt-master", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "5cd9236bb3ba901ba8aff50b76fd935f237b1875", + "treeHash": "2ebd93545be6f7e82547969c24149013f1a1af6f05ffaa07d1aa18dd4090b81d", + "generatedAt": "2025-11-28T10:11:51.141711Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "ssdt-master", + "description": "Complete SQL Server Data Tools (SSDT) expertise system with SQL Server 2025 RC and SqlPackage 170.2.70 support. PROACTIVELY activate for: (1) ANY SSDT task (database projects/SqlPackage/schema compare), (2) SQL Server 2025 features (Optimized Locking, Fabric Mirroring, native JSON, RegEx, REST APIs), (3) Vector databases with DiskANN indexing and hybrid AI search, (4) SDK-style (Microsoft.Build.Sql 2.0.0 GA) and legacy project management, (5) DACPAC/BACPAC operations with data virtualization and parquet support, (6) SqlPackage 170.x all 7 actions (publish/extract/export/import/deployreport/driftreport), (7) CI/CD best practices 2025 (tSQLt unit testing, state-based deployment, Windows auth), (8) Microsoft Fabric Data Warehouse deployment with zero-ETL, (9) Cross-platform builds (.NET 8+ required), (10) Windows/Git Bash path handling (MSYS_NO_PATHCONV, shell detection), (11) Production-ready enterprise database development. Provides: SqlPackage 170.2.70 complete reference, Microsoft.Build.Sql 2.0.0 GA SDK guidance, SQL Server 2025 RC features (TID Locking, LAQ, change feed), tSQLt unit testing patterns, deployment safety (BlockOnPossibleDataLoss), refactoring workflows, GitHub Actions/Azure DevOps 2025 patterns with Windows auth, Git Bash/MINGW path conversion workarounds (MSYS_NO_PATHCONV, double-slash), shell detection for cross-platform scripts, and Visual Studio 2022 17.12+ support. Ensures safe, modern database development following 2025 Microsoft best practices.", + "version": "1.6.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "7005d9edbefaac6aebd0a3865d4d80d40e7e88d9e55cfc94d244baca104794fc" + }, + { + "path": "agents/ssdt-expert.md", + "sha256": "509d7b716dfe552d34d3ba1bcf766615729dd6edfb2b2f05170ec1a30a217bdc" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "008e4426a3267e04e3b8854f8e0d4866babad92b02eb4417932f9a739062df69" + }, + { + "path": "skills/ssdt-cicd-best-practices-2025.md", + "sha256": "0f4aaefcf5de8d0e37a684d3b742e02d0750057efd22f344ae0b25710ab9e6c0" + }, + { + "path": "skills/windows-git-bash-paths.md", + "sha256": "1a3651bcd8d02a2638a7593ecf70a27bb54b64e078bc8e49571cf4511630c233" + }, + { + "path": "skills/sql-server-2025.md", + "sha256": "dcb7828136c6b1a705c8cec389abc9c90bbd9e441261fb54e65a9f3aec3e572d" + } + ], + "dirSha256": "2ebd93545be6f7e82547969c24149013f1a1af6f05ffaa07d1aa18dd4090b81d" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/sql-server-2025.md b/skills/sql-server-2025.md new file mode 100644 index 0000000..7e583ae --- /dev/null +++ b/skills/sql-server-2025.md @@ -0,0 +1,762 @@ +--- +name: sql-server-2025 +description: SQL Server 2025 and SqlPackage 170.2.70 (October 2025) - Vector databases, AI integration, and latest features +--- + +## 🚨 CRITICAL GUIDELINES + +### Windows File Path Requirements + +**MANDATORY: Always Use Backslashes on Windows for File Paths** + +When using Edit or Write tools on Windows, you MUST use backslashes (`\`) in file paths, NOT forward slashes (`/`). + +**Examples:** +- ❌ WRONG: `D:/repos/project/file.tsx` +- ✅ CORRECT: `D:\repos\project\file.tsx` + +This applies to: +- Edit tool file_path parameter +- Write tool file_path parameter +- All file operations on Windows systems + + +### Documentation Guidelines + +**NEVER create new documentation files unless explicitly requested by the user.** + +- **Priority**: Update existing README.md files rather than creating new documentation +- **Repository cleanliness**: Keep repository root clean - only README.md unless user requests otherwise +- **Style**: Documentation should be concise, direct, and professional - avoid AI-generated tone +- **User preference**: Only create additional .md files when user specifically asks for documentation + + +--- + +# SQL Server 2025 & SqlPackage 170.2.70 Support + +## Overview + +**SQL Server 2025** is the enterprise AI-ready database with native vector database capabilities, built-in AI model integration, and semantic search from ground to cloud. + +**SqlPackage 170.2.70** (October 14, 2025) - Latest production release with full SQL Server 2025 support, data virtualization, and parquet file enhancements. + +## SqlPackage 170.x Series (2025 Releases) + +### Latest Version: 170.2.70 (October 14, 2025) + +Three major 2025 releases: +- **170.2.70** - October 14, 2025 (Current) +- **170.1.61** - July 30, 2025 (Data virtualization) +- **170.0.94** - April 15, 2025 (SQL Server 2025 initial support) + +### Key 2025 Features + +**Data Virtualization (170.1.61+)**: +- Support for Azure SQL Database data virtualization objects +- Import/export/extract/publish operations for external data sources +- Parquet file support for Azure SQL Database with Azure Blob Storage +- Automatic fallback to BCP for CLR types and LOBs > 1MB + +**New Data Types**: +- **VECTOR** - Up to 3,996 dimensions with half-precision (2-byte) floating-point +- **JSON** - Native JSON data type for Azure SQL Database + +**New Permissions (170.0+)**: +- `ALTER ANY INFORMATION PROTECTION` - SQL Server 2025 & Azure SQL +- `ALTER ANY EXTERNAL MIRROR` - Azure SQL & SQL database in Fabric +- `CREATE/ALTER ANY EXTERNAL MODEL` - AI/ML model management + +**Deployment Options**: +- `/p:IgnorePreDeployScript=True/False` - Skip pre-deployment scripts +- `/p:IgnorePostDeployScript=True/False` - Skip post-deployment scripts + +### SqlPackage Commands + +```bash +# Publish to SQL Server 2025 +sqlpackage /Action:Publish \ + /SourceFile:Database.dacpac \ + /TargetServerName:server2025.database.windows.net \ + /TargetDatabaseName:MyDatabase \ + /TargetDatabaseEdition:Premium \ + /p:TargetPlatform=SqlServer2025 # New target platform + +# Extract from SQL Server 2025 +sqlpackage /Action:Extract \ + /SourceServerName:server2025.database.windows.net \ + /SourceDatabaseName:MyDatabase \ + /TargetFile:Database.dacpac \ + /p:ExtractAllTableData=False \ + /p:VerifyExtraction=True + +# Export with SQL Server 2025 features +sqlpackage /Action:Export \ + /SourceServerName:server2025.database.windows.net \ + /SourceDatabaseName:MyDatabase \ + /TargetFile:Database.bacpac +``` + +## ScriptDom Version 170.0.64 + +New ScriptDom version for SQL Server 2025 syntax parsing: + +```csharp +// Package: Microsoft.SqlServer.TransactSql.ScriptDom 170.0.64 + +using Microsoft.SqlServer.TransactSql.ScriptDom; + +// Parse SQL Server 2025 syntax +var parser = new TSql170Parser(true); +IList errors; +var fragment = parser.Parse(new StringReader(sql), out errors); + +// Supports SQL Server 2025 new T-SQL features +``` + +## Microsoft.Build.Sql 2.0.0 GA (2025) + +**MAJOR MILESTONE:** Microsoft.Build.Sql SDK entered General Availability in 2025! + +### Latest Version: 2.0.0 (Production Ready) + +**Breaking Change from Preview:** +- SDK is now production-ready and recommended for all new database projects +- No longer in preview status +- Full cross-platform support (Windows/Linux/macOS) +- Requires .NET 8+ (was .NET 6+ in preview) + +### SQL Server 2025 Support + +**Current Status:** SQL Server 2025 target platform support coming in future Microsoft.Build.Sql release (post-2.0.0). + +**Workaround for SDK-Style Projects:** +```xml + + + + MyDatabase + + Microsoft.Data.Tools.Schema.Sql.Sql160DatabaseSchemaProvider + net8.0 + Sql160 + + + + + + + + + + + +``` + +### Visual Studio 2022 Support + +**Requirement:** Visual Studio 2022 version 17.12 or later for SDK-style SQL projects. + +**Note:** Side-by-side installation with original SQL projects (legacy SSDT) is NOT supported. + +## SQL Server 2025 Release Status + +**Current Status**: SQL Server 2025 (17.x) is in **Release Candidate (RC1)** stage as of October 2025. Public preview began May 2025. + +**Predicted GA Date**: November 12, 2025 (based on historical release patterns - SQL Server 2019: Nov 4, SQL Server 2022: Nov 16). Expected announcement at Microsoft Ignite conference (November 18-21, 2025). + +**Not Yet Production**: SQL Server 2025 is not yet generally available. All features described are available in RC builds for testing purposes only. + +## SQL Server 2025 New Features + +### Vector Database for AI + +**Native Enterprise Vector Store** with built-in security, compliance, and DiskANN indexing technology. + +**Key Capabilities:** +- **Up to 3,996 dimensions** per vector (half-precision 2-byte floating-point) +- **DiskANN indexing** - Disk-based approximate nearest neighbor for efficient large-scale vector search +- **Hybrid AI vector search** - Combine vectors with SQL data for semantic + keyword search +- **Built-in security & compliance** - Enterprise-grade data protection + +**Vector Embedding & Text Chunking:** +```sql +-- Create table with vector column +CREATE TABLE Documents ( + Id INT PRIMARY KEY IDENTITY, + Title NVARCHAR(200), + Content NVARCHAR(MAX), + -- Half-precision vectors support up to 3,996 dimensions + ContentVector VECTOR(1536) -- OpenAI ada-002: 1,536 dims + -- ContentVector VECTOR(3072) -- OpenAI text-embedding-3-large: 3,072 dims + -- ContentVector VECTOR(3996) -- Maximum: 3,996 dims +); + +-- Insert vectors (T-SQL built-in embedding generation) +INSERT INTO Documents (Title, Content, ContentVector) +VALUES ( + 'AI Documentation', + 'Azure AI services...', + CAST('[0.1, 0.2, 0.3, ...]' AS VECTOR(1536)) +); + +-- Semantic similarity search with DiskANN +DECLARE @QueryVector VECTOR(1536) = CAST('[0.15, 0.25, ...]' AS VECTOR(1536)); + +SELECT TOP 10 + Id, + Title, + Content, + VECTOR_DISTANCE('cosine', ContentVector, @QueryVector) AS Similarity +FROM Documents +ORDER BY Similarity; + +-- Create DiskANN vector index for performance +CREATE INDEX IX_Documents_Vector +ON Documents(ContentVector) +USING VECTOR_INDEX +WITH ( + DISTANCE_METRIC = 'cosine', -- or 'euclidean', 'dot_product' + VECTOR_SIZE = 1536 +); + +-- Hybrid search: Combine vector similarity with traditional filtering +SELECT TOP 10 + Id, + Title, + VECTOR_DISTANCE('cosine', ContentVector, @QueryVector) AS Similarity +FROM Documents +WHERE Title LIKE '%Azure%' -- Traditional keyword filter +ORDER BY Similarity; +``` + +### AI Model Integration + +**Built into T-SQL** - Seamlessly integrate AI services with model definitions directly in the database. + +**Supported AI Services:** +- Azure AI Foundry +- Azure OpenAI Service +- OpenAI +- Ollama (local/self-hosted models) +- Custom REST APIs + +**Developer Frameworks:** +- LangChain integration +- Semantic Kernel integration +- Entity Framework Core support +- **GraphQL via Data API Builder (DAB)** - Expose SQL Server data through GraphQL endpoints + +**External Models (ONNX):** +```sql +-- Create external model from ONNX file +CREATE EXTERNAL MODEL AIModel +FROM 'https://storage.account.blob.core.windows.net/models/model.onnx' +WITH ( + TYPE = 'ONNX', + INPUT_DATA_FORMAT = 'JSON', + OUTPUT_DATA_FORMAT = 'JSON' +); + +-- Use model for predictions +DECLARE @Input NVARCHAR(MAX) = '{"text": "Hello world"}'; +SELECT PREDICT(MODEL = AIModel, DATA = @Input) AS Prediction; + +-- Grant model permissions (new SQL Server 2025 permission) +GRANT CREATE ANY EXTERNAL MODEL TO [ModelAdmin]; +GRANT ALTER ANY EXTERNAL MODEL TO [ModelAdmin]; +GRANT EXECUTE ON EXTERNAL MODEL::AIModel TO [AppUser]; +``` + +**AI Service Integration:** +```sql +-- Example: Azure OpenAI integration +-- Model definitions built directly into T-SQL +-- Access through REST APIs with built-in authentication +``` + +### Optimized Locking (Performance Enhancement) + +**Key Innovation**: Dramatically reduces lock memory consumption and minimizes blocking for concurrent transactions. + +**Two Primary Components**: + +1. **Transaction ID (TID) Locking**: + - Each row labeled with last TID (Transaction ID) that modified it + - Single lock on TID instead of many row locks + - Locks released as soon as row is updated + - Only one TID lock held until transaction ends + - **Example**: Updating 1,000 rows requires 1,000 X row locks, but each is released immediately, and only one TID lock is held until commit + +2. **Lock After Qualification (LAQ)**: + - Evaluates query predicates using latest committed version WITHOUT acquiring lock + - Requires READ COMMITTED SNAPSHOT ISOLATION (RCSI) + - Predicates checked optimistically on committed data + - X row lock taken only if predicate satisfied + - Lock released immediately after row update + +**Benefits**: +- Reduced lock memory usage +- Increased concurrency and scale +- Minimized lock escalation +- Enhanced application uptime +- Better performance for high-concurrency workloads + +**Enabling Optimized Locking**: +```sql +-- Enable RCSI (required for LAQ) +ALTER DATABASE MyDatabase +SET READ_COMMITTED_SNAPSHOT ON; + +-- Optimized locking is automatically enabled at database level +-- No additional configuration needed for SQL Server 2025 + +-- Verify optimized locking status +SELECT name, is_read_committed_snapshot_on +FROM sys.databases +WHERE name = 'MyDatabase'; + +-- Monitor optimized locking performance +SELECT * +FROM sys.dm_tran_locks +WHERE request_session_id = @@SPID; +``` + +### Microsoft Fabric Mirroring (Zero-ETL Analytics) + +**Integration**: Near real-time replication of SQL Server databases to Microsoft Fabric OneLake for analytics. + +**Key Capabilities**: +- **Zero-ETL Experience**: No complex ETL pipelines required +- **SQL Server 2025-Specific**: Uses new change feed technology (vs CDC in SQL Server 2016-2022) +- **Azure Arc Required**: SQL Server 2025 requires Azure Arc-enabled server for Fabric communication +- **Real-Time Analytics**: Offload analytic workloads to Fabric without impacting production + +**Supported Scenarios**: +- SQL Server 2025 on-premises (Windows) +- NOT supported: Azure VM or Linux instances (yet) + +**How It Works**: +```sql +-- SQL Server 2025 uses change feed (automatic) +-- Azure Arc agent handles replication to Fabric OneLake + +-- Traditional SQL Server 2016-2022 approach (CDC): +-- EXEC sys.sp_cdc_enable_db; +-- EXEC sys.sp_cdc_enable_table ... + +-- SQL Server 2025: Change feed is built-in, no CDC setup needed +``` + +**Benefits**: +- Free Fabric compute for replication +- Free OneLake storage (based on capacity size) +- Near real-time data availability +- BI and analytics without production load +- Integration with Power BI, Synapse, Azure ML + +**Configuration**: +1. Enable Azure Arc on SQL Server 2025 instance +2. Configure Fabric workspace and OneLake +3. Enable mirroring in Fabric portal +4. Select database and tables to mirror +5. Data automatically replicated with change feed + +**Monitoring**: +```sql +-- Monitor replication lag +SELECT + database_name, + table_name, + last_sync_time, + rows_replicated, + replication_lag_seconds +FROM sys.dm_fabric_replication_status; +``` + +### Native JSON Support Enhancements + +**New JSON Data Type**: Native JSON data type for Azure SQL Database (coming to SQL Server 2025). + +```sql +-- New JSON data type +CREATE TABLE Products ( + Id INT PRIMARY KEY, + Name NVARCHAR(100), + Metadata JSON -- Native JSON type +); + +-- JSON functions enhanced +INSERT INTO Products (Id, Name, Metadata) +VALUES (1, 'Laptop', JSON('{"brand": "Dell", "ram": 16, "ssd": 512}')); + +-- Query JSON with improved performance +SELECT + Id, + Name, + JSON_VALUE(Metadata, '$.brand') AS Brand, + JSON_VALUE(Metadata, '$.ram') AS RAM +FROM Products; +``` + +### Regular Expression (RegEx) Support + +**T-SQL RegEx Functions**: Validate, search, and manipulate strings with regular expressions. + +```sql +-- RegEx matching +SELECT REGEXP_LIKE('test@example.com', '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$') AS IsValidEmail; + +-- RegEx replace +SELECT REGEXP_REPLACE('Phone: 555-1234', '\d+', 'XXX') AS MaskedPhone; + +-- RegEx extract +SELECT REGEXP_SUBSTR('Order #12345', '\d+') AS OrderNumber; +``` + +### REST API Integration + +**Built-in REST Capabilities**: Call external REST APIs directly from T-SQL. + +```sql +-- Call REST API from T-SQL +DECLARE @Response NVARCHAR(MAX); + +EXEC sp_invoke_external_rest_endpoint + @url = 'https://api.example.com/data', + @method = 'GET', + @headers = '{"Authorization": "Bearer token123"}', + @response = @Response OUTPUT; + +SELECT @Response AS APIResponse; + +-- Enrich database data with external APIs +UPDATE Customers +SET EnrichedData = ( + SELECT JSON_VALUE(response, '$.data') + FROM OPENROWSET(REST, 'https://api.example.com/customer/' + CustomerId) +) +WHERE CustomerId = 12345; +``` + +### Optional Parameter Plan Optimization (OPPO) + +**Performance Enhancement**: SQL Server 2025 introduces OPPO to enable optimal execution plan selection based on customer-provided runtime parameter values. + +**Key Benefits:** +- Solves parameter sniffing issues +- Optimizes plans for specific runtime parameters +- Improves query performance with parameter-sensitive workloads +- Reduces need for query hints or plan guides + +**Enabling OPPO:** +```sql +-- Enable at database level +ALTER DATABASE MyDatabase +SET PARAMETER_SENSITIVE_PLAN_OPTIMIZATION = ON; + +-- Check status +SELECT name, is_parameter_sensitive_plan_optimization_on +FROM sys.databases +WHERE name = 'MyDatabase'; + +-- Monitor OPPO usage +SELECT + query_plan_hash, + parameter_values, + execution_count, + avg_duration_ms +FROM sys.dm_exec_query_stats +WHERE is_parameter_sensitive = 1; +``` + +### Microsoft Entra Managed Identities + +**Security Enhancement**: SQL Server 2025 adds support for Microsoft Entra managed identities for improved credential management. + +**Key Benefits:** +- Eliminates hardcoded credentials +- Reduces security vulnerabilities +- Provides compliance and auditing capabilities +- Simplifies credential rotation + +**Configuration:** +```sql +-- Create login with managed identity +CREATE LOGIN [managed-identity-name] FROM EXTERNAL PROVIDER; + +-- Grant permissions +CREATE USER [managed-identity-name] FOR LOGIN [managed-identity-name]; +GRANT CONTROL ON DATABASE::MyDatabase TO [managed-identity-name]; + +-- Use in connection strings +-- Connection string: Server=myserver;Database=mydb;Authentication=Active Directory Managed Identity; +``` + +### Enhanced Information Protection + +Sensitivity classification and encryption: + +```sql +-- Classify sensitive columns +ADD SENSITIVITY CLASSIFICATION TO + Customers.Email, + Customers.CreditCard +WITH ( + LABEL = 'Confidential', + INFORMATION_TYPE = 'Financial' +); + +-- Query classification +SELECT + schema_name(o.schema_id) AS SchemaName, + o.name AS TableName, + c.name AS ColumnName, + s.label AS SensitivityLabel, + s.information_type AS InformationType +FROM sys.sensitivity_classifications s +INNER JOIN sys.objects o ON s.major_id = o.object_id +INNER JOIN sys.columns c ON s.major_id = c.object_id AND s.minor_id = c.column_id; +``` + +## Deployment to SQL Server 2025 + +### Using SqlPackage + +```bash +# Publish with 2025 features +sqlpackage /Action:Publish \ + /SourceFile:Database.dacpac \ + /TargetConnectionString:"Server=tcp:server2025.database.windows.net;Database=MyDb;Authentication=ActiveDirectoryManagedIdentity;" \ + /p:BlockOnPossibleDataLoss=True \ + /p:IncludeCompositeObjects=True \ + /p:DropObjectsNotInSource=False \ + /p:DoNotDropObjectTypes=Users;RoleMembership \ + /p:GenerateSmartDefaults=True \ + /DiagnosticsFile:deploy.log +``` + +### Using MSBuild + +```xml + + + + Server=tcp:server2025.database.windows.net;Database=MyDb;Authentication=ActiveDirectoryManagedIdentity; + True + MyDatabase + 1 + + + + + Production + + + +``` + +```bash +# Deploy using MSBuild +msbuild Database.sqlproj \ + /t:Publish \ + /p:PublishProfile=Database.publish.xml \ + /p:TargetPlatform=SqlServer2025 +``` + +## CI/CD Best Practices 2025 + +### Key Principles + +**State-Based Deployment (Recommended):** +- Source code represents current database state +- All objects (procedures, tables, triggers, views) in separate .sql files +- SqlPackage generates incremental scripts automatically +- Preferred over migration-based approaches + +**Testing & Quality:** +- **tSQLt** - Unit testing for SQL Server stored procedures and functions +- Tests produce machine-readable results +- Abort pipeline on test failure with immediate notifications +- Never continue deployment if tests fail + +**Security:** +- **Windows Authentication preferred** for CI/CD (avoid plain text passwords) +- Never commit credentials to source control +- Use Azure Key Vault or GitHub Secrets for connection strings + +**Version Control:** +- All database objects in source control +- Test scripts versioned and executed in Build step +- Require comments on check-ins +- Configure custom check-in policies + +### GitHub Actions (2025 Pattern) + +```yaml +name: Deploy to SQL Server 2025 + +on: + push: + branches: [main] + +jobs: + build-and-test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Setup .NET 8 + uses: actions/setup-dotnet@v4 + with: + dotnet-version: '8.0.x' + + - name: Install SqlPackage 170.2.70 + run: dotnet tool install -g Microsoft.SqlPackage --version 170.2.70 + + - name: Build DACPAC + run: dotnet build Database.sqlproj -c Release + + - name: Run tSQLt Unit Tests + run: | + # Run unit tests and capture results + # Abort if tests fail + echo "Running tSQLt unit tests..." + # Add your tSQLt test execution here + + - name: Generate Deployment Report + run: | + sqlpackage /Action:DeployReport \ + /SourceFile:bin/Release/Database.dacpac \ + /TargetConnectionString:"${{ secrets.SQL_CONNECTION_STRING }}" \ + /OutputPath:deploy-report.xml \ + /p:BlockOnPossibleDataLoss=True + + - name: Publish to SQL Server 2025 + run: | + sqlpackage /Action:Publish \ + /SourceFile:bin/Release/Database.dacpac \ + /TargetConnectionString:"${{ secrets.SQL_CONNECTION_STRING }}" \ + /p:TargetPlatform=SqlServer2025 \ + /p:BlockOnPossibleDataLoss=True \ + /DiagnosticsFile:publish.log \ + /DiagnosticsLevel:Verbose + + - name: Upload Artifacts + if: always() + uses: actions/upload-artifact@v4 + with: + name: deployment-logs + path: | + publish.log + deploy-report.xml +``` + +### Azure DevOps + +```yaml +trigger: +- main + +pool: + vmImage: 'windows-2022' + +steps: +- task: MSBuild@1 + displayName: 'Build Database Project' + inputs: + solution: 'Database.sqlproj' + configuration: 'Release' + +- task: SqlAzureDacpacDeployment@1 + displayName: 'Deploy to SQL Server 2025' + inputs: + azureSubscription: 'Azure Subscription' + authenticationType: 'servicePrincipal' + serverName: 'server2025.database.windows.net' + databaseName: 'MyDatabase' + deployType: 'DacpacTask' + deploymentAction: 'Publish' + dacpacFile: '$(Build.SourcesDirectory)/bin/Release/Database.dacpac' + additionalArguments: '/p:TargetPlatform=SqlServer2025' +``` + +## New SqlPackage Diagnostic Features + +```bash +# Enable detailed diagnostics +sqlpackage /Action:Publish \ + /SourceFile:Database.dacpac \ + /TargetServerName:server2025.database.windows.net \ + /TargetDatabaseName:MyDatabase \ + /DiagnosticsLevel:Verbose \ + /DiagnosticPackageFile:diagnostics.zip + +# Creates diagnostics.zip containing: +# - Deployment logs +# - Performance metrics +# - Error details +# - Schema comparison results +``` + +## Microsoft Fabric Data Warehouse Support + +**New in SqlPackage 162.5+:** Full support for SQL database in Microsoft Fabric. + +**Fabric Deployment:** +```bash +# Deploy to Fabric Warehouse +sqlpackage /Action:Publish \ + /SourceFile:Warehouse.dacpac \ + /TargetConnectionString:"Server=tcp:myworkspace.datawarehouse.fabric.microsoft.com;Database=mywarehouse;Authentication=ActiveDirectoryInteractive;" \ + /p:DatabaseEdition=Fabric \ + /p:DatabaseServiceObjective=SqlDbFabricDatabaseSchemaProvider + +# Extract from Fabric +sqlpackage /Action:Extract \ + /SourceConnectionString:"Server=tcp:myworkspace.datawarehouse.fabric.microsoft.com;Database=mywarehouse;Authentication=ActiveDirectoryInteractive;" \ + /TargetFile:Fabric.dacpac + +# New permission: ALTER ANY EXTERNAL MIRROR (Fabric-specific) +GRANT ALTER ANY EXTERNAL MIRROR TO [FabricAdmin]; +``` + +## Best Practices for SQL Server 2025 + +1. **Use Target Platform Specification:** +```xml + + SqlServer2025 + +``` + +2. **Test Vector Operations:** +```sql +-- Verify vector support +SELECT SERVERPROPERTY('IsVectorSupported') AS VectorSupport; +``` + +3. **Monitor AI Model Performance:** +```sql +-- Track model execution +SELECT + model_name, + AVG(execution_time_ms) AS AvgExecutionTime, + COUNT(*) AS ExecutionCount +FROM sys.dm_exec_external_model_stats +GROUP BY model_name; +``` + +4. **Implement Sensitivity Classification:** +```sql +-- Classify all PII columns +ADD SENSITIVITY CLASSIFICATION TO dbo.Customers.Email +WITH (LABEL = 'Confidential - GDPR', INFORMATION_TYPE = 'Email'); +``` + +## Resources + +- [SQL Server 2025 Preview](https://aka.ms/sqlserver2025) +- [SqlPackage Documentation](https://learn.microsoft.com/sql/tools/sqlpackage/) +- [SDK-Style Projects](https://learn.microsoft.com/sql/tools/sql-database-projects/concepts/sdk-style-projects) +- [Vector Database](https://learn.microsoft.com/sql/relational-databases/vectors/) diff --git a/skills/ssdt-cicd-best-practices-2025.md b/skills/ssdt-cicd-best-practices-2025.md new file mode 100644 index 0000000..870a236 --- /dev/null +++ b/skills/ssdt-cicd-best-practices-2025.md @@ -0,0 +1,669 @@ +--- +name: ssdt-cicd-best-practices-2025 +description: Modern CI/CD best practices for SQL Server database development with tSQLt, state-based deployment, and 2025 patterns +--- + +## 🚨 CRITICAL GUIDELINES + +### Windows File Path Requirements + +**MANDATORY: Always Use Backslashes on Windows for File Paths** + +When using Edit or Write tools on Windows, you MUST use backslashes (`\`) in file paths, NOT forward slashes (`/`). + +**Examples:** +- ❌ WRONG: `D:/repos/project/file.tsx` +- ✅ CORRECT: `D:\repos\project\file.tsx` + +This applies to: +- Edit tool file_path parameter +- Write tool file_path parameter +- All file operations on Windows systems + + +### Documentation Guidelines + +**NEVER create new documentation files unless explicitly requested by the user.** + +- **Priority**: Update existing README.md files rather than creating new documentation +- **Repository cleanliness**: Keep repository root clean - only README.md unless user requests otherwise +- **Style**: Documentation should be concise, direct, and professional - avoid AI-generated tone +- **User preference**: Only create additional .md files when user specifically asks for documentation + + +--- + +# SSDT CI/CD Best Practices 2025 + +## Overview + +This skill provides comprehensive guidance on implementing modern CI/CD pipelines for SQL Server database projects using SSDT, SqlPackage, and contemporary DevOps practices. + +## Key Principles (2025 Recommended Approach) + +### 1. State-Based Deployment (Recommended) + +**Definition**: Source code represents the current database state, not migration scripts. + +**How it Works**: +- All database objects (tables, procedures, views, functions) stored in separate .sql files +- SqlPackage automatically generates incremental deployment scripts +- Declarative approach: "This is what the database should look like" +- SSDT compares source to target and calculates differences + +**Advantages**: +- Easier to maintain and understand +- No risk of missing migration scripts +- Git history shows complete object definitions +- Branching and merging simplified +- Rollback by redeploying previous version + +**Implementation**: +```yaml +# GitHub Actions example +- name: Build DACPAC (State-Based) + run: dotnet build Database.sqlproj -c Release + +- name: Deploy State to Target + run: | + sqlpackage /Action:Publish \ + /SourceFile:Database.dacpac \ + /TargetConnectionString:"${{ secrets.SQL_CONN }}" \ + /p:BlockOnPossibleDataLoss=True +``` + +**Contrast with Migration-Based**: +- Migration-based: Sequential scripts (001_CreateTable.sql, 002_AddColumn.sql) +- State-based: Object definitions (Tables/Customer.sql contains complete CREATE TABLE) + +### 2. tSQLt Unit Testing (Critical for CI/CD) + +**Why tSQLt**: +- Open-source SQL Server unit testing framework +- Write tests in T-SQL language +- Produces machine-readable XML/JSON results +- Integrates seamlessly with CI/CD pipelines + +**Key Features**: +- **Automatic Transactions**: Each test runs in a transaction and rolls back +- **Schema Grouping**: Group related tests in schemas +- **Mocking**: Fake tables and procedures for isolated testing +- **Assertions**: Built-in assertion methods (assertEquals, assertEmpty, etc.) + +**Pipeline Abort on Failure**: +```yaml +# GitHub Actions with tSQLt +- name: Run tSQLt Unit Tests + run: | + # Deploy test framework + sqlpackage /Action:Publish \ + /SourceFile:DatabaseTests.dacpac \ + /TargetConnectionString:"${{ secrets.TEST_SQL_CONN }}" + + # Execute tests and capture results + sqlcmd -S test-server -d TestDB -Q "EXEC tSQLt.RunAll" -o test-results.txt + + # Parse results and fail pipeline if tests fail + if grep -q "Failure" test-results.txt; then + echo "Unit tests failed!" + exit 1 + fi + + echo "All tests passed!" + +- name: Deploy to Production (only runs if tests pass) + run: | + sqlpackage /Action:Publish \ + /SourceFile:Database.dacpac \ + /TargetConnectionString:"${{ secrets.PROD_SQL_CONN }}" +``` + +**Test Structure**: +```sql +-- tSQLt test example +CREATE SCHEMA CustomerTests; +GO + +CREATE PROCEDURE CustomerTests.[test Customer Insert Sets Correct Defaults] +AS +BEGIN + -- Arrange + EXEC tSQLt.FakeTable 'dbo.Customers'; + + -- Act + INSERT INTO dbo.Customers (FirstName, LastName, Email) + VALUES ('John', 'Doe', 'john@example.com'); + + -- Assert + EXEC tSQLt.AssertEquals @Expected = 1, + @Actual = (SELECT COUNT(*) FROM dbo.Customers); + EXEC tSQLt.AssertNotEquals @Expected = NULL, + @Actual = (SELECT CreatedDate FROM dbo.Customers); +END; +GO + +-- Run all tests +EXEC tSQLt.RunAll; +``` + +**Azure DevOps Integration**: +```yaml +- task: PowerShell@2 + displayName: 'Run tSQLt Tests' + inputs: + targetType: 'inline' + script: | + # Execute tSQLt tests + $results = Invoke-Sqlcmd -ServerInstance $(testServer) ` + -Database $(testDatabase) ` + -Query "EXEC tSQLt.RunAll" ` + -Verbose + + # Check for failures + $failures = $results | Where-Object { $_.Class -eq 'Failure' } + if ($failures) { + Write-Error "Tests failed: $($failures.Count) failures" + exit 1 + } +``` + +### 3. Windows Authentication Over SQL Authentication + +**Security Best Practice**: Prefer Windows Authentication (Integrated Security) for CI/CD agents. + +**Why Windows Auth**: +- No passwords stored in connection strings +- Leverages existing Active Directory infrastructure +- Service accounts with minimal permissions +- Audit trail via Windows Security logs +- No credential rotation needed + +**Implementation**: + +**Self-Hosted Agents (Recommended)**: +```yaml +# GitHub Actions with self-hosted Windows agent +runs-on: [self-hosted, windows, sql-deploy] + +steps: + - name: Deploy with Windows Auth + run: | + sqlpackage /Action:Publish \ + /SourceFile:Database.dacpac \ + /TargetConnectionString:"Server=prod-sql;Database=MyDB;Integrated Security=True;" \ + /p:BlockOnPossibleDataLoss=True +``` + +**Azure DevOps with Service Connection**: +```yaml +- task: SqlAzureDacpacDeployment@1 + inputs: + authenticationType: 'integratedAuth' # Uses Windows Auth + serverName: 'prod-sql.domain.com' + databaseName: 'MyDatabase' + dacpacFile: '$(Build.ArtifactStagingDirectory)/Database.dacpac' +``` + +**Alternative for Cloud Agents (Azure SQL)**: +```yaml +# Use Managed Identity instead of SQL auth +- name: Deploy with Managed Identity + run: | + sqlpackage /Action:Publish \ + /SourceFile:Database.dacpac \ + /TargetConnectionString:"Server=tcp:server.database.windows.net;Database=MyDB;Authentication=ActiveDirectoryManagedIdentity;" \ + /p:BlockOnPossibleDataLoss=True +``` + +**Never Do This**: +```yaml +# BAD: Plain text SQL auth password +TargetConnectionString: "Server=prod;Database=MyDB;User=sa;Password=P@ssw0rd123" +``` + +**If SQL Auth Required**: +```yaml +# Use secrets/variables (least preferred method) +- name: Deploy with SQL Auth (Not Recommended) + run: | + sqlpackage /Action:Publish \ + /SourceFile:Database.dacpac \ + /TargetServerName:"${{ secrets.SQL_SERVER }}" \ + /TargetDatabaseName:"${{ secrets.SQL_DATABASE }}" \ + /TargetUser:"${{ secrets.SQL_USER }}" \ + /TargetPassword:"${{ secrets.SQL_PASSWORD }}" \ + /p:BlockOnPossibleDataLoss=True + # Still not as secure as Windows Auth! +``` + +### 4. Version Control Everything + +**What to Version**: +``` +DatabaseProject/ +├── Tables/ +│ ├── Customer.sql +│ └── Order.sql +├── StoredProcedures/ +│ └── GetCustomerOrders.sql +├── Tests/ +│ ├── CustomerTests/ +│ │ └── test_CustomerInsert.sql +│ └── OrderTests/ +│ └── test_OrderValidation.sql +├── Scripts/ +│ ├── Script.PreDeployment.sql +│ └── Script.PostDeployment.sql +├── Database.sqlproj +├── Database.Dev.publish.xml +├── Database.Prod.publish.xml +└── .gitignore +``` + +**.gitignore**: +``` +# Build outputs +bin/ +obj/ +*.dacpac + +# User-specific files +*.user +*.suo + +# Visual Studio folders +.vs/ + +# Never commit credentials +*.publish.xml.user +``` + +**Check-in Requirements**: +- Require code review for database changes +- Mandate comments on all commits +- Run automated tests before merge +- Enforce naming conventions via branch policies + +### 5. Deployment Reports Always Required + +**Before Production Deployment**: +```yaml +- name: Generate Deployment Report + run: | + sqlpackage /Action:DeployReport \ + /SourceFile:Database.dacpac \ + /TargetConnectionString:"${{ secrets.PROD_SQL_CONN }}" \ + /OutputPath:deploy-report.xml \ + /p:BlockOnPossibleDataLoss=True + +- name: Parse and Review Report + run: | + # Extract key metrics from XML + echo "=== DEPLOYMENT REPORT ===" + # Parse XML for operations count + # Check for data loss warnings + # Display to user or post to PR + +- name: Require Manual Approval + uses: trstringer/manual-approval@v1 + with: + approvers: database-admins + minimum-approvals: 1 + instructions: "Review deploy-report.xml before approving" + +- name: Deploy After Approval + run: | + sqlpackage /Action:Publish \ + /SourceFile:Database.dacpac \ + /TargetConnectionString:"${{ secrets.PROD_SQL_CONN }}" +``` + +### 6. Environment Promotion Strategy + +**Standard Flow**: Dev → QA → Staging → Production + +**Consistent Deployment Options**: +```yaml +# Define environment-specific properties +environments: + dev: + blockOnDataLoss: false + dropObjectsNotInSource: true + backupBeforeChanges: false + + qa: + blockOnDataLoss: true + dropObjectsNotInSource: false + backupBeforeChanges: true + + staging: + blockOnDataLoss: true + dropObjectsNotInSource: false + backupBeforeChanges: true + + production: + blockOnDataLoss: true + dropObjectsNotInSource: false + backupBeforeChanges: true + requireApproval: true +``` + +## Complete GitHub Actions Pipeline (2025 Best Practice) + +```yaml +name: SQL Server CI/CD Pipeline + +on: + push: + branches: [main, develop] + pull_request: + branches: [main] + +env: + DOTNET_VERSION: '8.0.x' + SQLPACKAGE_VERSION: '170.2.70' + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Setup .NET 8 + uses: actions/setup-dotnet@v4 + with: + dotnet-version: ${{ env.DOTNET_VERSION }} + + - name: Install SqlPackage + run: dotnet tool install -g Microsoft.SqlPackage --version ${{ env.SQLPACKAGE_VERSION }} + + - name: Build Database Project + run: dotnet build src/Database.sqlproj -c Release + + - name: Build Test Project + run: dotnet build tests/DatabaseTests.sqlproj -c Release + + - name: Upload DACPAC Artifacts + uses: actions/upload-artifact@v4 + with: + name: dacpacs + path: | + src/bin/Release/*.dacpac + tests/bin/Release/*.dacpac + + test: + runs-on: windows-latest # tSQLt requires SQL Server + needs: build + steps: + - uses: actions/checkout@v4 + + - name: Download Artifacts + uses: actions/download-artifact@v4 + with: + name: dacpacs + + - name: Setup Test Database + run: | + sqlcmd -S localhost -Q "CREATE DATABASE TestDB" + + - name: Deploy Database to Test + run: | + sqlpackage /Action:Publish ` + /SourceFile:Database.dacpac ` + /TargetConnectionString:"Server=localhost;Database=TestDB;Integrated Security=True;" + + - name: Deploy tSQLt Framework + run: | + sqlpackage /Action:Publish ` + /SourceFile:DatabaseTests.dacpac ` + /TargetConnectionString:"Server=localhost;Database=TestDB;Integrated Security=True;" + + - name: Run tSQLt Unit Tests + run: | + $results = Invoke-Sqlcmd -ServerInstance localhost ` + -Database TestDB ` + -Query "EXEC tSQLt.RunAll" ` + -Verbose + + $failures = $results | Where-Object { $_.Class -eq 'Failure' } + if ($failures) { + Write-Error "Tests failed: $($failures.Count) failures" + exit 1 + } + Write-Host "All tests passed!" + + deploy-dev: + runs-on: [self-hosted, windows, sql-deploy] + needs: test + if: github.ref == 'refs/heads/develop' + environment: dev + steps: + - name: Download Artifacts + uses: actions/download-artifact@v4 + with: + name: dacpacs + + - name: Deploy to Dev (Windows Auth) + run: | + sqlpackage /Action:Publish ` + /SourceFile:Database.dacpac ` + /TargetConnectionString:"Server=dev-sql;Database=MyDB;Integrated Security=True;" ` + /p:BlockOnPossibleDataLoss=False ` + /p:DropObjectsNotInSource=True + + deploy-staging: + runs-on: [self-hosted, windows, sql-deploy] + needs: test + if: github.ref == 'refs/heads/main' + environment: staging + steps: + - name: Download Artifacts + uses: actions/download-artifact@v4 + with: + name: dacpacs + + - name: Generate Deployment Report + run: | + sqlpackage /Action:DeployReport ` + /SourceFile:Database.dacpac ` + /TargetConnectionString:"Server=staging-sql;Database=MyDB;Integrated Security=True;" ` + /OutputPath:deploy-report.xml + + - name: Deploy to Staging (Windows Auth) + run: | + sqlpackage /Action:Publish ` + /SourceFile:Database.dacpac ` + /TargetConnectionString:"Server=staging-sql;Database=MyDB;Integrated Security=True;" ` + /p:BlockOnPossibleDataLoss=True ` + /p:BackupDatabaseBeforeChanges=True ` + /p:DropObjectsNotInSource=False + + deploy-production: + runs-on: [self-hosted, windows, sql-deploy] + needs: deploy-staging + environment: production + steps: + - name: Download Artifacts + uses: actions/download-artifact@v4 + with: + name: dacpacs + + - name: Generate Deployment Report + run: | + sqlpackage /Action:DeployReport ` + /SourceFile:Database.dacpac ` + /TargetConnectionString:"Server=prod-sql;Database=MyDB;Integrated Security=True;" ` + /OutputPath:prod-deploy-report.xml + + - name: Manual Approval Required + uses: trstringer/manual-approval@v1 + with: + approvers: database-admins,devops-leads + minimum-approvals: 2 + instructions: "Review prod-deploy-report.xml and approve deployment" + + - name: Deploy to Production (Windows Auth) + run: | + sqlpackage /Action:Publish ` + /SourceFile:Database.dacpac ` + /TargetConnectionString:"Server=prod-sql;Database=MyDB;Integrated Security=True;" ` + /p:BlockOnPossibleDataLoss=True ` + /p:BackupDatabaseBeforeChanges=True ` + /p:DropObjectsNotInSource=False ` + /p:DoNotDropObjectTypes=Users;Logins;RoleMembership ` + /DiagnosticsFile:prod-deploy.log + + - name: Upload Deployment Logs + if: always() + uses: actions/upload-artifact@v4 + with: + name: production-deployment-logs + path: prod-deploy.log +``` + +## Azure DevOps Pipeline Example (2025) + +```yaml +trigger: + branches: + include: + - main + - develop + +pool: + vmImage: 'windows-2022' + +variables: + buildConfiguration: 'Release' + dotnetVersion: '8.0.x' + sqlPackageVersion: '170.2.70' + +stages: +- stage: Build + jobs: + - job: BuildDatabase + steps: + - task: UseDotNet@2 + displayName: 'Install .NET 8' + inputs: + version: $(dotnetVersion) + + - task: DotNetCoreCLI@2 + displayName: 'Build Database Project' + inputs: + command: 'build' + projects: '**/*.sqlproj' + arguments: '-c $(buildConfiguration)' + + - task: PublishBuildArtifacts@1 + displayName: 'Publish DACPAC' + inputs: + PathtoPublish: '$(Build.SourcesDirectory)/bin/$(buildConfiguration)' + ArtifactName: 'dacpacs' + +- stage: Test + dependsOn: Build + jobs: + - job: RunUnitTests + steps: + - task: DownloadBuildArtifacts@1 + inputs: + artifactName: 'dacpacs' + + - task: SqlAzureDacpacDeployment@1 + displayName: 'Deploy to Test Database' + inputs: + authenticationType: 'integratedAuth' + serverName: 'test-sql-server' + databaseName: 'TestDB' + dacpacFile: '$(System.ArtifactsDirectory)/dacpacs/Database.dacpac' + + - task: PowerShell@2 + displayName: 'Run tSQLt Tests' + inputs: + targetType: 'inline' + script: | + $results = Invoke-Sqlcmd -ServerInstance 'test-sql-server' ` + -Database 'TestDB' ` + -Query "EXEC tSQLt.RunAll" + + $failures = $results | Where-Object { $_.Class -eq 'Failure' } + if ($failures) { + throw "Tests failed: $($failures.Count) failures" + } + +- stage: DeployProduction + dependsOn: Test + condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main')) + jobs: + - deployment: DeployToProduction + environment: 'Production' + strategy: + runOnce: + deploy: + steps: + - task: SqlAzureDacpacDeployment@1 + displayName: 'Generate Deployment Report' + inputs: + deployType: 'DeployReport' + authenticationType: 'integratedAuth' + serverName: 'prod-sql-server' + databaseName: 'ProductionDB' + dacpacFile: '$(Pipeline.Workspace)/dacpacs/Database.dacpac' + outputFile: 'deploy-report.xml' + + - task: SqlAzureDacpacDeployment@1 + displayName: 'Deploy to Production' + inputs: + authenticationType: 'integratedAuth' + serverName: 'prod-sql-server' + databaseName: 'ProductionDB' + dacpacFile: '$(Pipeline.Workspace)/dacpacs/Database.dacpac' + additionalArguments: '/p:BlockOnPossibleDataLoss=True /p:BackupDatabaseBeforeChanges=True' +``` + +## Best Practices Checklist + +### Source Control +- [ ] All database objects in source control +- [ ] .gitignore configured for build outputs +- [ ] No credentials committed +- [ ] Test scripts versioned separately +- [ ] Branching strategy defined (gitflow, trunk-based, etc.) + +### Testing +- [ ] tSQLt framework deployed +- [ ] Unit tests cover critical stored procedures +- [ ] Tests grouped logically in schemas +- [ ] Pipeline aborts on test failure +- [ ] Test results published to dashboard + +### Security +- [ ] Windows Authentication used for CI/CD +- [ ] Service accounts follow principle of least privilege +- [ ] Secrets stored in Azure Key Vault / GitHub Secrets +- [ ] No plain text passwords +- [ ] Audit logging enabled + +### Deployment +- [ ] State-based deployment strategy +- [ ] Deployment reports generated before production +- [ ] Manual approval gates for production +- [ ] Backup before changes (production) +- [ ] BlockOnPossibleDataLoss enabled (production) +- [ ] DoNotDropObjectTypes configured +- [ ] Rollback plan documented + +### Monitoring +- [ ] Deployment logs captured +- [ ] Failed deployments trigger alerts +- [ ] Performance metrics tracked +- [ ] Schema drift detection automated + +## Resources + +- [tSQLt Official Site](https://tsqlt.org/) +- [Microsoft.Build.Sql Documentation](https://learn.microsoft.com/sql/tools/sql-database-projects/) +- [SqlPackage Reference](https://learn.microsoft.com/sql/tools/sqlpackage/) +- [Azure DevOps SQL Tasks](https://learn.microsoft.com/azure/devops/pipelines/tasks/deploy/sql-azure-dacpac-deployment) +- [GitHub Actions for SQL](https://github.com/marketplace?type=actions&query=sql+) diff --git a/skills/windows-git-bash-paths.md b/skills/windows-git-bash-paths.md new file mode 100644 index 0000000..511ba17 --- /dev/null +++ b/skills/windows-git-bash-paths.md @@ -0,0 +1,529 @@ +--- +name: windows-git-bash-paths +description: Windows and Git Bash path handling for SSDT, SqlPackage, and DACPAC files with shell detection +--- + +## 🚨 CRITICAL GUIDELINES + +### Windows File Path Requirements + +**MANDATORY: Always Use Backslashes on Windows for File Paths** + +When using Edit or Write tools on Windows, you MUST use backslashes (`\`) in file paths, NOT forward slashes (`/`). + +**Examples:** +- ❌ WRONG: `D:/repos/project/file.tsx` +- ✅ CORRECT: `D:\repos\project\file.tsx` + +This applies to: +- Edit tool file_path parameter +- Write tool file_path parameter +- All file operations on Windows systems + + +### Documentation Guidelines + +**NEVER create new documentation files unless explicitly requested by the user.** + +- **Priority**: Update existing README.md files rather than creating new documentation +- **Repository cleanliness**: Keep repository root clean - only README.md unless user requests otherwise +- **Style**: Documentation should be concise, direct, and professional - avoid AI-generated tone +- **User preference**: Only create additional .md files when user specifically asks for documentation + + +--- + +# Windows and Git Bash Path Handling for SSDT + +## Overview + +SQL Server development is Windows-heavy, and many developers use Git Bash (MINGW/MSYS2) as their preferred shell on Windows. This creates unique path conversion challenges when working with Windows-native tools like SqlPackage, MSBuild, and Visual Studio that expect Windows-style paths. + +This skill provides comprehensive guidance on handling path conversion issues, shell detection, and best practices for SSDT workflows on Windows with Git Bash. + +## The Path Conversion Problem + +### What Happens in Git Bash/MINGW + +Git Bash automatically converts POSIX-style paths to Windows paths, but this can cause issues with command-line arguments: + +**Automatic Conversions:** +- `/foo` → `C:/Program Files/Git/usr/foo` +- `/foo:/bar` → `C:\msys64\foo;C:\msys64\bar` +- `--dir=/foo` → `--dir=C:/msys64/foo` + +**Problematic for SqlPackage:** +```bash +# Git Bash converts /Action to a path! +sqlpackage /Action:Publish /SourceFile:MyDB.dacpac +# Becomes: sqlpackage C:/Program Files/Git/usr/Action:Publish ... +``` + +### What Triggers Conversion + +✓ Leading forward slash (/) in arguments +✓ Colon-separated path lists +✓ Arguments after `-` or `,` with path components + +### What's Exempt + +✓ Arguments containing `=` (variable assignments) +✓ Drive specifiers (`C:`) +✓ Arguments with `;` (already Windows format) +✓ Arguments starting with `//` (Windows switches) + +## Solutions for SqlPackage in Git Bash + +### Method 1: MSYS_NO_PATHCONV (Recommended) + +Disable path conversion for specific commands: + +```bash +# Temporarily disable path conversion +MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \ + /SourceFile:"MyDatabase.dacpac" \ + /TargetServerName:"localhost" \ + /TargetDatabaseName:"MyDB" + +# Works for all SqlPackage actions +MSYS_NO_PATHCONV=1 sqlpackage /Action:Extract \ + /SourceConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;" \ + /TargetFile:"MyDB_backup.dacpac" +``` + +**Important Notes:** +- The VALUE doesn't matter - setting to `0`, `false`, or empty still disables conversion +- Only matters that variable is DEFINED +- To re-enable: `env -u MSYS_NO_PATHCONV` + +### Method 2: Double Slash // (Alternative) + +Use double slashes for SqlPackage parameters: + +```bash +# Works in Git Bash and CMD +sqlpackage //Action:Publish \ + //SourceFile:MyDatabase.dacpac \ + //TargetServerName:localhost \ + //TargetDatabaseName:MyDB + +# Extract with double slashes +sqlpackage //Action:Extract \ + //SourceConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;" \ + //TargetFile:output.dacpac +``` + +**Advantages:** +- No environment variable needed +- Works across shells +- Shell-agnostic scripts + +### Method 3: Use Windows-Style Paths with Quotes + +Always quote paths with backslashes: + +```bash +# Quoted Windows paths work in Git Bash +MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \ + /SourceFile:"D:\Projects\MyDB\bin\Release\MyDB.dacpac" \ + /TargetConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;" + +# Or with forward slashes (Windows accepts both) +MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \ + /SourceFile:"D:/Projects/MyDB/bin/Release/MyDB.dacpac" \ + /TargetConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;" +``` + +### Method 4: Switch to PowerShell or CMD + +For Windows-native tools, consider using native shells: + +```powershell +# PowerShell (recommended for Windows SSDT workflows) +sqlpackage /Action:Publish ` + /SourceFile:"MyDatabase.dacpac" ` + /TargetServerName:"localhost" ` + /TargetDatabaseName:"MyDB" +``` + +```cmd +:: CMD +sqlpackage /Action:Publish ^ + /SourceFile:"MyDatabase.dacpac" ^ + /TargetServerName:"localhost" ^ + /TargetDatabaseName:"MyDB" +``` + +## Shell Detection for Scripts + +### Bash Script Detection + +```bash +#!/bin/bash + +# Method 1: Check $OSTYPE +case "$OSTYPE" in + msys*) # MSYS/Git Bash/MinGW + export MSYS_NO_PATHCONV=1 + SQLPACKAGE_ARGS="/Action:Publish /SourceFile:MyDB.dacpac" + ;; + cygwin*) # Cygwin + export MSYS_NO_PATHCONV=1 + SQLPACKAGE_ARGS="/Action:Publish /SourceFile:MyDB.dacpac" + ;; + linux-gnu*) # Linux + SQLPACKAGE_ARGS="/Action:Publish /SourceFile:MyDB.dacpac" + ;; + darwin*) # macOS + SQLPACKAGE_ARGS="/Action:Publish /SourceFile:MyDB.dacpac" + ;; +esac + +sqlpackage $SQLPACKAGE_ARGS +``` + +```bash +# Method 2: Check uname -s (most portable) +case "$(uname -s)" in + MINGW64*|MINGW32*) + # Git Bash + export MSYS_NO_PATHCONV=1 + echo "Git Bash detected - path conversion disabled" + ;; + MSYS_NT*) + # MSYS + export MSYS_NO_PATHCONV=1 + echo "MSYS detected - path conversion disabled" + ;; + CYGWIN*) + # Cygwin + export MSYS_NO_PATHCONV=1 + echo "Cygwin detected - path conversion disabled" + ;; + Linux*) + # Linux or WSL + echo "Linux detected" + ;; + Darwin*) + # macOS + echo "macOS detected" + ;; +esac +``` + +```bash +# Method 3: Check $MSYSTEM (Git Bash specific) +if [ -n "$MSYSTEM" ]; then + # Running in Git Bash/MSYS2 + export MSYS_NO_PATHCONV=1 + echo "MSYS environment detected: $MSYSTEM" + case "$MSYSTEM" in + MINGW64) echo "64-bit native Windows environment" ;; + MINGW32) echo "32-bit native Windows environment" ;; + MSYS) echo "POSIX-compliant environment" ;; + esac +fi +``` + +### Complete Build Script Example + +```bash +#!/bin/bash +# build-and-deploy.sh - Cross-platform SSDT build script + +set -e # Exit on error + +# Detect shell and set path conversion +if [ -n "$MSYSTEM" ]; then + echo "Git Bash/MSYS2 detected - disabling path conversion" + export MSYS_NO_PATHCONV=1 +fi + +# Variables +PROJECT_NAME="MyDatabase" +BUILD_CONFIG="Release" +DACPAC_PATH="bin/${BUILD_CONFIG}/${PROJECT_NAME}.dacpac" +TARGET_SERVER="${SQL_SERVER:-localhost}" +TARGET_DB="${SQL_DATABASE:-MyDB}" + +# Build +echo "Building ${PROJECT_NAME}..." +dotnet build "${PROJECT_NAME}.sqlproj" -c "$BUILD_CONFIG" + +# Verify DACPAC exists +if [ ! -f "$DACPAC_PATH" ]; then + echo "ERROR: DACPAC not found at $DACPAC_PATH" + exit 1 +fi + +echo "DACPAC built successfully: $DACPAC_PATH" + +# Deploy +echo "Deploying to ${TARGET_SERVER}/${TARGET_DB}..." + +# Use double-slash method for maximum compatibility +sqlpackage //Action:Publish \ + //SourceFile:"$DACPAC_PATH" \ + //TargetServerName:"$TARGET_SERVER" \ + //TargetDatabaseName:"$TARGET_DB" \ + //p:BlockOnPossibleDataLoss=False + +echo "Deployment complete!" +``` + +## Common SSDT Path Issues in Git Bash + +### Issue 1: DACPAC File Paths + +**Problem:** +```bash +# Git Bash mangles the path +sqlpackage /Action:Publish /SourceFile:./bin/Release/MyDB.dacpac +# Error: Cannot find file +``` + +**Solution:** +```bash +# Use MSYS_NO_PATHCONV +MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \ + /SourceFile:"./bin/Release/MyDB.dacpac" + +# OR use absolute Windows path +MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \ + /SourceFile:"D:/Projects/MyDB/bin/Release/MyDB.dacpac" + +# OR use double slashes +sqlpackage //Action:Publish //SourceFile:./bin/Release/MyDB.dacpac +``` + +### Issue 2: SQL Project File Paths + +**Problem:** +```bash +# Path with spaces causes issues +dotnet build "D:/Program Files/MyProject/Database.sqlproj" +# Works in Git Bash (dotnet handles paths correctly) + +# But MSBuild paths may fail +msbuild "D:/Program Files/MyProject/Database.sqlproj" +# May fail if not quoted properly +``` + +**Solution:** +```bash +# Always quote paths with spaces +dotnet build "D:/Program Files/MyProject/Database.sqlproj" + +# Use backslashes for MSBuild on Windows +msbuild "D:\Program Files\MyProject\Database.sqlproj" + +# Or use 8.3 short names (no spaces) +msbuild "D:/PROGRA~1/MyProject/Database.sqlproj" +``` + +### Issue 3: Publish Profile Paths + +**Problem:** +```bash +# Publish profile not found +sqlpackage /Action:Publish \ + /SourceFile:MyDB.dacpac \ + /Profile:./Profiles/Production.publish.xml +``` + +**Solution:** +```bash +# Use MSYS_NO_PATHCONV with quoted paths +MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \ + /SourceFile:"MyDB.dacpac" \ + /Profile:"./Profiles/Production.publish.xml" + +# Or absolute Windows path +MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \ + /SourceFile:"D:/Projects/MyDB.dacpac" \ + /Profile:"D:/Projects/Profiles/Production.publish.xml" +``` + +### Issue 4: Connection Strings + +**Problem:** +```bash +# File paths in connection strings +/SourceConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;AttachDbFilename=D:/Data/MyDB.mdf" +# Path gets mangled +``` + +**Solution:** +```bash +# Quote entire connection string +MSYS_NO_PATHCONV=1 sqlpackage /Action:Extract \ + /SourceConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;AttachDbFilename=D:\Data\MyDB.mdf" \ + /TargetFile:"output.dacpac" + +# Or use double backslashes in connection string +/SourceConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;AttachDbFilename=D:\\Data\\MyDB.mdf" +``` + +## CI/CD Considerations + +### GitHub Actions with Git Bash + +```yaml +name: SSDT Build and Deploy + +on: [push] + +jobs: + build: + runs-on: windows-latest + defaults: + run: + shell: bash # Use Git Bash + + steps: + - uses: actions/checkout@v4 + + - name: Setup .NET + uses: actions/setup-dotnet@v4 + with: + dotnet-version: '8.0.x' + + - name: Install SqlPackage + run: dotnet tool install -g Microsoft.SqlPackage + + - name: Build Database Project + run: dotnet build Database.sqlproj -c Release + + - name: Deploy with Path Conversion Disabled + env: + MSYS_NO_PATHCONV: 1 + run: | + sqlpackage /Action:Publish \ + /SourceFile:"bin/Release/MyDatabase.dacpac" \ + /TargetServerName:"localhost" \ + /TargetDatabaseName:"MyDB" +``` + +### PowerShell Alternative (Recommended for Windows) + +```yaml +jobs: + build: + runs-on: windows-latest + defaults: + run: + shell: pwsh # Use PowerShell - no path issues + + steps: + - name: Deploy Database + run: | + sqlpackage /Action:Publish ` + /SourceFile:"bin/Release/MyDatabase.dacpac" ` + /TargetServerName:"localhost" ` + /TargetDatabaseName:"MyDB" +``` + +## Best Practices Summary + +### For Interactive Development + +1. **Use PowerShell or CMD for SSDT on Windows** - avoids path conversion issues entirely +2. **If using Git Bash**, set `MSYS_NO_PATHCONV=1` in your shell profile for SSDT work +3. **Always quote paths** containing spaces or special characters +4. **Use absolute paths** when possible to avoid ambiguity + +### For Scripts + +1. **Detect shell environment** and set `MSYS_NO_PATHCONV=1` conditionally +2. **Use double-slash // syntax** for SqlPackage arguments (most portable) +3. **Prefer PowerShell for Windows-specific workflows** (build scripts, CI/CD) +4. **Test scripts on all target platforms** (Windows PowerShell, Git Bash, Linux) + +### For CI/CD + +1. **Use PowerShell shell in GitHub Actions** for Windows runners (`shell: pwsh`) +2. **Self-hosted Windows agents** - use native Windows paths and shells +3. **Set MSYS_NO_PATHCONV=1 as environment variable** if Git Bash required +4. **Prefer dotnet CLI over MSBuild** for cross-platform compatibility + +### For Teams + +1. **Document shell requirements** in repository README +2. **Provide scripts for all shells** (bash, PowerShell, CMD) +3. **Standardize on PowerShell** for Windows SSDT workflows when possible +4. **Use containerized builds** to avoid shell-specific issues + +## Quick Reference + +### Environment Variables + +```bash +# Disable path conversion (Git Bash/MSYS2/Cygwin) +export MSYS_NO_PATHCONV=1 + +# Re-enable path conversion +env -u MSYS_NO_PATHCONV +``` + +### SqlPackage Command Templates + +```bash +# Git Bash - Method 1 (MSYS_NO_PATHCONV) +MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish /SourceFile:"MyDB.dacpac" /TargetServerName:"localhost" /TargetDatabaseName:"MyDB" + +# Git Bash - Method 2 (Double Slash) +sqlpackage //Action:Publish //SourceFile:MyDB.dacpac //TargetServerName:localhost //TargetDatabaseName:MyDB + +# PowerShell (Recommended for Windows) +sqlpackage /Action:Publish /SourceFile:"MyDB.dacpac" /TargetServerName:"localhost" /TargetDatabaseName:"MyDB" + +# CMD +sqlpackage /Action:Publish /SourceFile:"MyDB.dacpac" /TargetServerName:"localhost" /TargetDatabaseName:"MyDB" +``` + +### Shell Detection One-Liners + +```bash +# Check if Git Bash/MSYS +[ -n "$MSYSTEM" ] && echo "Git Bash/MSYS2 detected" + +# Check uname +[[ "$(uname -s)" =~ ^MINGW ]] && echo "Git Bash detected" + +# Set path conversion conditionally +[ -n "$MSYSTEM" ] && export MSYS_NO_PATHCONV=1 +``` + +## Resources + +- [Git Bash Path Conversion Guide](https://www.pascallandau.com/blog/setting-up-git-bash-mingw-msys2-on-windows/) +- [MSYS2 Path Conversion Documentation](https://www.msys2.org/docs/filesystem-paths/) +- [SqlPackage Documentation](https://learn.microsoft.com/sql/tools/sqlpackage/) +- [Microsoft.Build.Sql SDK](https://www.nuget.org/packages/Microsoft.Build.Sql) +- [Git for Windows](https://gitforwindows.org/) + +## Troubleshooting + +### "Invalid parameter" errors + +**Symptom:** SqlPackage reports "Invalid parameter" or "Unknown action" +**Cause:** Git Bash converting `/Action` to a file path +**Fix:** Use `MSYS_NO_PATHCONV=1` or double-slash `//Action` + +### "File not found" with valid paths + +**Symptom:** DACPAC or project file not found despite correct path +**Cause:** Path conversion mangling the file path +**Fix:** Quote paths and use `MSYS_NO_PATHCONV=1` + +### Build succeeds but publish fails + +**Symptom:** `dotnet build` works but `sqlpackage` fails +**Cause:** dotnet CLI handles paths correctly, but SqlPackage uses `/` parameters +**Fix:** Use `MSYS_NO_PATHCONV=1` for SqlPackage commands only + +### Spaces in paths cause errors + +**Symptom:** Paths with "Program Files" or other spaces fail +**Cause:** Unquoted paths split into multiple arguments +**Fix:** Always quote paths: `/SourceFile:"D:/Program Files/MyDB.dacpac"`