feat: ER diagram visualization with Sugiyama layout

.gitignore

@@ -142,3 +142,4 @@ build/
 # Static libraries (downloaded from GitHub Releases via scripts/download-libs.sh)
 Libs/*.a
 Libs/.downloaded
+Libs/ios/

CHANGELOG.md

@@ -9,11 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Space key toggles FK preview popover on selected cell, rebindable in Settings > Keyboard (#648)
+- ER diagram with interactive layout, crow's foot notation, and PNG export (#186)
+- Space key toggles FK preview popover (#648)
 
 ### Fixed
 
-- Accept SQLAlchemy-style connection URLs with driver hints (e.g., `postgresql+psycopg://`) (#642)
+- Accept SQLAlchemy-style connection URLs with driver hints (#642)
 
 ## [0.29.0] - 2026-04-09
 

CLAUDE.md

@@ -9,7 +9,7 @@ TablePro is a native macOS database client (SwiftUI + AppKit) — a fast, lightw
 - **Source**: `TablePro/` — `Core/` (business logic, services), `Views/` (UI), `Models/` (data structures), `ViewModels/`, `Extensions/`, `Theme/`
 - **Plugins**: `Plugins/` — `.tableplugin` bundles + `TableProPluginKit` shared framework. Built-in (bundled in app): MySQL, PostgreSQL, SQLite, ClickHouse, MSSQL, Redis, CSV, JSON, SQL export, MQL. Separately distributed via plugin registry: MongoDB, Oracle, DuckDB, Cassandra, Etcd, CloudflareD1, DynamoDB, BigQuery
 - **C bridges**: Each plugin contains its own C bridge module (e.g., `Plugins/MySQLDriverPlugin/CMariaDB/`, `Plugins/PostgreSQLDriverPlugin/CLibPQ/`)
-- **Static libs**: `Libs/` — pre-built `libmariadb*.a`, `libpq*.a`, etc. Downloaded from GitHub Releases via `scripts/download-libs.sh` (not in git)
+- **Static libs**: `Libs/` — pre-built `libmariadb*.a`, `libpq*.a`, etc. `Libs/ios/` — xcframeworks for iOS (Hiredis, LibPQ, MariaDB, OpenSSL, LibSSH2). Both downloaded from GitHub Releases via `scripts/download-libs.sh` (not in git)
 - **SPM deps**: CodeEditSourceEditor (`main` branch, tree-sitter editor), Sparkle (2.8.1, auto-update), OracleNIO. Managed via Xcode, no `Package.swift`.
 
 ## Build & Development Commands
@@ -58,6 +58,10 @@ tar czf /tmp/tablepro-libs-v1.tar.gz -C Libs .
 gh release upload libs-v1 /tmp/tablepro-libs-v1.tar.gz --clobber --repo TableProApp/TablePro
 # 4. Commit the updated checksums
 git add Libs/checksums.sha256 && git commit -m "build: update static library checksums"
+
+# iOS xcframeworks (Libs/ios/*.xcframework)
+tar czf /tmp/tablepro-libs-ios-v1.tar.gz -C Libs/ios .
+gh release upload libs-v1 /tmp/tablepro-libs-ios-v1.tar.gz --clobber --repo TableProApp/TablePro
 ```
 
 ## Architecture

Packages/TableProCore/Sources/TableProPluginKit/PluginForeignKeyInfo.swift

@@ -5,6 +5,7 @@ public struct PluginForeignKeyInfo: Codable, Sendable {
     public let column: String
     public let referencedTable: String
     public let referencedColumn: String
+    public let referencedSchema: String?
     public let onDelete: String
     public let onUpdate: String
 
@@ -13,13 +14,15 @@ public struct PluginForeignKeyInfo: Codable, Sendable {
         column: String,
         referencedTable: String,
         referencedColumn: String,
+        referencedSchema: String? = nil,
         onDelete: String = "NO ACTION",
         onUpdate: String = "NO ACTION"
     ) {
         self.name = name
         self.column = column
         self.referencedTable = referencedTable
         self.referencedColumn = referencedColumn
+        self.referencedSchema = referencedSchema
         self.onDelete = onDelete
         self.onUpdate = onUpdate
     }

TablePro/Core/Services/Infrastructure/SessionStateFactory.swift

@@ -93,6 +93,11 @@ enum SessionStateFactory {
                     tabMgr.addCreateTableTab(
                         databaseName: payload.databaseName ?? connection.database
                     )
+                case .erDiagram:
+                    tabMgr.addERDiagramTab(
+                        schemaKey: payload.erDiagramSchemaKey ?? payload.databaseName ?? connection.database,
+                        databaseName: payload.databaseName ?? connection.database
+                    )
                 }
             case .newEmptyTab:
                 tabMgr.addTab(databaseName: payload.databaseName ?? connection.database)

TablePro/Core/Services/Query/QueryPlanParser.swift

@@ -224,7 +224,7 @@ struct SQLitePlanParser: QueryPlanParser {
                 nodes.append((id: id, parent: parent, detail: parts[3].trimmingCharacters(in: .whitespaces)))
             } else {
                 // Fallback: treat entire line as a detail node
-                nodes.append((id: nodes.count, parent: nodes.isEmpty ? -1 : 0, detail: line))
+                nodes.append((id: nodes.count, parent: -1, detail: line))
             }
         }
 

TablePro/Core/Storage/ConnectionStorage.swift

@@ -41,6 +41,19 @@ final class ConnectionStorage {
             let connections = storedConnections.map { stored in
                 stored.toConnection()
             }
+
+            // Migration: assign sortOrder from array position for pre-existing data
+            if connections.count > 1 && connections.allSatisfy({ $0.sortOrder == 0 }) {
+                var migrated = connections
+                for i in migrated.indices { migrated[i].sortOrder = i }
+                let migratedStored = migrated.map { StoredConnection(from: $0) }
+                if let data = try? encoder.encode(migratedStored) {
+                    defaults.set(data, forKey: connectionsKey)
+                }
+                cachedConnections = migrated
+                return migrated
+            }
+
             cachedConnections = connections
             return connections
         } catch {
@@ -371,6 +384,9 @@ private struct StoredConnection: Codable {
     // Startup commands
     let startupCommands: String?
 
+    // Sort order for sync
+    let sortOrder: Int
+
     // TOTP configuration
     let totpMode: String
     let totpAlgorithm: String
@@ -440,6 +456,9 @@ private struct StoredConnection: Codable {
         // Startup commands
         self.startupCommands = connection.startupCommands
 
+        // Sort order
+        self.sortOrder = connection.sortOrder
+
         // Plugin-driven additional fields
         self.additionalFields = connection.additionalFields.isEmpty ? nil : connection.additionalFields
     }
@@ -455,7 +474,7 @@ private struct StoredConnection: Codable {
         case isReadOnly // Legacy key for migration reading only
         case aiPolicy
         case mongoAuthSource, mongoReadPreference, mongoWriteConcern, redisDatabase
-        case mssqlSchema, oracleServiceName, startupCommands
+        case mssqlSchema, oracleServiceName, startupCommands, sortOrder
         case additionalFields
     }
 
@@ -492,6 +511,7 @@ private struct StoredConnection: Codable {
         try container.encodeIfPresent(aiPolicy, forKey: .aiPolicy)
         try container.encodeIfPresent(redisDatabase, forKey: .redisDatabase)
         try container.encodeIfPresent(startupCommands, forKey: .startupCommands)
+        try container.encode(sortOrder, forKey: .sortOrder)
         try container.encodeIfPresent(additionalFields, forKey: .additionalFields)
     }
 
@@ -554,6 +574,7 @@ private struct StoredConnection: Codable {
         mssqlSchema = try container.decodeIfPresent(String.self, forKey: .mssqlSchema)
         oracleServiceName = try container.decodeIfPresent(String.self, forKey: .oracleServiceName)
         startupCommands = try container.decodeIfPresent(String.self, forKey: .startupCommands)
+        sortOrder = try container.decodeIfPresent(Int.self, forKey: .sortOrder) ?? 0
         additionalFields = try container.decodeIfPresent([String: String].self, forKey: .additionalFields)
     }
 
@@ -621,6 +642,7 @@ private struct StoredConnection: Codable {
             aiPolicy: parsedAIPolicy,
             redisDatabase: redisDatabase,
             startupCommands: startupCommands,
+            sortOrder: sortOrder,
             additionalFields: mergedFields
         )
     }

TablePro/Core/Storage/ERDiagramPositionStorage.swift

@@ -0,0 +1,37 @@
+import Foundation
+
+/// Persists user-arranged table node positions for ER diagrams.
+/// Keyed by connection + schema so positions survive across sessions.
+@MainActor
+final class ERDiagramPositionStorage {
+    static let shared = ERDiagramPositionStorage()
+    private let defaults = UserDefaults.standard
+
+    private init() {}
+
+    private func key(connectionId: UUID, schemaKey: String) -> String {
+        "com.TablePro.erDiagram.positions.\(connectionId.uuidString).\(schemaKey)"
+    }
+
+    func load(connectionId: UUID, schemaKey: String) -> [String: CGPoint] {
+        guard let data = defaults.data(forKey: key(connectionId: connectionId, schemaKey: schemaKey)),
+              let stored = try? JSONDecoder().decode([String: CodablePoint].self, from: data)
+        else { return [:] }
+        return stored.mapValues { CGPoint(x: $0.x, y: $0.y) }
+    }
+
+    func save(_ positions: [String: CGPoint], connectionId: UUID, schemaKey: String) {
+        let stored = positions.mapValues { CodablePoint(x: $0.x, y: $0.y) }
+        guard let data = try? JSONEncoder().encode(stored) else { return }
+        defaults.set(data, forKey: key(connectionId: connectionId, schemaKey: schemaKey))
+    }
+
+    func clear(connectionId: UUID, schemaKey: String) {
+        defaults.removeObject(forKey: key(connectionId: connectionId, schemaKey: schemaKey))
+    }
+}
+
+private struct CodablePoint: Codable {
+    let x: Double
+    let y: Double
+}

TablePro/Core/Sync/SyncRecordMapper.swift

@@ -62,6 +62,7 @@ struct SyncRecordMapper {
         record["safeModeLevel"] = connection.safeModeLevel.rawValue as CKRecordValue
         record["modifiedAtLocal"] = Date() as CKRecordValue
         record["schemaVersion"] = schemaVersion as CKRecordValue
+        record["sortOrder"] = Int64(connection.sortOrder) as CKRecordValue
 
         if let tagId = connection.tagId {
             record["tagId"] = tagId.uuidString as CKRecordValue
@@ -128,6 +129,7 @@ struct SyncRecordMapper {
         let aiPolicyRaw = record["aiPolicy"] as? String
         let redisDatabase = (record["redisDatabase"] as? Int64).map { Int($0) }
         let startupCommands = record["startupCommands"] as? String
+        let sortOrder = (record["sortOrder"] as? Int64).map { Int($0) } ?? 0
         let sshProfileId = (record["sshProfileId"] as? String).flatMap { UUID(uuidString: $0) }
 
         var sshConfig = SSHConfiguration()
@@ -163,6 +165,7 @@ struct SyncRecordMapper {
             aiPolicy: aiPolicyRaw.flatMap { AIConnectionPolicy(rawValue: $0) },
             redisDatabase: redisDatabase,
             startupCommands: startupCommands,
+            sortOrder: sortOrder,
             additionalFields: additionalFields
         )
     }

TablePro/Models/Connection/ConnectionGroupTree.swift

@@ -55,6 +55,7 @@ func buildGroupTree(
 
         let groupConnections = connections
             .filter { $0.groupId == group.id }
+            .sorted { $0.sortOrder != $1.sortOrder ? $0.sortOrder < $1.sortOrder : $0.name.localizedStandardCompare($1.name) == .orderedAscending }
         for conn in groupConnections {
             children.append(.connection(conn))
         }
@@ -67,6 +68,7 @@ func buildGroupTree(
             guard let groupId = conn.groupId else { return true }
             return !validGroupIds.contains(groupId)
         }
+        .sorted { $0.sortOrder != $1.sortOrder ? $0.sortOrder < $1.sortOrder : $0.name.localizedStandardCompare($1.name) == .orderedAscending }
         for conn in ungrouped {
             items.append(.connection(conn))
         }

TablePro/Models/Connection/DatabaseConnection.swift

@@ -185,6 +185,7 @@ struct DatabaseConnection: Identifiable, Hashable {
     var additionalFields: [String: String] = [:]
     var redisDatabase: Int?
     var startupCommands: String?
+    var sortOrder: Int
 
     var mongoAuthSource: String? {
         get { additionalFields["mongoAuthSource"]?.nilIfEmpty }
@@ -267,6 +268,7 @@ struct DatabaseConnection: Identifiable, Hashable {
         mssqlSchema: String? = nil,
         oracleServiceName: String? = nil,
         startupCommands: String? = nil,
+        sortOrder: Int = 0,
         additionalFields: [String: String]? = nil
     ) {
         self.id = id
@@ -286,6 +288,7 @@ struct DatabaseConnection: Identifiable, Hashable {
         self.aiPolicy = aiPolicy
         self.redisDatabase = redisDatabase
         self.startupCommands = startupCommands
+        self.sortOrder = sortOrder
         if let additionalFields {
             self.additionalFields = additionalFields
         } else {