📚 IrbyImaging.DbContext Migrations Documentation

File: 20230614163408_AddBlobNameColumn.cs


Table of Contents

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. Key Functional Areas
  4. Migration Class: AddBlobNameColumn
  5. Applying & Rolling Back Migrations
  6. Sample Code Blocks & Usage Examples
  7. Error Handling & Best Practices
  8. Conclusion

1. Overview & Purpose

📝 What is this file?
This C# file defines an Entity Framework Core Migration that adds a new column named BlobName to the DocumentImage table within the irby schema of the database. Migrations in EF Core provide a way to incrementally evolve the database schema over time as your model changes, while preserving existing data.

Why add BlobName?

  • Enable storing a reference (name/key) to the BLOB (Binary Large OBject) in an external storage system (e.g., Azure Blob Storage, AWS S3).
  • Decouple the binary data from the database rows, improving scalability and performance.

2. Dependencies & Technologies

Category Details
Language C# (.NET 6.0 / .NET Core 3.1+)
ORM Framework Entity Framework Core ≥ 3.1
Package Microsoft.EntityFrameworkCore.Migrations
Database Provider SQL Server, PostgreSQL, MySQL (via EF Core)
Tools dotnet ef CLI, Visual Studio / VS Code

3. Key Functional Areas

  1. Schema Extension 🏗️
    • Adds a new nullable text column BlobName to irby.DocumentImage.
  2. Reversibility 🔄
    • Defines both Up() (apply) and Down() (revert) methods for rolling changes back.

4. Migration Class: AddBlobNameColumn

using Microsoft.EntityFrameworkCore.Migrations;

namespace IrbyImaging.DbContext.Migrations
{
    public partial class AddBlobNameColumn : Migration
    {
        protected override void Up(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.AddColumn<string>(
                name: "BlobName",
                schema: "irby",
                table: "DocumentImage",
                type: "nvarchar(max)",
                nullable: true);
        }

        protected override void Down(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.DropColumn(
                name: "BlobName",
                schema: "irby",
                table: "DocumentImage");
        }
    }
}

4.1 Class Diagram (UML)

+--------------------------------------+
| <<Migration>>                        |
| AddBlobNameColumn                    |
|--------------------------------------|
| +Up(migrationBuilder) : void         |
| +Down(migrationBuilder) : void       |
+--------------------------------------+

4.2 Up Method

  • Signature: protected override void Up(MigrationBuilder migrationBuilder)
  • Responsibility: Apply the migration by modifying the database schema.
  • Operation:
    • migrationBuilder.AddColumn<string>
      • name: "BlobName"
      • schema: "irby"
      • table: "DocumentImage"
      • type: "nvarchar(max)"
      • nullable: true

4.3 Down Method

  • Signature: protected override void Down(MigrationBuilder migrationBuilder)
  • Responsibility: Reverse the migration, restoring the previous schema.
  • Operation:
    • migrationBuilder.DropColumn
      • name: "BlobName"
      • schema: "irby"
      • table: "DocumentImage"

5. Applying & Rolling Back Migrations

5.1 Apply Migration 🚀

dotnet ef migrations add AddBlobNameColumn
dotnet ef database update
  • Result: DocumentImage table now has a new nullable BlobName column.

5.2 Rollback Migration 🔙

dotnet ef database update <PreviousMigrationName>
  • Or remove the last migration entirely:
    dotnet ef migrations remove
    

6. Sample Code Blocks & Usage Examples

6.1 Saving a New DocumentImage with BlobName

using var context = new IrbyDbContext();
var docImage = new DocumentImage
{
    Name        = "Invoice_123",
    ContentType = "image/png",
    BlobName    = "invoices/2023/123.png",
    CreatedAt   = DateTime.UtcNow
};
context.DocumentImages.Add(docImage);
context.SaveChanges();

6.2 Querying by BlobName

var img = context.DocumentImages
    .FirstOrDefault(d => d.BlobName == "invoices/2023/123.png");
if (img != null) {
    Console.WriteLine($"Found image: {img.Name}");
}

7. Error Handling & Best Practices

  • Nullable Column: Since BlobName is nullable, existing rows won’t break.
  • Data Migration: If you need to backfill existing records, create a follow‑up migration or use a SQL script in Up().
  • Idempotency: EF Core migrations are designed to run only once; don’t manually re-run AddColumn calls.
  • Testing:
    • Write integration tests to ensure the column exists and can be read/written.
    • Use an in‑memory or local test database.

8. Conclusion

This migration, AddBlobNameColumn, is a simple yet critical schema evolution step that introduces a new data point (BlobName) for document images. It leverages EF Core’s fluent migration API to ensure a safe, reversible update to the database. By storing external blob references, your application can scale storage independently of your relational database, boosting performance and cost‑efficiency. 🚀


Happy Coding! 👩‍💻👨‍💻