|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +The SQL Server First Responder Kit is a collection of T-SQL stored procedures for diagnosing and tuning Microsoft SQL Server performance. All code is pure T-SQL — there is no build system, no package manager, and no application framework. |
| 8 | + |
| 9 | +## Installation and Testing |
| 10 | + |
| 11 | +**Install all scripts on a local SQL Server:** |
| 12 | +```bash |
| 13 | +sqlcmd -S localhost -E -d master -C -i Install-All-Scripts.sql |
| 14 | +``` |
| 15 | + |
| 16 | +**Install only Azure-compatible scripts:** |
| 17 | +```bash |
| 18 | +sqlcmd -S localhost -E -d master -C -i Install-Azure.sql |
| 19 | +``` |
| 20 | + |
| 21 | +**Run the full release build, test suite, and PR creation (PowerShell):** |
| 22 | +```powershell |
| 23 | +& "Documentation\Development\Build Installation Scripts.ps1" |
| 24 | +# Optional params: |
| 25 | +& "Documentation\Development\Build Installation Scripts.ps1" -ServerInstance "MyServer" -Database "master" |
| 26 | +``` |
| 27 | +This script bumps version numbers, rebuilds the Install-*.sql files, runs all procs against a local instance, and (if clean) creates a PR into `dev`. |
| 28 | + |
| 29 | +**Run a single proc test manually:** |
| 30 | +```bash |
| 31 | +sqlcmd -S localhost -E -d master -C -Q "EXEC dbo.sp_Blitz @CheckUserDatabaseObjects = 1;" |
| 32 | +``` |
| 33 | + |
| 34 | +## Repository Structure |
| 35 | + |
| 36 | +| File | Purpose | |
| 37 | +|------|---------| |
| 38 | +| `sp_Blitz.sql` | Overall server health check | |
| 39 | +| `sp_BlitzCache.sql` | Query plan cache analysis | |
| 40 | +| `sp_BlitzFirst.sql` | Real-time performance diagnosis | |
| 41 | +| `sp_BlitzIndex.sql` | Index analysis and recommendations | |
| 42 | +| `sp_BlitzLock.sql` | Deadlock analysis | |
| 43 | +| `sp_BlitzWho.sql` | Active session inspection | |
| 44 | +| `sp_BlitzBackups.sql` | Backup health check | |
| 45 | +| `sp_BlitzAnalysis.sql` | Queries sp_BlitzFirst output tables | |
| 46 | +| `sp_DatabaseRestore.sql` | Multi-file restore helper | |
| 47 | +| `sp_ineachdb.sql` | Execute SQL in each database | |
| 48 | +| `sp_kill.sql` | Session killer utility | |
| 49 | +| `SqlServerVersions.sql` | Reference table for SQL Server versions/support dates | |
| 50 | +| `Install-All-Scripts.sql` | **Auto-generated** — concatenation of all sp_*.sql + SqlServerVersions.sql | |
| 51 | +| `Install-Azure.sql` | **Auto-generated** — Azure-compatible subset | |
| 52 | +| `Deprecated/` | Unmaintained scripts (sp_AllNightLog, sp_BlitzQueryStore, SQL 2005 versions) | |
| 53 | +| `Documentation/Development/Build Installation Scripts.ps1` | Release automation script | |
| 54 | + |
| 55 | +**Do not manually edit `Install-All-Scripts.sql` or `Install-Azure.sql`** — they are auto-generated by the build script from the individual `sp_*.sql` files. |
| 56 | + |
| 57 | +## Code Standards |
| 58 | + |
| 59 | +- All `sp_*.sql` files must compile and run on all Microsoft-currently-supported SQL Server versions (2016+) and Amazon RDS. Azure SQL DB support is best-effort. |
| 60 | +- Code must handle **case-sensitive** databases/servers, **Unicode object names**, and varied date formats. |
| 61 | +- Each proc stores its version in a `SELECT @Version = 'X.XX', @VersionDate = 'YYYYMMDD';` statement — the build script uses this pattern to bump versions during release. |
| 62 | +- Procs use `WITH RECOMPILE`, `SET TRANSACTION ISOLATION LEVEL READ UNCOMMITTED`, and `SET NOCOUNT ON` as standard preamble. |
| 63 | +- The `@Debug` parameter (TINYINT) is a convention shared across procs for verbose output. |
| 64 | +- Common output parameters: `@Version VARCHAR(30) OUTPUT`, `@VersionDate DATETIME OUTPUT`, `@VersionCheckMode BIT`. |
| 65 | + |
| 66 | +## AI Features (sp_BlitzCache and sp_BlitzIndex) |
| 67 | + |
| 68 | +Both procs support an `@AI` parameter: |
| 69 | +- `@AI = 2` — builds and returns an AI prompt (copy/paste into any AI tool, no setup required) |
| 70 | +- `@AI = 1` — calls an AI API directly via `sp_invoke_external_rest_endpoint` (requires SQL Server 2025 or Azure SQL DB, plus database-scoped credentials) |
| 71 | + |
| 72 | +Optional config tables (`dbo.Blitz_AI_Providers`, `dbo.Blitz_AI_Prompts`) override defaults. A database-level `CONSTITUTION.md` extended property is included in AI prompts when present. See `Documentation/Using_AI.md` for full setup. |
| 73 | + |
| 74 | +## Version and Release Flow |
| 75 | + |
| 76 | +1. Work happens on feature branches off `dev`; PRs target `dev`. |
| 77 | +2. `Install-All-Scripts.sql` and `Install-Azure.sql` are rebuilt by the PowerShell build script — never hand-edit them. |
| 78 | +3. The build script bumps the minor version by 0.01 and updates `@VersionDate` to today across all `sp_*.sql` files. |
| 79 | +4. All procs share the same version number and date. |
0 commit comments