Initial commit
This commit is contained in:
Zhongwei Li
15
.claude-plugin/plugin.json
Normal file
15
.claude-plugin/plugin.json
Normal file
@@ -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"
|
||||
]
|
||||
}
|
||||
3
README.md
Normal file
3
README.md
Normal file
@@ -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.
|
||||
427
agents/ssdt-expert.md
Normal file
427
agents/ssdt-expert.md
Normal file
@@ -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.
|
||||
57
plugin.lock.json
Normal file
57
plugin.lock.json
Normal file
@@ -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": []
|
||||
}
|
||||
}
|
||||
762
skills/sql-server-2025.md
Normal file
762
skills/sql-server-2025.md
Normal file
@@ -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<ParseError> 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
|
||||
<!-- Database.sqlproj (SDK-style with SQL Server 2025 compatibility) -->
|
||||
<Project Sdk="Microsoft.Build.Sql/2.0.0">
|
||||
<PropertyGroup>
|
||||
<Name>MyDatabase</Name>
|
||||
<!-- Use SQL Server 2022 (160) provider until 2025 provider available -->
|
||||
<DSP>Microsoft.Data.Tools.Schema.Sql.Sql160DatabaseSchemaProvider</DSP>
|
||||
<TargetFramework>net8.0</TargetFramework>
|
||||
<SqlServerVersion>Sql160</SqlServerVersion>
|
||||
|
||||
<!-- SQL Server 2025 features will still work in runtime database -->
|
||||
<!-- Only build-time validation uses Sql160 provider -->
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<Folder Include="Tables\" />
|
||||
<Folder Include="Views\" />
|
||||
<Folder Include="StoredProcedures\" />
|
||||
</ItemGroup>
|
||||
</Project>
|
||||
```
|
||||
|
||||
### 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
|
||||
<!-- Database.publish.xml -->
|
||||
<Project>
|
||||
<PropertyGroup>
|
||||
<TargetConnectionString>Server=tcp:server2025.database.windows.net;Database=MyDb;Authentication=ActiveDirectoryManagedIdentity;</TargetConnectionString>
|
||||
<BlockOnPossibleDataLoss>True</BlockOnPossibleDataLoss>
|
||||
<TargetDatabaseName>MyDatabase</TargetDatabaseName>
|
||||
<ProfileVersionNumber>1</ProfileVersionNumber>
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<SqlCmdVariable Include="Environment">
|
||||
<Value>Production</Value>
|
||||
</SqlCmdVariable>
|
||||
</ItemGroup>
|
||||
</Project>
|
||||
```
|
||||
|
||||
```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
|
||||
<PropertyGroup>
|
||||
<TargetPlatform>SqlServer2025</TargetPlatform>
|
||||
</PropertyGroup>
|
||||
```
|
||||
|
||||
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/)
|
||||
669
skills/ssdt-cicd-best-practices-2025.md
Normal file
669
skills/ssdt-cicd-best-practices-2025.md
Normal file
@@ -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+)
|
||||
529
skills/windows-git-bash-paths.md
Normal file
529
skills/windows-git-bash-paths.md
Normal file
@@ -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"`
|
||||
Reference in New Issue
Block a user