Update database-migrations rule file to PostgreSQL conventions with snake_case naming

Author: tjementum

.claude/rules/backend/database-migrations.md

@@ -1,41 +1,50 @@
 ---
 paths: **/Database/Migrations/*.cs
-description: Rules for creating database migrations
+description: Rules for creating database migrations with PostgreSQL conventions
 ---
 
 # Database Migrations
 
-Guidelines for creating database migrations.
+Guidelines for creating database migrations using PostgreSQL conventions with snake_case naming.
 
 ## Implementation
 
 1. Create migrations manually rather than using Entity Framework tooling:
    - Place migrations in `/[scs-name]/Core/Database/Migrations`
    - Name migration files with 14-digit timestamp prefix: `YYYYMMDDHHmmss_MigrationName.cs`
-   - Only implement the `Up` method—don't create `Down` migration
+   - Only implement the `Up` method--don't create `Down` migration
 
 2. Follow this strict column ordering in table creation statements:
-   - `TenantId` (if applicable)
-   - `Id` (always required)
+   - `tenant_id` (if applicable)
+   - `id` (always required)
    - Foreign keys (if applicable)
-   - `CreatedAt` and `ModifiedAt` as non-nullable `datetimeoffset`
+   - `created_at` and `modified_at` as non-nullable/nullable `timestamptz`
    - All other properties in the same order as they appear in the C# Aggregate class
 
-3. Use appropriate SQL Server data types:
-   - Use `varchar(32)` for strongly typed IDs (ULID is 26 chars + underscore + max 5-char prefix = exactly 32)
-   - Intelligently deduce varchar vs nvarchar based on property type, validators, enum values, etc.
-   - Use `datetimeoffset` (default), `datetime2` (timezone agnostic), or `date`—never `datetime`
-   - Default to `varchar(10)` or `varchar(20)` for enum values
-4. Create appropriate constraints and indexes:
-   - Primary keys: `PK_TableName`
-   - Foreign keys: `FK_ChildTable_ParentTable_ColumnName`
-   - Indexes: `IX_TableName_ColumnName`
-
-5. Migrate existing data:
-   - Use `migrationBuilder.Sql("UPDATE [table] SET [column] = [value] WHERE [condition]")` with care
-6. Use standard SQL Server naming conventions:
-   - Table names should be plural (e.g., `Users`, not `User`)
-   - Constraint and index names should follow the patterns above
+3. Use snake_case naming for everything:
+   - Table names: plural, lowercase (e.g., `users`, `email_logins`, `stripe_events`)
+   - Column names: lowercase with underscores (e.g., `tenant_id`, `created_at`, `email_confirmed`)
+   - C# anonymous type members must also be snake_case (e.g., `tenant_id = table.Column<long>(...)`)
+   - Constraint names: `pk_table_name`, `fk_child_table_parent_table_column_name`, `ix_table_name_column_name`
+
+4. Use appropriate PostgreSQL data types:
+   - Use `text` for all string columns--PostgreSQL stores `text`, `varchar`, and `varchar(N)` identically with no performance difference
+   - Use `timestamptz` for `DateTimeOffset` columns--never `timestamp`, `datetime`, or `datetimeoffset`
+   - Use `boolean` for bool properties
+   - Use `integer` for int properties
+   - Use `bigint` for long properties (e.g., `TenantId`)
+   - Use `numeric(18,2)` for decimal properties and always add `HasPrecision(18, 2)` in the EF Core configuration
+   - Use `jsonb` for columns mapped with `OwnsOne(..., b => b.ToJson())`--Npgsql requires `jsonb`, not `text`, for JSON-mapped owned entities
+   - Enforce length constraints at the application level using FluentValidation, not at the database level
+
+5. Create appropriate constraints and indexes:
+   - Primary keys: `pk_table_name`
+   - Foreign keys: `fk_child_table_parent_table_column_name`
+   - Indexes: `ix_table_name_column_name`
+   - Filtered indexes use PostgreSQL `WHERE` clause syntax (e.g., `filter: "deleted_at IS NULL"`)
+
+6. Migrate existing data:
+   - Use `migrationBuilder.Sql("UPDATE table_name SET column_name = value WHERE condition")` with care
 
 ## Examples
 
@@ -49,76 +58,83 @@ public sealed class AddUserPreferences : Migration
     protected override void Up(MigrationBuilder migrationBuilder)
     {
         migrationBuilder.CreateTable(
-            "UserPreferences",
+            "user_preferences", // ✅ DO: Use snake_case plural table name
             table => new
             {
-                TenantId = table.Column<long>("bigint", nullable: false), // ✅ DO: Add TenantId as first column
-                Id = table.Column<string>("varchar(32)", nullable: false), // ✅ DO: Make Id varchar(32) by default
-                UserId = table.Column<string>("varchar(32)", nullable: false), // ✅ DO: Add Foreginkey before CreatedAt/ModifiedAt
-                CreatedAt = table.Column<DateTimeOffset>("datetimeoffset", nullable: false),
-                ModifiedAt = table.Column<DateTimeOffset>("datetimeoffset", nullable: true),
-                Language = table.Column<string>("varchar(10)", nullable: false) // ✅ DO: Use varchar when colum has known values
+                tenant_id = table.Column<long>("bigint", nullable: false), // ✅ DO: Add tenant_id as first column
+                id = table.Column<string>("text", nullable: false), // ✅ DO: Use text for all string columns
+                user_id = table.Column<string>("text", nullable: false), // ✅ DO: Add foreign key before created_at/modified_at
+                created_at = table.Column<DateTimeOffset>("timestamptz", nullable: false), // ✅ DO: Use timestamptz
+                modified_at = table.Column<DateTimeOffset>("timestamptz", nullable: true),
+                language = table.Column<string>("text", nullable: false) // ✅ DO: Use text for string columns
             },
             constraints: table =>
             {
-                table.PrimaryKey("PK_UserPreferences", x => x.Id);
-                table.ForeignKey("FK_UserPreferences_Users_UserId", x => x.UserId, "Users", "Id");
+                table.PrimaryKey("pk_user_preferences", x => x.id); // ✅ DO: Use pk_table_name
+                table.ForeignKey("fk_user_preferences_users_user_id", x => x.user_id, "users", "id"); // ✅ DO: Use fk_child_parent_column
             }
         );
 
-        migrationBuilder.CreateIndex("IX_UserPreferences_TenantId", "UserPreferences", "TenantId");
-        migrationBuilder.CreateIndex("IX_UserPreferences_UserId", "UserPreferences", "UserId");
+        migrationBuilder.CreateIndex("ix_user_preferences_tenant_id", "user_preferences", "tenant_id"); // ✅ DO: Use ix_table_column
+        migrationBuilder.CreateIndex("ix_user_preferences_user_id", "user_preferences", "user_id");
     }
 }
 
-// ❌ DON'T: Forget to add the attribute [DbContext(typeof(XxxDbContext))] for the self-contained system 
+// ❌ DON'T: Forget to add the attribute [DbContext(typeof(XxxDbContext))] for the self-contained system
 [Migration("20250507_AddUserPrefs")]  // ❌ Missing proper 14-digit timestamp
 public class AddUserPrefsMigration : Migration  // ❌ Not sealed, incorrect naming, suffixed with Migration
 {
     protected override void Up(MigrationBuilder migrationBuilder)
     {
-        // Create UserPreferences table  // ❌ DON'T: Add comments
         migrationBuilder.CreateTable(
-            "UserPreference",   // ❌ DON'T: use singular name for table
+            "UserPreference",   // ❌ DON'T: Use PascalCase or singular name for table
             table => new
             {
-                Id = table.Column<string>("varchar(30)", nullable: false), // ❌ DON'T: Use varchar(30) for ULID
-                Theme = table.Column<string>("varchar(20)", nullable: false),  // ❌ DON'T: Add properties before CreatedAt/ModifiedAt
-                TenantId = table.Column<long>("bigint", nullable: false),  // ❌ TenantId should be first
-                CreatedAt = table.Column<DateTimeOffset>("datetimeoffset", nullable: false),
+                Id = table.Column<string>("varchar(30)", nullable: false), // ❌ DON'T: Use PascalCase column names or varchar(N)--use text instead
+                Theme = table.Column<string>("varchar(20)", nullable: false),  // ❌ DON'T: Add properties before created_at/modified_at or use varchar(N)
+                TenantId = table.Column<long>("bigint", nullable: false),  // ❌ tenant_id should be first, and snake_case
+                CreatedAt = table.Column<DateTimeOffset>("datetimeoffset", nullable: false), // ❌ DON'T: Use SQL Server types
                 ModifiedAt = table.Column<DateTimeOffset>("datetime", nullable: true), // ❌ DON'T: Use datetime
-                UserId = table.Column<string>("varchar(32)", nullable: false),  // ❌ Foreign key after CreatedAt/ModifiedAt
-                Language = table.Column<string>("varchar(10)", nullable: false), // ❌ Trailing comma
+                UserId = table.Column<string>("varchar(32)", nullable: false),  // ❌ Foreign key after created_at/modified_at, use text not varchar
             },
             constraints: table =>
             {
-                table.PrimaryKey("PrimaryKey_UserPreference", i => i.Id);  // ❌ Incorrect PK naming, variable should be x not i
-                table.ForeignKey("ForeignKey_UserPreference_User", x => x.UserId, "Users", "Id");  // ❌ Incorrect FK naming
+                table.PrimaryKey("PK_UserPreference", i => i.Id);  // ❌ PascalCase PK naming, variable should be x not i
+                table.ForeignKey("FK_UserPreference_User", x => x.UserId, "Users", "Id");  // ❌ PascalCase FK naming
             }
         );
     }
-    
+
     protected override void Down(MigrationBuilder migrationBuilder)  // ❌ DON'T: Create a down method
     {
         migrationBuilder.DropTable("UserPreference");
     }
 }
 ```
 
-### Example 2 - Determining column sizes from validators
+### Example 2 - Filtered indexes and data migrations
+
+```csharp
+// ✅ DO: Use PostgreSQL WHERE clause syntax for filtered indexes
+migrationBuilder.CreateIndex("ix_users_tenant_id_email", "users", ["tenant_id", "email"], unique: true, filter: "deleted_at IS NULL");
+migrationBuilder.CreateIndex("ix_subscriptions_stripe_customer_id", "subscriptions", "stripe_customer_id", unique: true, filter: "stripe_customer_id IS NOT NULL");
+
+// ❌ DON'T: Use SQL Server bracket notation
+migrationBuilder.CreateIndex("IX_Users_TenantId_Email", "Users", ["TenantId", "Email"], unique: true, filter: "[DeletedAt] IS NULL");
+```
 
 ```csharp
+// ✅ DO: Use text for string columns, enforce length in validators
 public sealed class UpdateUserValidator : AbstractValidator<UpdateUserCommand>
 {
     public UpdateUserValidator()
     {
-        RuleFor(x => x.TimeZone).NotEmpty().MaximumLength(50); // ✅ DO: Use column sizes based on command validators
+        RuleFor(x => x.TimeZone).NotEmpty().MaximumLength(50);
     }
 }
 
 protected override void Up(MigrationBuilder migrationBuilder)
 {
-    migrationBuilder.AddColumn<string>("TimeZone", "Users", "varchar(50)", nullable: false, defaultValue: "UTC"); // ✅ DO: Match column size to validator
-    // ✅ DO: Consider running complex logic here to update existing records
+    migrationBuilder.AddColumn<string>("time_zone", "users", "text", nullable: false, defaultValue: "UTC");
 }
 ```

.claude/rules/backend/domain-modeling.md

@@ -134,7 +134,6 @@ public sealed class InvoiceConfiguration : IEntityTypeConfiguration<Invoice>
 
         // ✅ DO: Map collection with custom JsonSerializer
         builder.Property(i => i.InvoiceLines)
-            .HasColumnName("InvoiceLines")
             .HasConversion(
                 v => JsonSerializer.Serialize(v.ToArray(), JsonSerializerOptions),
                 v => JsonSerializer.Deserialize<ImmutableArray<InvoiceLine>>(v, JsonSerializerOptions)

.claude/rules/backend/strongly-typed-ids.md

@@ -11,7 +11,7 @@ Guidelines for implementing strongly typed IDs in the backend, covering type saf
 
 1. Use strongly typed IDs to provide type safety and prevent mixing different ID types, improving readability and maintainability
 2. By default, use `StronglyTypedUlid<T>` as the base class—it provides chronological ordering and includes a prefix for easy recognition (e.g., `usr_01JMVAW4T4320KJ3A7EJMCG8R0`)
-3. Use the `[IdPrefix]` attribute with a short prefix (max 5 characters)—ULIDs are 26 chars, plus 5-char prefix and underscore = 32 chars for varchar(32)
+3. Use the `[IdPrefix]` attribute with a short prefix (max 5 characters)—ULIDs are 26 chars, plus 5-char prefix and underscore = 32 chars max
 4. Follow the naming convention `[Entity]Id`
 5. Include the `[JsonConverter]` attribute for proper serialization
 6. Always override `ToString()` in the concrete class—record types don't inherit this from the base class