jdescopingtool/PLANS/2026-01-06-sql-naming-convention-implementation.md

SQL Object Naming Convention Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Rename stored procedures to use usp_ prefix and functions to use fn_ prefix for SQL Server best practice compliance.

Architecture: Modify existing DbUp SQL scripts, update C# code to use centralized constants, manually sync Docker database since DbUp won't re-run already-executed scripts.

Tech Stack: SQL Server, DbUp migrations, Dapper, SqlKata

---

Task 1: Update SubmitSearch Procedure Script

Files:

• Modify: src/JdeScoping.Database/Scripts/040_CreateSubmitSearchProcedure.sql

Step 1: Read current script

Read the file to understand current content.

Step 2: Update procedure name

Change [dbo].[SubmitSearch] to [dbo].[usp_SubmitSearch] in the CREATE OR ALTER statement.

-- Migration: 040_CreateSubmitSearchProcedure
-- Source: OLD/Database/StoredProcedures/SubmitSearch.sql
-- Creates a new search record with status=1 (Submitted)

CREATE OR ALTER PROCEDURE [dbo].[usp_SubmitSearch]
(
    @p_UserName VARCHAR(128),
    @p_Name VARCHAR(128),
    @p_Criteria VARCHAR(MAX),
    @o_SearchID INT OUTPUT
)
AS
BEGIN
    -- Insert new search record
    INSERT INTO dbo.Search
    (
        UserName,
        Name,
        Status,
        SubmitDT,
        Criteria
    )
    VALUES
    (
        @p_UserName,
        @p_Name,
        1,
        GETDATE(),
        @p_Criteria
    );

    -- Get assigned auto-ID
    SET @o_SearchID = SCOPE_IDENTITY();
END
GO

Step 3: Commit

git add src/JdeScoping.Database/Scripts/040_CreateSubmitSearchProcedure.sql
git commit -m "refactor(db): rename SubmitSearch to usp_SubmitSearch"

---

Task 2: Update StartSearch Procedure Script

Files:

• Modify: src/JdeScoping.Database/Scripts/041_CreateStartSearchProcedure.sql

Step 1: Update procedure name

Change [dbo].[StartSearch] to [dbo].[usp_StartSearch]:

-- Migration: 041_CreateStartSearchProcedure
-- Source: OLD/Database/StoredProcedures/StartSearch.sql
-- Updates search status to 2 (Started) and sets start timestamp

CREATE OR ALTER PROCEDURE [dbo].[usp_StartSearch]
(
    @p_SearchID INT
)
AS
BEGIN
    -- Update search status and start timestamp
    UPDATE dbo.Search
    SET Status = 2,
        StartDT = GETDATE()
    WHERE ID = @p_SearchID;
END
GO

Step 2: Commit

git add src/JdeScoping.Database/Scripts/041_CreateStartSearchProcedure.sql
git commit -m "refactor(db): rename StartSearch to usp_StartSearch"

---

Task 3: Update CompleteSearch Procedure Script

Files:

• Modify: src/JdeScoping.Database/Scripts/042_CreateCompleteSearchProcedure.sql

Step 1: Update procedure name

Change [dbo].[CompleteSearch] to [dbo].[usp_CompleteSearch]:

-- Migration: 042_CreateCompleteSearchProcedure
-- Source: OLD/Database/StoredProcedures/CompleteSearch.sql
-- Completes search with status 3 (Success) or 4 (Error) and stores results

CREATE OR ALTER PROCEDURE [dbo].[usp_CompleteSearch]
(
    @p_SearchID INT,
    @p_WasSuccessful BIT,
    @p_Results VARBINARY(MAX)
)
AS
BEGIN
    DECLARE @v_Status INT;

    -- Determine status code
    SET @v_Status = CASE @p_WasSuccessful
                      WHEN 1 THEN 3
                      ELSE 4
                    END;

    -- Update search status and results
    UPDATE dbo.Search
    SET Status = @v_Status,
        Results = @p_Results,
        EndDT = GETDATE()
    WHERE ID = @p_SearchID;
END
GO

Step 2: Commit

git add src/JdeScoping.Database/Scripts/042_CreateCompleteSearchProcedure.sql
git commit -m "refactor(db): rename CompleteSearch to usp_CompleteSearch"

---

Task 4: Update ResetPartialSearches Procedure Script

Files:

• Modify: src/JdeScoping.Database/Scripts/043_CreateResetPartialSearchesProcedure.sql

Step 1: Update procedure name

Change [dbo].[ResetPartialSearches] to [dbo].[usp_ResetPartialSearches]:

-- Migration: 043_CreateResetPartialSearchesProcedure
-- Source: OLD/Database/StoredProcedures/ResetPartialSearches.sql
-- Resets searches that were started but not completed (cleanup after crash)

CREATE OR ALTER PROCEDURE [dbo].[usp_ResetPartialSearches]
AS
BEGIN
    -- Reset status and start timestamp for searches begun but not finished
    UPDATE dbo.Search
    SET Status = 1,
        StartDT = NULL
    WHERE StartDT IS NOT NULL
      AND EndDT IS NULL;
END
GO

Step 2: Commit

git add src/JdeScoping.Database/Scripts/043_CreateResetPartialSearchesProcedure.sql
git commit -m "refactor(db): rename ResetPartialSearches to usp_ResetPartialSearches"

---

Task 5: Update MatchMIS Function Script

Files:

• Modify: src/JdeScoping.Database/Scripts/044_CreateMatchMisFunction.sql

Step 1: Update function name

Change [dbo].[MatchMIS] to [dbo].[fn_MatchMIS] in the CREATE OR ALTER statement (line 7).

Step 2: Commit

git add src/JdeScoping.Database/Scripts/044_CreateMatchMisFunction.sql
git commit -m "refactor(db): rename MatchMIS to fn_MatchMIS"

---

Task 6: Create SqlObjects Constants Class

Files:

• Create: src/JdeScoping.DataAccess/SqlObjects.cs

Step 1: Create constants file

namespace JdeScoping.DataAccess;

/// <summary>
/// Constants for SQL stored procedure and function names.
/// </summary>
public static class SqlObjects
{
    // Stored Procedures
    public const string SubmitSearch = "usp_SubmitSearch";
    public const string StartSearch = "usp_StartSearch";
    public const string CompleteSearch = "usp_CompleteSearch";
    public const string ResetPartialSearches = "usp_ResetPartialSearches";
    public const string ValidateSearchCriteria = "usp_ValidateSearchCriteria";

    // Functions
    public const string MatchMis = "fn_MatchMIS";
}

Step 2: Commit

git add src/JdeScoping.DataAccess/SqlObjects.cs
git commit -m "feat(data-access): add SqlObjects constants for SP/function names"

---

Task 7: Update LotFinderRepository to Use SqlObjects

Files:

• Modify: src/JdeScoping.DataAccess/Repositories/LotFinderRepository.SearchManagement.cs

Step 1: Update SubmitSearchAsync method

Find line 125 with new SqlCommand("SubmitSearch", connection) and change to use constant:

await using var command = new SqlCommand(SqlObjects.SubmitSearch, connection)

Also update the LogAndThrow call on line 150 to use the constant:

LogAndThrow(ex, operation, SqlObjects.SubmitSearch);

Step 2: Build to verify

dotnet build src/JdeScoping.DataAccess

Expected: Build succeeds.

Step 3: Commit

git add src/JdeScoping.DataAccess/Repositories/LotFinderRepository.SearchManagement.cs
git commit -m "refactor(data-access): use SqlObjects constant for SubmitSearch"

---

Task 8: Update MisQueryBuilder to Use SqlObjects

Files:

• Modify: src/JdeScoping.DataAccess/QueryBuilders/MisQueryBuilder.cs

Step 1: Update MatchMIS reference

Find line 162 with dbo.MatchMIS( and change to use the new name:

dbo.fn_MatchMIS(c.WorkOrderNumber, c.ItemNumber, c.BranchCode, c.RoutingType,

Note: Since this is raw SQL embedded in a string, we change directly to fn_MatchMIS rather than interpolating the constant. The constant exists for documentation/discoverability.

Step 2: Build to verify

dotnet build src/JdeScoping.DataAccess

Expected: Build succeeds.

Step 3: Commit

git add src/JdeScoping.DataAccess/QueryBuilders/MisQueryBuilder.cs
git commit -m "refactor(data-access): rename MatchMIS to fn_MatchMIS in MisQueryBuilder"

---

Task 9: Update Docker Database - Drop Old Objects

Step 1: Drop old procedures and function

docker exec scopingtool-sqlserver /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P 'ScopingTool_SA_2024Dev' -C -d ScopingTool -Q "
DROP PROCEDURE IF EXISTS dbo.SubmitSearch;
DROP PROCEDURE IF EXISTS dbo.StartSearch;
DROP PROCEDURE IF EXISTS dbo.CompleteSearch;
DROP PROCEDURE IF EXISTS dbo.ResetPartialSearches;
DROP FUNCTION IF EXISTS dbo.MatchMIS;
"

Step 2: Verify objects dropped

docker exec scopingtool-sqlserver /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P 'ScopingTool_SA_2024Dev' -C -d ScopingTool -Q "
SELECT name, type_desc FROM sys.objects
WHERE type IN ('P', 'FN', 'TF', 'IF')
AND name IN ('SubmitSearch', 'StartSearch', 'CompleteSearch', 'ResetPartialSearches', 'MatchMIS')
"

Expected: 0 rows returned.

---

Task 10: Update Docker Database - Create New Procedures

Step 1: Create usp_SubmitSearch

docker exec scopingtool-sqlserver /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P 'ScopingTool_SA_2024Dev' -C -d ScopingTool -Q "
CREATE OR ALTER PROCEDURE [dbo].[usp_SubmitSearch]
(
    @p_UserName VARCHAR(128),
    @p_Name VARCHAR(128),
    @p_Criteria VARCHAR(MAX),
    @o_SearchID INT OUTPUT
)
AS
BEGIN
    INSERT INTO dbo.Search (UserName, Name, Status, SubmitDT, Criteria)
    VALUES (@p_UserName, @p_Name, 1, GETDATE(), @p_Criteria);
    SET @o_SearchID = SCOPE_IDENTITY();
END
"

Step 2: Create usp_StartSearch

docker exec scopingtool-sqlserver /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P 'ScopingTool_SA_2024Dev' -C -d ScopingTool -Q "
CREATE OR ALTER PROCEDURE [dbo].[usp_StartSearch] (@p_SearchID INT)
AS
BEGIN
    UPDATE dbo.Search SET Status = 2, StartDT = GETDATE() WHERE ID = @p_SearchID;
END
"

Step 3: Create usp_CompleteSearch

docker exec scopingtool-sqlserver /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P 'ScopingTool_SA_2024Dev' -C -d ScopingTool -Q "
CREATE OR ALTER PROCEDURE [dbo].[usp_CompleteSearch]
(
    @p_SearchID INT,
    @p_WasSuccessful BIT,
    @p_Results VARBINARY(MAX)
)
AS
BEGIN
    DECLARE @v_Status INT = CASE @p_WasSuccessful WHEN 1 THEN 3 ELSE 4 END;
    UPDATE dbo.Search SET Status = @v_Status, Results = @p_Results, EndDT = GETDATE() WHERE ID = @p_SearchID;
END
"

Step 4: Create usp_ResetPartialSearches

docker exec scopingtool-sqlserver /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P 'ScopingTool_SA_2024Dev' -C -d ScopingTool -Q "
CREATE OR ALTER PROCEDURE [dbo].[usp_ResetPartialSearches]
AS
BEGIN
    UPDATE dbo.Search SET Status = 1, StartDT = NULL WHERE StartDT IS NOT NULL AND EndDT IS NULL;
END
"

---

Task 11: Update Docker Database - Create fn_MatchMIS

Step 1: Copy script content and execute

The MatchMIS function is too large for inline execution. Read the updated script file and execute via sqlcmd with input redirection or copy the content.

# Copy the SQL file to Docker container and execute
docker cp src/JdeScoping.Database/Scripts/044_CreateMatchMisFunction.sql scopingtool-sqlserver:/tmp/
docker exec scopingtool-sqlserver /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P 'ScopingTool_SA_2024Dev' -C -d ScopingTool -i /tmp/044_CreateMatchMisFunction.sql

Step 2: Verify all new objects exist

docker exec scopingtool-sqlserver /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P 'ScopingTool_SA_2024Dev' -C -d ScopingTool -Q "
SELECT name, type_desc FROM sys.objects
WHERE type IN ('P', 'FN', 'TF', 'IF')
ORDER BY type_desc, name
"

Expected: All procedures show usp_ prefix, all functions show fn_ prefix.

---

Task 12: Run Full Test Suite

Step 1: Build entire solution

dotnet build

Expected: Build succeeds.

Step 2: Run all tests

dotnet test

Expected: All tests pass (including database tests that use the renamed objects).

Step 3: Commit verification

No commit needed - verification only.

---

Task 13: Update OpenSpec sql-business-logic Spec

Files:

• Modify: openspec/specs/sql-business-logic/spec.md

Step 1: Update all procedure/function references

Replace:

• SubmitSearch with usp_SubmitSearch
• StartSearch with usp_StartSearch
• CompleteSearch with usp_CompleteSearch
• ResetPartialSearches with usp_ResetPartialSearches
• MatchMIS with fn_MatchMIS (but keep descriptive references like "MatchMIS function" as-is for readability)

Step 2: Commit

git add openspec/specs/sql-business-logic/spec.md
git commit -m "docs(openspec): update sql-business-logic with usp_/fn_ prefixes"

---

Task 14: Update OpenSpec database-schema Spec

Files:

• Modify: openspec/specs/database-schema/spec.md

Step 1: Update all procedure/function references

Same replacements as Task 13.

Step 2: Commit

git add openspec/specs/database-schema/spec.md
git commit -m "docs(openspec): update database-schema with usp_/fn_ prefixes"

---

Task 15: Update OpenSpec data-access Spec

Files:

• Modify: openspec/specs/data-access/spec.md

Step 1: Update procedure references

Replace EXEC dbo.SubmitSearch with EXEC dbo.usp_SubmitSearch and similar.

Step 2: Commit

git add openspec/specs/data-access/spec.md
git commit -m "docs(openspec): update data-access with usp_ prefix"

---

Task 16: Update OpenSpec search-processing Spec

Files:

• Modify: openspec/specs/search-processing/spec.md

Step 1: Update MatchMIS references

Replace dbo.MatchMIS with dbo.fn_MatchMIS.

Step 2: Commit

git add openspec/specs/search-processing/spec.md
git commit -m "docs(openspec): update search-processing with fn_MatchMIS"

---

Task 17: Update Architecture Documentation

Files:

• Modify: DOCUMENTATION/Architecture/Testing.md
• Modify: DOCUMENTATION/Architecture/Database.md

Step 1: Update Testing.md

Search for SubmitSearch and update any references.

Step 2: Update Database.md

Search for stored procedure references and update with usp_ prefix.

Step 3: Commit

git add DOCUMENTATION/Architecture/Testing.md DOCUMENTATION/Architecture/Database.md
git commit -m "docs: update architecture docs with usp_/fn_ prefixes"

---

Task 18: Final Verification

Step 1: Verify Docker database naming

docker exec scopingtool-sqlserver /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P 'ScopingTool_SA_2024Dev' -C -d ScopingTool -Q "
SELECT 'Procedures' as Type, name FROM sys.procedures WHERE schema_id = SCHEMA_ID('dbo') ORDER BY name;
SELECT 'Functions' as Type, name FROM sys.objects WHERE type IN ('FN', 'TF', 'IF') AND schema_id = SCHEMA_ID('dbo') ORDER BY name;
"

Expected:

• All procedures start with usp_
• All functions start with fn_

Step 2: Run full test suite one more time

dotnet test

Expected: All tests pass.

Step 3: Final commit (if any uncommitted changes)

git status

If clean, no action needed.