feat: add iCloud sync for SSH profiles and documentation

- Add SyncRecordType.sshProfile with CKRecord mapping
- Add syncSSHProfiles toggle to SyncSettings
- Add sync tracking (markDirty/markDeleted) in SSHProfileStorage
- Add saveProfilesWithoutSync for applying remote changes
- Update SyncCoordinator: push, pull, delete, conflict handling
- Handle .sshProfile in ConflictResolutionView
- Add SSH Profiles feature docs (EN/VI/ZH)
- Update SSH Tunneling docs with link to profiles
- Update docs.json navigation

Author: datlechin

TablePro/Core/Storage/SSHProfileStorage.swift

@@ -42,6 +42,17 @@ final class SSHProfileStorage {
             Self.logger.warning("Refusing to save SSH profiles: previous load failed (would overwrite existing data)")
             return
         }
+        do {
+            let data = try encoder.encode(profiles)
+            defaults.set(data, forKey: profilesKey)
+            SyncChangeTracker.shared.markDirty(.sshProfile, ids: profiles.map { $0.id.uuidString })
+        } catch {
+            Self.logger.error("Failed to save SSH profiles: \(error)")
+        }
+    }
+
+    func saveProfilesWithoutSync(_ profiles: [SSHProfile]) {
+        guard !lastLoadFailed else { return }
         do {
             let data = try encoder.encode(profiles)
             defaults.set(data, forKey: profilesKey)
@@ -67,6 +78,7 @@ final class SSHProfileStorage {
     }
 
     func deleteProfile(_ profile: SSHProfile) {
+        SyncChangeTracker.shared.markDeleted(.sshProfile, id: profile.id.uuidString)
         var profiles = loadProfiles()
         guard !lastLoadFailed else { return }
         profiles.removeAll { $0.id == profile.id }

TablePro/Core/Sync/SyncCoordinator.swift

@@ -146,12 +146,17 @@ final class SyncCoordinator {
             changeTracker.markDirty(.tag, id: tag.id.uuidString)
         }
 
+        let sshProfiles = SSHProfileStorage.shared.loadProfiles()
+        for profile in sshProfiles {
+            changeTracker.markDirty(.sshProfile, id: profile.id.uuidString)
+        }
+
         // Mark all settings categories as dirty
         for category in ["general", "appearance", "editor", "dataGrid", "history", "tabs", "keyboard", "ai"] {
             changeTracker.markDirty(.settings, id: category)
         }
 
-        Self.logger.info("Marked all local data dirty: \(connections.count) connections, \(groups.count) groups, \(tags.count) tags, 8 settings categories")
+        Self.logger.info("Marked all local data dirty: \(connections.count) connections, \(groups.count) groups, \(tags.count) tags, \(sshProfiles.count) SSH profiles, 8 settings categories")
     }
 
     /// Called when user disables sync in settings
@@ -254,6 +259,11 @@ final class SyncCoordinator {
             collectDirtyTags(into: &recordsToSave, deletions: &recordIDsToDelete, zoneID: zoneID)
         }
 
+        // Collect dirty SSH profiles
+        if settings.syncSSHProfiles {
+            collectDirtySSHProfiles(into: &recordsToSave, deletions: &recordIDsToDelete, zoneID: zoneID)
+        }
+
         // Collect unsynced query history
         if settings.syncQueryHistory {
             let limit = settings.historySyncLimit.limit ?? Int.max
@@ -301,6 +311,9 @@ final class SyncCoordinator {
                 changeTracker.clearAllDirty(.group)
                 changeTracker.clearAllDirty(.tag)
             }
+            if settings.syncSSHProfiles {
+                changeTracker.clearAllDirty(.sshProfile)
+            }
             if settings.syncSettings {
                 changeTracker.clearAllDirty(.settings)
             }
@@ -322,6 +335,11 @@ final class SyncCoordinator {
                     metadataStorage.removeTombstone(type: .tag, id: tombstone.id)
                 }
             }
+            if settings.syncSSHProfiles {
+                for tombstone in metadataStorage.tombstones(for: .sshProfile) {
+                    metadataStorage.removeTombstone(type: .sshProfile, id: tombstone.id)
+                }
+            }
             if settings.syncSettings {
                 for tombstone in metadataStorage.tombstones(for: .settings) {
                     metadataStorage.removeTombstone(type: .settings, id: tombstone.id)
@@ -416,6 +434,8 @@ final class SyncCoordinator {
             case SyncRecordType.tag.rawValue where settings.syncGroupsAndTags:
                 applyRemoteTag(record)
                 groupsOrTagsChanged = true
+            case SyncRecordType.sshProfile.rawValue where settings.syncSSHProfiles:
+                applyRemoteSSHProfile(record)
             case SyncRecordType.settings.rawValue where settings.syncSettings:
                 applyRemoteSettings(record)
             case SyncRecordType.queryHistory.rawValue where settings.syncQueryHistory:
@@ -494,6 +514,18 @@ final class SyncCoordinator {
         TagStorage.shared.saveTags(tags)
     }
 
+    private func applyRemoteSSHProfile(_ record: CKRecord) {
+        guard let remoteProfile = SyncRecordMapper.toSSHProfile(record) else { return }
+
+        var profiles = SSHProfileStorage.shared.loadProfiles()
+        if let index = profiles.firstIndex(where: { $0.id == remoteProfile.id }) {
+            profiles[index] = remoteProfile
+        } else {
+            profiles.append(remoteProfile)
+        }
+        SSHProfileStorage.shared.saveProfilesWithoutSync(profiles)
+    }
+
     private func applyRemoteSettings(_ record: CKRecord) {
         guard let category = SyncRecordMapper.settingsCategory(from: record),
               let data = SyncRecordMapper.settingsData(from: record)
@@ -561,6 +593,15 @@ final class SyncCoordinator {
                 TagStorage.shared.saveTags(tags)
             }
         }
+
+        if recordName.hasPrefix("SSHProfile_") {
+            let uuidString = String(recordName.dropFirst("SSHProfile_".count))
+            if let uuid = UUID(uuidString: uuidString) {
+                var profiles = SSHProfileStorage.shared.loadProfiles()
+                profiles.removeAll { $0.id == uuid }
+                SSHProfileStorage.shared.saveProfilesWithoutSync(profiles)
+            }
+        }
     }
 
     // MARK: - Observers
@@ -654,6 +695,7 @@ final class SyncCoordinator {
             case SyncRecordType.tag.rawValue: syncRecordType = .tag
             case SyncRecordType.settings.rawValue: syncRecordType = .settings
             case SyncRecordType.queryHistory.rawValue: syncRecordType = .queryHistory
+            case SyncRecordType.sshProfile.rawValue: syncRecordType = .sshProfile
             default: continue
             }
 
@@ -786,4 +828,26 @@ final class SyncCoordinator {
             )
         }
     }
+
+    private func collectDirtySSHProfiles(
+        into records: inout [CKRecord],
+        deletions: inout [CKRecord.ID],
+        zoneID: CKRecordZone.ID
+    ) {
+        let dirtyProfileIds = changeTracker.dirtyRecords(for: .sshProfile)
+        if !dirtyProfileIds.isEmpty {
+            let profiles = SSHProfileStorage.shared.loadProfiles()
+            for id in dirtyProfileIds {
+                if let profile = profiles.first(where: { $0.id.uuidString == id }) {
+                    records.append(SyncRecordMapper.toCKRecord(profile, in: zoneID))
+                }
+            }
+        }
+
+        for tombstone in metadataStorage.tombstones(for: .sshProfile) {
+            deletions.append(
+                SyncRecordMapper.recordID(type: .sshProfile, id: tombstone.id, in: zoneID)
+            )
+        }
+    }
 }

TablePro/Core/Sync/SyncRecordMapper.swift

@@ -18,6 +18,7 @@ enum SyncRecordType: String, CaseIterable {
     case queryHistory = "QueryHistory"
     case favorite = "SQLFavorite"
     case favoriteFolder = "SQLFavoriteFolder"
+    case sshProfile = "SSHProfile"
 }
 
 /// Pure-function mapper between local models and CKRecord
@@ -44,6 +45,7 @@ struct SyncRecordMapper {
         case .queryHistory: recordName = "History_\(id)"
         case .favorite: recordName = "Favorite_\(id)"
         case .favoriteFolder: recordName = "FavoriteFolder_\(id)"
+        case .sshProfile: recordName = "SSHProfile_\(id)"
         }
         return CKRecord.ID(recordName: recordName, zoneID: zone)
     }
@@ -311,4 +313,82 @@ struct SyncRecordMapper {
 
         return record
     }
+
+    // MARK: - SSH Profile
+
+    static func toCKRecord(_ profile: SSHProfile, in zone: CKRecordZone.ID) -> CKRecord {
+        let recordID = recordID(type: .sshProfile, id: profile.id.uuidString, in: zone)
+        let record = CKRecord(recordType: SyncRecordType.sshProfile.rawValue, recordID: recordID)
+
+        record["profileId"] = profile.id.uuidString as CKRecordValue
+        record["name"] = profile.name as CKRecordValue
+        record["host"] = profile.host as CKRecordValue
+        record["port"] = Int64(profile.port) as CKRecordValue
+        record["username"] = profile.username as CKRecordValue
+        record["authMethod"] = profile.authMethod.rawValue as CKRecordValue
+        record["privateKeyPath"] = profile.privateKeyPath as CKRecordValue
+        record["useSSHConfig"] = Int64(profile.useSSHConfig ? 1 : 0) as CKRecordValue
+        record["agentSocketPath"] = profile.agentSocketPath as CKRecordValue
+        record["totpMode"] = profile.totpMode.rawValue as CKRecordValue
+        record["totpAlgorithm"] = profile.totpAlgorithm.rawValue as CKRecordValue
+        record["totpDigits"] = Int64(profile.totpDigits) as CKRecordValue
+        record["totpPeriod"] = Int64(profile.totpPeriod) as CKRecordValue
+        record["modifiedAtLocal"] = Date() as CKRecordValue
+        record["schemaVersion"] = schemaVersion as CKRecordValue
+
+        if !profile.jumpHosts.isEmpty {
+            do {
+                let jumpHostsData = try encoder.encode(profile.jumpHosts)
+                record["jumpHostsJson"] = jumpHostsData as CKRecordValue
+            } catch {
+                logger.warning("Failed to encode jump hosts for sync: \(error.localizedDescription)")
+            }
+        }
+
+        return record
+    }
+
+    static func toSSHProfile(_ record: CKRecord) -> SSHProfile? {
+        guard let profileIdString = record["profileId"] as? String,
+              let profileId = UUID(uuidString: profileIdString),
+              let name = record["name"] as? String
+        else {
+            logger.warning("Failed to decode SSH profile from CKRecord: missing required fields")
+            return nil
+        }
+
+        let host = record["host"] as? String ?? ""
+        let port = (record["port"] as? Int64).map { Int($0) } ?? 22
+        let username = record["username"] as? String ?? ""
+        let authMethodRaw = record["authMethod"] as? String ?? SSHAuthMethod.password.rawValue
+        let privateKeyPath = record["privateKeyPath"] as? String ?? ""
+        let useSSHConfig = (record["useSSHConfig"] as? Int64 ?? 1) != 0
+        let agentSocketPath = record["agentSocketPath"] as? String ?? ""
+        let totpModeRaw = record["totpMode"] as? String ?? TOTPMode.none.rawValue
+        let totpAlgorithmRaw = record["totpAlgorithm"] as? String ?? TOTPAlgorithm.sha1.rawValue
+        let totpDigits = (record["totpDigits"] as? Int64).map { Int($0) } ?? 6
+        let totpPeriod = (record["totpPeriod"] as? Int64).map { Int($0) } ?? 30
+
+        var jumpHosts: [SSHJumpHost] = []
+        if let jumpHostsData = record["jumpHostsJson"] as? Data {
+            jumpHosts = (try? decoder.decode([SSHJumpHost].self, from: jumpHostsData)) ?? []
+        }
+
+        return SSHProfile(
+            id: profileId,
+            name: name,
+            host: host,
+            port: port,
+            username: username,
+            authMethod: SSHAuthMethod(rawValue: authMethodRaw) ?? .password,
+            privateKeyPath: privateKeyPath,
+            useSSHConfig: useSSHConfig,
+            agentSocketPath: agentSocketPath,
+            jumpHosts: jumpHosts,
+            totpMode: TOTPMode(rawValue: totpModeRaw) ?? .none,
+            totpAlgorithm: TOTPAlgorithm(rawValue: totpAlgorithmRaw) ?? .sha1,
+            totpDigits: totpDigits,
+            totpPeriod: totpPeriod
+        )
+    }
 }

TablePro/Models/Settings/SyncSettings.swift

@@ -16,6 +16,7 @@ struct SyncSettings: Codable, Equatable {
     var syncQueryHistory: Bool
     var historySyncLimit: HistorySyncLimit
     var syncPasswords: Bool
+    var syncSSHProfiles: Bool
 
     init(
         enabled: Bool,
@@ -24,7 +25,8 @@ struct SyncSettings: Codable, Equatable {
         syncSettings: Bool,
         syncQueryHistory: Bool,
         historySyncLimit: HistorySyncLimit,
-        syncPasswords: Bool = false
+        syncPasswords: Bool = false,
+        syncSSHProfiles: Bool = true
     ) {
         self.enabled = enabled
         self.syncConnections = syncConnections
@@ -33,6 +35,7 @@ struct SyncSettings: Codable, Equatable {
         self.syncQueryHistory = syncQueryHistory
         self.historySyncLimit = historySyncLimit
         self.syncPasswords = syncPasswords
+        self.syncSSHProfiles = syncSSHProfiles
     }
 
     init(from decoder: Decoder) throws {
@@ -44,6 +47,7 @@ struct SyncSettings: Codable, Equatable {
         syncQueryHistory = try container.decode(Bool.self, forKey: .syncQueryHistory)
         historySyncLimit = try container.decode(HistorySyncLimit.self, forKey: .historySyncLimit)
         syncPasswords = try container.decodeIfPresent(Bool.self, forKey: .syncPasswords) ?? false
+        syncSSHProfiles = try container.decodeIfPresent(Bool.self, forKey: .syncSSHProfiles) ?? true
     }
 
     static let `default` = SyncSettings(
@@ -53,7 +57,8 @@ struct SyncSettings: Codable, Equatable {
         syncSettings: true,
         syncQueryHistory: true,
         historySyncLimit: .entries500,
-        syncPasswords: false
+        syncPasswords: false,
+        syncSSHProfiles: true
     )
 }
 

TablePro/Views/Components/ConflictResolutionView.swift

@@ -142,6 +142,13 @@ struct ConflictResolutionView: View {
             if let name = record["name"] as? String {
                 fieldRow(label: String(localized: "Name"), value: name)
             }
+        case .sshProfile:
+            if let name = record["name"] as? String {
+                fieldRow(label: String(localized: "Name"), value: name)
+            }
+            if let host = record["host"] as? String {
+                fieldRow(label: "Host", value: host)
+            }
         }
     }
 

TablePro/Views/Settings/SyncSettingsView.swift

@@ -131,6 +131,9 @@ struct SyncSettingsView: View {
             Toggle("Groups & Tags:", isOn: $syncSettings.syncGroupsAndTags)
                 .onChange(of: syncSettings.syncGroupsAndTags) { _, _ in persistSettings() }
 
+            Toggle("SSH Profiles:", isOn: $syncSettings.syncSSHProfiles)
+                .onChange(of: syncSettings.syncSSHProfiles) { _, _ in persistSettings() }
+
             Toggle("Settings:", isOn: $syncSettings.syncSettings)
                 .onChange(of: syncSettings.syncSettings) { _, _ in persistSettings() }
 

docs/databases/ssh-tunneling.mdx

@@ -7,6 +7,10 @@ description: Route database connections through an encrypted SSH tunnel to reach
 
 SSH tunneling routes your database connection through an encrypted tunnel to reach servers that aren't directly accessible from your Mac. TablePro manages the tunnel lifecycle, including keep-alive and auto-reconnect.
 
+<Tip>
+If you connect to multiple databases through the same SSH server, you can save your SSH configuration as a reusable profile. See [SSH Profiles](/features/ssh-profiles).
+</Tip>
+
 ## How SSH Tunneling Works
 
 ```mermaid

docs/docs.json

@@ -65,7 +65,8 @@
                   "features/keyboard-shortcuts",
                   "features/deep-links",
                   "features/safe-mode",
-                  "features/icloud-sync"
+                  "features/icloud-sync",
+                  "features/ssh-profiles"
                 ]
               },
               {
@@ -161,7 +162,8 @@
                   "vi/features/keyboard-shortcuts",
                   "vi/features/deep-links",
                   "vi/features/safe-mode",
-                  "vi/features/icloud-sync"
+                  "vi/features/icloud-sync",
+                  "vi/features/ssh-profiles"
                 ]
               },
               {
@@ -262,7 +264,8 @@
                   "zh/features/keyboard-shortcuts",
                   "zh/features/deep-links",
                   "zh/features/safe-mode",
-                  "zh/features/icloud-sync"
+                  "zh/features/icloud-sync",
+                  "zh/features/ssh-profiles"
                 ]
               },
               {