sql-schema

Database Architect skill. Use this when you need to modify the database schema, add tables, or seed data. This project uses RAW SQL SCRIPTS orchestrated by .NET Aspire, NOT Entity Framework Migrations.

6 stars

bycwoodruff

View on GitHub Installation ↓

Best use case

sql-schema is best used when you need a repeatable AI agent workflow instead of a one-off prompt.

Teams using sql-schema should expect a more consistent output, faster repeated execution, less prompt rewriting.

When to use this skill

You want a reusable workflow that can be run more than once with consistent structure.

When not to use this skill

You only need a quick one-off answer and do not need a reusable workflow.
You cannot install or maintain the underlying files, dependencies, or repository context.

Installation

Claude Code / Cursor / Codex

$curl -o ~/.claude/skills/sql-schema/SKILL.md --create-dirs "https://raw.githubusercontent.com/cwoodruff/morespeakers-com/main/.claude/skills/sql-schema/SKILL.md"

Manual Installation

Download SKILL.md from GitHub
Place it in .claude/skills/sql-schema/SKILL.md inside your project
Restart your AI agent — it will auto-discover the skill

How sql-schema Compares

Feature / Agent	sql-schema	Standard Approach
Platform Support	Not specified	Limited / Varies
Context Awareness	High	Baseline
Installation Complexity	Unknown	N/A

Frequently Asked Questions

What does this skill do?

Where can I find the source code?

You can find the source code on GitHub using the link provided at the top of the page.

SKILL.md Source

# SQL Schema Management Skill

## Overview

MoreSpeakers.com uses a "Script-Load" pattern via .NET Aspire (`MoreSpeakers.AppHost`) to initialize the SQL Server container. We **DO NOT** use `dotnet ef migrations`.

## Source of Truth

The database schema is defined in `scripts/database/`.

## Workflow

### 1. Identify the Change
Determine if you need a new table, a modified column, or new seed data.

### 2. Locate the Loading Logic
Check `src/MoreSpeakers.AppHost/AppHost.cs`. Look for the `sqlText` concatenation logic:

```csharp
var sqlText = string.Concat(
    File.ReadAllText(Path.Combine(path, @"../../scripts/database/create-database.sql")),
    " ",
    File.ReadAllText(Path.Combine(path, @"../../scripts/database/create-tables.sql")),
    // ... other files
);
```

### 3. Apply the Change

**Option A: Modify Existing Files (Preferred for clean slate)**
-   If adding a core table, add T-SQL to `scripts/database/create-tables.sql`.
-   If adding a view, use `scripts/database/create-views.sql`.

**Option B: Create New Script (For specific updates)**
1.  Create a new file, e.g., `scripts/database/update-schema-features.sql`.
2.  **CRITICAL**: You MUST update `AppHost.cs` to include this new file in the `string.Concat` list, or it will be ignored.

### 4. Writing SQL

-   **Idempotency**: Always write idempotent SQL. The script may run on container startup.
    ```sql
    IF NOT EXISTS (SELECT * FROM sys.tables WHERE name = 'MyTable')
    BEGIN
        CREATE TABLE MyTable (...)
    END
    ```
-   **Foreign Keys**: Ensure referenced tables are created *before* the table defining the key (check file order in `AppHost.cs`).

### 5. Verification
-   Run `dotnet run --project src/MoreSpeakers.AppHost`.
-   The container will spin up and execute the concatenated SQL script.

## PROHIBITED ACTIONS

-   ❌ `dotnet ef migrations add`
-   ❌ `dotnet ef database update`
-   ❌ Modifying the DbContext `OnModelCreating` without adding corresponding SQL scripts.