SqlForge.Core 0.2.0

SqlForge 🔨

Version-controlled, typed stored procedures for MSSQL — with Dapper codegen and AI-ready context output.

dotnet tool install -g SqlForge

The Problem

Your company has 100+ stored procedures in MSSQL. No one knows what parameters they take, what they return, or which tables they touch — unless they open SSMS and read the T-SQL. SPs change silently with no version history. And feeding this mess to an AI agent? Forget it.

What SqlForge Does

sqlforge sync       → Pulls all SPs from MSSQL, detects changes, bumps versions
sqlforge generate   → Generates typed Dapper wrappers + AI context markdown
sqlforge diff       → Shows what changed without touching anything
sqlforge annotate   → Adds human descriptions to SPs
sqlforge list       → Lists all tracked procedures

Quickstart

# 1. Install
dotnet tool install -g SqlForge

# 2. Create config in your project root
sqlforge init

# 3. Edit sqlforge.config.json with your connection string

# 4. Pull all SPs from the database
sqlforge sync

# 5. Generate typed Dapper wrappers + AI context
sqlforge generate

What Gets Generated

generated/Procedures.g.cs — Typed Dapper wrappers

// Before SqlForge — you write this manually, no IntelliSense on return shape
var results = await db.QueryAsync<dynamic>(
    "dbo.GetUserOrders", 
    new { userId = 5 },
    commandType: CommandType.StoredProcedure);

// After SqlForge — fully typed, IntelliSense on params AND return columns
var results = await SP.GetUserOrders(db, new(UserId: 5, Status: "active"));
// results is IEnumerable<GetUserOrdersResult>
// result.OrderId, result.Total, result.CreatedAt — all typed ✓

generated/context.md — AI-ready context

Instead of dumping 10,000 lines of T-SQL into your AI agent's context window, SqlForge generates a structured, token-efficient markdown document:

### `[dbo].[GetUserOrders]` (v3)
> Returns all orders for a given user, optionally filtered by status.

**Touches tables/views:** `Orders`, `Users`, `OrderItems`

**Parameters:**
| Name | SQL Type | C# Type | Mode | Nullable |
|------|----------|---------|------|----------|
| `@userId` | `int` | `int` | IN | no |
| `@status` | `varchar(50)` | `string` | IN | yes |

**Returns:**
| Column | SQL Type | C# Type |
|--------|----------|---------|
| `OrderId` | `int` | `int` |
| `Total` | `decimal(18,2)` | `decimal` |

.sp-registry/procedures/*.json — Version history

Each SP gets its own JSON file, committed to git:

{
  "name": "GetUserOrders",
  "schema": "dbo",
  "version": 3,
  "lastModifiedUtc": "2025-06-01T10:00:00Z",
  "description": "Returns all orders for a user, optionally filtered by status",
  "parameters": [ ... ],
  "returns": [ ... ],
  "dependsOn": ["Orders", "Users", "OrderItems"],
  "history": [
    { "version": 1, "changedAtUtc": "2024-01-15T...", "changeNote": "First discovered" },
    { "version": 2, "changedAtUtc": "2024-08-22T...", "changeNote": null },
    { "version": 3, "changedAtUtc": "2025-06-01T...", "changeNote": "Added status filter" }
  ]
}

Configuration

sqlforge.config.json:

{
  "connectionString": "Server=localhost;Database=YourDB;Trusted_Connection=True;TrustServerCertificate=True;",
  "schemas": ["dbo"],
  "exclude": ["sp_*", "xp_*", "dt_*"],
  "generation": {
    "namespace": "YourApp.Data.Procedures",
    "outputPath": "generated/",
    "generateDapperWrappers": true,
    "generateAiContext": true
  },
  "registry": {
    "path": ".sp-registry/"
  }
}

Version Control Workflow

your-project/
├── .sp-registry/              ← commit this to git
│   └── procedures/
│       ├── dbo.GetUserOrders.json
│       ├── dbo.CreateInvoice.json
│       └── ...
├── generated/                 ← optionally gitignore (regenerate on build)
│   ├── Procedures.g.cs
│   └── context.md
└── sqlforge.config.json       ← gitignore if it contains credentials

Recommended git workflow:

# Before committing a DB change
sqlforge sync --note "Added @status parameter to GetUserOrders"
sqlforge generate
git add .sp-registry/ generated/
git commit -m "chore: sync SP registry"

Now SP changes show up in PRs like code changes. Reviewers can see exactly what changed.

Annotating Stored Procedures

sqlforge annotate GetUserOrders --schema dbo "Returns paginated orders for a user. Status can be: active, cancelled, pending."
sqlforge generate   # re-run to include description in context.md

Descriptions survive future syncs — SqlForge never overwrites them.

Known Limitations

• sp_describe_first_result_set fails on SPs that use temp tables, dynamic SQL (EXEC(@sql)), or return multiple result sets. SqlForge will still track and version these SPs, but the returns field will be empty.
• Output parameters (@out / INOUT) are detected but the generated wrappers use DynamicParameters for these — check the generated code.
• Only MSSQL is supported currently.

Roadmap

• PostgreSQL support (functions + procedures)
• VS Code extension with hover-type IntelliSense from registry JSON
• sqlforge watch — auto-sync on SP changes
• Output parameter support in Dapper wrappers
• Multiple result set annotation

License

MIT