docs: add SQL naming convention implementation plan
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,591 @@
|
||||
# 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.
|
||||
|
||||
```sql
|
||||
-- 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**
|
||||
|
||||
```bash
|
||||
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]`:
|
||||
|
||||
```sql
|
||||
-- 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**
|
||||
|
||||
```bash
|
||||
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]`:
|
||||
|
||||
```sql
|
||||
-- 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**
|
||||
|
||||
```bash
|
||||
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]`:
|
||||
|
||||
```sql
|
||||
-- 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**
|
||||
|
||||
```bash
|
||||
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**
|
||||
|
||||
```bash
|
||||
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**
|
||||
|
||||
```csharp
|
||||
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**
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```csharp
|
||||
await using var command = new SqlCommand(SqlObjects.SubmitSearch, connection)
|
||||
```
|
||||
|
||||
Also update the LogAndThrow call on line 150 to use the constant:
|
||||
|
||||
```csharp
|
||||
LogAndThrow(ex, operation, SqlObjects.SubmitSearch);
|
||||
```
|
||||
|
||||
**Step 2: Build to verify**
|
||||
|
||||
```bash
|
||||
dotnet build src/JdeScoping.DataAccess
|
||||
```
|
||||
|
||||
Expected: Build succeeds.
|
||||
|
||||
**Step 3: Commit**
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```csharp
|
||||
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**
|
||||
|
||||
```bash
|
||||
dotnet build src/JdeScoping.DataAccess
|
||||
```
|
||||
|
||||
Expected: Build succeeds.
|
||||
|
||||
**Step 3: Commit**
|
||||
|
||||
```bash
|
||||
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**
|
||||
|
||||
```bash
|
||||
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**
|
||||
|
||||
```bash
|
||||
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**
|
||||
|
||||
```bash
|
||||
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**
|
||||
|
||||
```bash
|
||||
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**
|
||||
|
||||
```bash
|
||||
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**
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
# 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**
|
||||
|
||||
```bash
|
||||
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**
|
||||
|
||||
```bash
|
||||
dotnet build
|
||||
```
|
||||
|
||||
Expected: Build succeeds.
|
||||
|
||||
**Step 2: Run all tests**
|
||||
|
||||
```bash
|
||||
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**
|
||||
|
||||
```bash
|
||||
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**
|
||||
|
||||
```bash
|
||||
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**
|
||||
|
||||
```bash
|
||||
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**
|
||||
|
||||
```bash
|
||||
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**
|
||||
|
||||
```bash
|
||||
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**
|
||||
|
||||
```bash
|
||||
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**
|
||||
|
||||
```bash
|
||||
dotnet test
|
||||
```
|
||||
|
||||
Expected: All tests pass.
|
||||
|
||||
**Step 3: Final commit (if any uncommitted changes)**
|
||||
|
||||
```bash
|
||||
git status
|
||||
```
|
||||
|
||||
If clean, no action needed.
|
||||
Reference in New Issue
Block a user