📚 Documentation: ChangeTypeOnClassNumber Migration

File: IrbyImaging.DbContext/Migrations/20250212153204_ChangeTypeOnClassNumber.cs


🗂 Table of Contents

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. Migration Workflow
    3.1. Up Method
    3.2. Down Method
  4. Data Model Impact
  5. UML Diagram
  6. Usage & Examples
  7. Error Handling & Rollbacks
  8. Conclusion

1. Overview & Purpose 🚀

The ChangeTypeOnClassNumber migration alters the ClassNumber column on the irby.JobClassification table:

  • Before: int NOT NULL
  • After: nvarchar(max) NULL

Why?

  • 📈 Flexibility: Accept alphanumeric and variable‑length codes.
  • 🛠 Compatibility: Accommodate prefixes, leading zeros, or special characters in classification numbers.

2. Dependencies & Technologies 🔧

Component Version / Requirement
Microsoft.EntityFrameworkCore.Migrations ≥ 6.0
.NET SDK ≥ 6.0
SQL Server (or any EF Core–supported DB) —

Note: This is a pure EF Core migration—no external NuGet packages beyond EF Core itself.


3. Migration Workflow 🔄

EF Core migrations are composed of two methods:

3.1 Up Method

protected override void Up(MigrationBuilder migrationBuilder)
{
    migrationBuilder.AlterColumn<string>(
        name: "ClassNumber",
        schema: "irby",
        table: "JobClassification",
        type: "nvarchar(max)",
        nullable: true,
        oldClrType: typeof(int),
        oldType: "int");
}
Parameter Description
name ClassNumber (column to alter)
schema irby (database schema)
table JobClassification
type nvarchar(max) (new SQL datatype)
nullable true (allows NULL)
oldClrType/oldType int (previous CLR & SQL types)

3.2 Down Method

protected override void Down(MigrationBuilder migrationBuilder)
{
    migrationBuilder.AlterColumn<int>(
        name: "ClassNumber",
        schema: "irby",
        table: "JobClassification",
        type: "int",
        nullable: false,
        defaultValue: 0,
        oldClrType: typeof(string),
        oldType: "nvarchar(max)",
        oldNullable: true);
}
  • Reverts the column back to int NOT NULL with default 0.

4. Data Model Impact 📊

After running this migration, update your JobClassification entity class:

public class JobClassification
{
    public int Id { get; set; }
    // Before: public int ClassNumber { get; set; }
    public string? ClassNumber { get; set; }
    // ...other properties...
}
Column Old Type New Type Nullable
ClassNumber int nvarchar(max) YES

5. UML Diagram 📈

classDiagram
    class JobClassification {
        +int Id
        +string? ClassNumber
        +... // other properties
    }
    note for JobClassification "ClassNumber type changed:\nint -> string"

6. Usage & Examples 💡

6.1 Adding & Applying

# 1. Add this migration
dotnet ef migrations add ChangeTypeOnClassNumber \
    --project IrbyImaging.DbContext

# 2. Apply to the database
dotnet ef database update

6.2 Rolling Back

# To revert just this migration:
dotnet ef database update 20250212153203_PreviousMigrationName

⚠️ Warning: Before rolling back, ensure no non-numeric or NULL values exist in ClassNumber, or the Down‑method will fail.


7. Error Handling & Rollbacks ⚠️

  • Data Conversion Risks

    • Up-grading (int→string): safe (all ints map to strings).
    • Down-grading (string→int): risky if values are non-numeric or NULL.
  • Best Practices

    1. Backup your database.
    2. Validate or cleanse data before calling database update on Down‑migration.
    3. Use a transactional context or wrap in a custom script if atomicity is required.

8. Conclusion 🎯

The ChangeTypeOnClassNumber migration is a straightforward but critical change:

  • Enables alphanumeric classification codes.
  • Keeps your data model in sync with evolving business requirements.

✅ Pro Tip: After applying, run your integration/unit tests against a copy of the production schema to catch any edge‑case issues early.


Happy Coding! 🚀
IrbyImaging Development Team