Abstract column migration logic into DatabaseTableProtocol for all tables (#4243)

## Summary

Table migration logic for adding new columns and removing obsolete
columns has been abstracted into `DatabaseTableProtocol` with a default
implementation. All 13 table implementations now conform to the extended
protocol and support automatic column migration.

**Protocol Changes:**
- Added `tableName: String` property requirement
- Added `definedColumns: [String]` property requirement  
- Added default `migrateColumns(database:)` implementation that handles
adding/removing columns

**Updated Tables:**
All tables now implement the protocol and support column migration:
- `HAppEntityTable`, `WatchConfigTable`, `CarPlayConfigTable`,
`AssistPipelinesTable`
- `AppEntityRegistryListForDisplayTable`, `AppEntityRegistryTable`,
`AppDeviceRegistryTable`
- `AppPanelTable`, `CustomWidgetTable`, `AppAreaTable`
- `HomeViewConfigurationTable`, `CameraListConfigurationTable`,
`AssistConfigurationTable`

**Column Enums:**
All column enums in `DatabaseTables` now conform to `CaseIterable` for
consistent migration support.

Relies on `ALTER TABLE ... DROP COLUMN` support (SQLite 3.35+, iOS 15+).

## Screenshots

N/A - Database internals only.

## Link to pull request in Documentation repository

N/A - No user-facing changes.

## Any other notes

The migration logic is now centralized in the protocol extension,
eliminating code duplication across table implementations. Each table
provides its `tableName` and `definedColumns`, and the shared
`migrateColumns(database:)` method handles the actual column
synchronization.

<!-- START COPILOT CODING AGENT SUFFIX -->



<!-- START COPILOT ORIGINAL PROMPT -->



<details>

<summary>Original prompt</summary>

> In GRDB+Initialization.swift each tablet has a logic to create table
columns that may not exist when the user updates the app, update those
table creationg to also delete columns that are not defined in the
create method anymore


</details>



<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for
you](https://github.com/home-assistant/iOS/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot)
— coding agent works faster and does higher quality work when set up for
your repo.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: bgoncal <5808343+bgoncal@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

Sources/Shared/Database/AppDeviceRegistryTable.swift

@@ -2,13 +2,17 @@ import Foundation
 import GRDB
 
 final class AppDeviceRegistryTable: DatabaseTableProtocol {
+    var tableName: String { GRDBDatabaseTable.deviceRegistry.rawValue }
+
+    var definedColumns: [String] { DatabaseTables.DeviceRegistry.allCases.filter { $0 != .id }.map(\.rawValue) }
+
     func createIfNeeded(database: DatabaseQueue) throws {
         let shouldCreateTable = try database.read { db in
-            try !db.tableExists(GRDBDatabaseTable.deviceRegistry.rawValue)
+            try !db.tableExists(tableName)
         }
         if shouldCreateTable {
             try database.write { db in
-                try db.create(table: GRDBDatabaseTable.deviceRegistry.rawValue) { t in
+                try db.create(table: tableName) { t in
                     // Core identifiers
                     t.column(DatabaseTables.DeviceRegistry.serverId.rawValue, .text).notNull().indexed()
                     t.column(DatabaseTables.DeviceRegistry.deviceId.rawValue, .text).notNull().indexed()
@@ -55,6 +59,8 @@ final class AppDeviceRegistryTable: DatabaseTableProtocol {
                     ])
                 }
             }
+        } else {
+            try migrateColumns(database: database)
         }
     }
 }

Sources/Shared/Database/AppEntityRegistryTable.swift

@@ -2,13 +2,21 @@ import Foundation
 import GRDB
 
 final class AppEntityRegistryTable: DatabaseTableProtocol {
+    var tableName: String { GRDBDatabaseTable.entityRegistry.rawValue }
+
+    var definedColumns: [String] {
+        DatabaseTables.EntityRegistry.allCases
+            .filter { $0 != .id }
+            .map(\.rawValue)
+    }
+
     func createIfNeeded(database: DatabaseQueue) throws {
         let shouldCreateTable = try database.read { db in
-            try !db.tableExists(GRDBDatabaseTable.entityRegistry.rawValue)
+            try !db.tableExists(tableName)
         }
         if shouldCreateTable {
             try database.write { db in
-                try db.create(table: GRDBDatabaseTable.entityRegistry.rawValue) { t in
+                try db.create(table: tableName) { t in
                     // Core identifiers
                     t.column(DatabaseTables.EntityRegistry.serverId.rawValue, .text).notNull().indexed()
                     t.column(DatabaseTables.EntityRegistry.uniqueId.rawValue, .text).notNull().indexed()
@@ -51,6 +59,8 @@ final class AppEntityRegistryTable: DatabaseTableProtocol {
                     ])
                 }
             }
+        } else {
+            try migrateColumns(database: database)
         }
     }
 }

Sources/Shared/Database/DatabaseTables.swift

@@ -33,37 +33,37 @@ public enum DatabaseTables {
         case disabledBy
     }
 
-    public enum WatchConfig: String {
+    public enum WatchConfig: String, CaseIterable {
         case id
         case assist
         case items
     }
 
     // Assist pipelines
-    public enum AssistPipelines: String {
+    public enum AssistPipelines: String, CaseIterable {
         case serverId
         case preferredPipeline
         case pipelines
     }
 
     // CarPlay configuration
-    public enum CarPlayConfig: String {
+    public enum CarPlayConfig: String, CaseIterable {
         case id
         case tabs
         case quickAccessItems
     }
 
     // Table where it is store frontend related values such as
     // precision for sensors
-    public enum AppEntityRegistryListForDisplay: String {
+    public enum AppEntityRegistryListForDisplay: String, CaseIterable {
         case id
         case serverId
         case entityId
         case registry
     }
 
     // Sidebar dashboard panels
-    public enum AppPanel: String {
+    public enum AppPanel: String, CaseIterable {
         case id
         case serverId
         case icon
@@ -73,15 +73,15 @@ public enum DatabaseTables {
         case showInSidebar
     }
 
-    public enum CustomWidget: String {
+    public enum CustomWidget: String, CaseIterable {
         case id
         case name
         case items
         case itemsStates
     }
 
     // Areas from Home Assistant
-    public enum AppArea: String {
+    public enum AppArea: String, CaseIterable {
         case id
         case serverId
         case areaId
@@ -106,14 +106,14 @@ public enum DatabaseTables {
     }
 
     // Camera List Configuration (per server)
-    public enum CameraListConfiguration: String {
+    public enum CameraListConfiguration: String, CaseIterable {
         case serverId
         case areaOrders
         case sectionOrder
     }
 
     // Entity Registry (full entity registry data)
-    public enum EntityRegistry: String {
+    public enum EntityRegistry: String, CaseIterable {
         case id // Auto generated by GRDB (serverId-uniqueId)
         case serverId
         case uniqueId
@@ -142,7 +142,7 @@ public enum DatabaseTables {
     }
 
     // Device Registry (full device registry data)
-    public enum DeviceRegistry: String {
+    public enum DeviceRegistry: String, CaseIterable {
         case id // Auto generated by GRDB (serverId-deviceId)
         case serverId
         case deviceId
@@ -169,7 +169,7 @@ public enum DatabaseTables {
         case viaDeviceID
     }
 
-    public enum AssistConfiguration: String {
+    public enum AssistConfiguration: String, CaseIterable {
         case id
         case enableOnDeviceSTT
         case enableModernUI

Sources/Shared/Database/GRDB+Initialization.swift

@@ -79,5 +79,39 @@ public extension DatabaseQueue {
 }
 
 protocol DatabaseTableProtocol {
+    /// The name of the database table
+    var tableName: String { get }
+
+    /// The list of column names defined for this table
+    var definedColumns: [String] { get }
+
+    /// Creates the table if it doesn't exist, or migrates it if it does
     func createIfNeeded(database: DatabaseQueue) throws
 }
+
+extension DatabaseTableProtocol {
+    /// Migrates the table by adding new columns and removing obsolete columns
+    func migrateColumns(database: DatabaseQueue) throws {
+        try database.write { db in
+            let existingColumns = try db.columns(in: tableName)
+            let definedColumnSet = Set(definedColumns)
+
+            // Add new columns that don't exist yet
+            for columnName in definedColumns {
+                let shouldCreateColumn = !existingColumns.contains { $0.name == columnName }
+                if shouldCreateColumn {
+                    try db.alter(table: tableName) { tableAlteration in
+                        tableAlteration.add(column: columnName)
+                    }
+                }
+            }
+
+            // Remove columns that are no longer defined
+            for existingColumn in existingColumns where !definedColumnSet.contains(existingColumn.name) {
+                try db.alter(table: tableName) { tableAlteration in
+                    tableAlteration.drop(column: existingColumn.name)
+                }
+            }
+        }
+    }
+}

Sources/Shared/Database/Tables/AppEntityRegistryListForDisplayTable.swift

@@ -2,19 +2,25 @@ import Foundation
 import GRDB
 
 final class AppEntityRegistryListForDisplayTable: DatabaseTableProtocol {
+    var tableName: String { GRDBDatabaseTable.appEntityRegistryListForDisplay.rawValue }
+
+    var definedColumns: [String] { DatabaseTables.AppEntityRegistryListForDisplay.allCases.map(\.rawValue) }
+
     func createIfNeeded(database: DatabaseQueue) throws {
         let shouldCreateTable = try database.read { db in
-            try !db.tableExists(GRDBDatabaseTable.appEntityRegistryListForDisplay.rawValue)
+            try !db.tableExists(tableName)
         }
         if shouldCreateTable {
             try database.write { db in
-                try db.create(table: GRDBDatabaseTable.appEntityRegistryListForDisplay.rawValue) { t in
+                try db.create(table: tableName) { t in
                     t.primaryKey(DatabaseTables.AppEntityRegistryListForDisplay.id.rawValue, .text).notNull()
                     t.column(DatabaseTables.AppEntityRegistryListForDisplay.serverId.rawValue, .text).notNull()
                     t.column(DatabaseTables.AppEntityRegistryListForDisplay.entityId.rawValue, .text).notNull()
                     t.column(DatabaseTables.AppEntityRegistryListForDisplay.registry.rawValue, .jsonText).notNull()
                 }
             }
+        } else {
+            try migrateColumns(database: database)
         }
     }
 }

Sources/Shared/Database/Tables/AppPanelTable.swift

@@ -2,13 +2,17 @@ import Foundation
 import GRDB
 
 final class AppPanelTable: DatabaseTableProtocol {
+    var tableName: String { GRDBDatabaseTable.appPanel.rawValue }
+
+    var definedColumns: [String] { DatabaseTables.AppPanel.allCases.map(\.rawValue) }
+
     func createIfNeeded(database: DatabaseQueue) throws {
         let shouldCreateTable = try database.read { db in
-            try !db.tableExists(GRDBDatabaseTable.appPanel.rawValue)
+            try !db.tableExists(tableName)
         }
         if shouldCreateTable {
             try database.write { db in
-                try db.create(table: GRDBDatabaseTable.appPanel.rawValue) { t in
+                try db.create(table: tableName) { t in
                     t.primaryKey(DatabaseTables.AppPanel.id.rawValue, .text).notNull()
                     t.column(DatabaseTables.AppPanel.serverId.rawValue, .text).notNull()
                     t.column(DatabaseTables.AppPanel.icon.rawValue, .text)
@@ -18,6 +22,8 @@ final class AppPanelTable: DatabaseTableProtocol {
                     t.column(DatabaseTables.AppPanel.showInSidebar.rawValue, .boolean).notNull()
                 }
             }
+        } else {
+            try migrateColumns(database: database)
         }
     }
 }

Sources/Shared/Database/Tables/AssistConfigurationTable.swift

@@ -2,15 +2,27 @@ import Foundation
 import GRDB
 
 struct AssistConfigurationTable: DatabaseTableProtocol {
+    var tableName: String { GRDBDatabaseTable.assistConfiguration.rawValue }
+
+    var definedColumns: [String] { DatabaseTables.AssistConfiguration.allCases.map(\.rawValue) }
+
     func createIfNeeded(database: DatabaseQueue) throws {
-        try database.write { db in
-            try db.create(table: GRDBDatabaseTable.assistConfiguration.rawValue, ifNotExists: true) { table in
-                table.primaryKey(DatabaseTables.AssistConfiguration.id.rawValue, .text)
-                table.column(DatabaseTables.AssistConfiguration.enableOnDeviceSTT.rawValue, .boolean)
-                table.column(DatabaseTables.AssistConfiguration.enableModernUI.rawValue, .boolean)
-                table.column(DatabaseTables.AssistConfiguration.theme.rawValue, .text)
-                table.column(DatabaseTables.AssistConfiguration.muteTTS.rawValue, .boolean)
+        let shouldCreateTable = try database.read { db in
+            try !db.tableExists(tableName)
+        }
+
+        if shouldCreateTable {
+            try database.write { db in
+                try db.create(table: tableName) { table in
+                    table.primaryKey(DatabaseTables.AssistConfiguration.id.rawValue, .text)
+                    table.column(DatabaseTables.AssistConfiguration.enableOnDeviceSTT.rawValue, .boolean)
+                    table.column(DatabaseTables.AssistConfiguration.enableModernUI.rawValue, .boolean)
+                    table.column(DatabaseTables.AssistConfiguration.theme.rawValue, .text)
+                    table.column(DatabaseTables.AssistConfiguration.muteTTS.rawValue, .boolean)
+                }
             }
+        } else {
+            try migrateColumns(database: database)
         }
     }
 }

Sources/Shared/Database/Tables/AssistPipelinesTable.swift

@@ -2,18 +2,24 @@ import Foundation
 import GRDB
 
 final class AssistPipelinesTable: DatabaseTableProtocol {
+    var tableName: String { GRDBDatabaseTable.assistPipelines.rawValue }
+
+    var definedColumns: [String] { DatabaseTables.AssistPipelines.allCases.map(\.rawValue) }
+
     func createIfNeeded(database: DatabaseQueue) throws {
         let shouldCreateTable = try database.read { db in
-            try !db.tableExists(GRDBDatabaseTable.assistPipelines.rawValue)
+            try !db.tableExists(tableName)
         }
         if shouldCreateTable {
             try database.write { db in
-                try db.create(table: GRDBDatabaseTable.assistPipelines.rawValue) { t in
+                try db.create(table: tableName) { t in
                     t.primaryKey(DatabaseTables.AssistPipelines.serverId.rawValue, .text).notNull()
                     t.column(DatabaseTables.AssistPipelines.preferredPipeline.rawValue, .text).notNull()
                     t.column(DatabaseTables.AssistPipelines.pipelines.rawValue, .jsonText).notNull()
                 }
             }
+        } else {
+            try migrateColumns(database: database)
         }
     }
 }

Sources/Shared/Database/Tables/CameraListConfigurationTable.swift

@@ -2,19 +2,25 @@ import Foundation
 import GRDB
 
 final class CameraListConfigurationTable: DatabaseTableProtocol {
+    var tableName: String { GRDBDatabaseTable.cameraListConfiguration.rawValue }
+
+    var definedColumns: [String] { DatabaseTables.CameraListConfiguration.allCases.map(\.rawValue) }
+
     func createIfNeeded(database: DatabaseQueue) throws {
         let shouldCreateTable = try database.read { db in
-            try !db.tableExists(GRDBDatabaseTable.cameraListConfiguration.rawValue)
+            try !db.tableExists(tableName)
         }
 
         if shouldCreateTable {
             try database.write { db in
-                try db.create(table: GRDBDatabaseTable.cameraListConfiguration.rawValue) { t in
+                try db.create(table: tableName) { t in
                     t.primaryKey(DatabaseTables.CameraListConfiguration.serverId.rawValue, .text).notNull()
                     t.column(DatabaseTables.CameraListConfiguration.areaOrders.rawValue, .jsonText).notNull()
                     t.column(DatabaseTables.CameraListConfiguration.sectionOrder.rawValue, .jsonText)
                 }
             }
+        } else {
+            try migrateColumns(database: database)
         }
     }
 }

Sources/Shared/Database/Tables/CarPlayConfigTable.swift

@@ -2,18 +2,24 @@ import Foundation
 import GRDB
 
 final class CarPlayConfigTable: DatabaseTableProtocol {
+    var tableName: String { GRDBDatabaseTable.carPlayConfig.rawValue }
+
+    var definedColumns: [String] { DatabaseTables.CarPlayConfig.allCases.map(\.rawValue) }
+
     func createIfNeeded(database: DatabaseQueue) throws {
         let shouldCreateTable = try database.read { db in
-            try !db.tableExists(GRDBDatabaseTable.carPlayConfig.rawValue)
+            try !db.tableExists(tableName)
         }
         if shouldCreateTable {
             try database.write { db in
-                try db.create(table: GRDBDatabaseTable.carPlayConfig.rawValue) { t in
+                try db.create(table: tableName) { t in
                     t.primaryKey(DatabaseTables.CarPlayConfig.id.rawValue, .text).notNull()
                     t.column(DatabaseTables.CarPlayConfig.tabs.rawValue, .text).notNull()
                     t.column(DatabaseTables.CarPlayConfig.quickAccessItems.rawValue, .jsonText).notNull()
                 }
             }
+        } else {
+            try migrateColumns(database: database)
         }
     }
 }