feat: add SQL file open, save, and save-as (#475) (#501)

datlechin · web-flow · commit 278ca1245af5 · 2026-03-29T20:51:41.000+07:00
* feat: add SQL file open, save, and save-as with native macOS integration (#475) * fix: guard writeFile encoding, restore onQuickSearch, clean changelog * fix: Preview SQL button should not enable for file-dirty state * docs: update SQL editor and keyboard shortcuts for file open/save * fix: O(1) length pre-check for isFileDirty, extract window title helper
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Nested hierarchical groups for connection list (up to 3 levels deep)
 - Confirmation dialogs for deep link queries, connection imports, and pre-connect scripts
 - JSON fields in Row Details sidebar now display in a scrollable monospaced text area
+- Open, save, and save-as for SQL files with native macOS title bar integration (#475)
 
 ### Changed
 
diff --git a/TablePro/Core/Services/Infrastructure/SQLFileService.swift b/TablePro/Core/Services/Infrastructure/SQLFileService.swift
@@ -0,0 +1,57 @@
+//
+//  SQLFileService.swift
+//  TablePro
+//
+//  Service for reading and writing SQL files.
+//
+
+import AppKit
+import os
+import UniformTypeIdentifiers
+
+/// Service for reading and writing SQL files.
+enum SQLFileService {
+    private static let logger = Logger(subsystem: "com.TablePro", category: "SQLFileService")
+
+    /// Reads a SQL file from disk.
+    static func readFile(url: URL) async throws -> String {
+        try await Task.detached {
+            try String(contentsOf: url, encoding: .utf8)
+        }.value
+    }
+
+    /// Writes content to a SQL file atomically.
+    static func writeFile(content: String, to url: URL) async throws {
+        try await Task.detached {
+            guard let data = content.data(using: .utf8) else {
+                throw CocoaError(.fileWriteInapplicableStringEncoding)
+            }
+            try data.write(to: url, options: .atomic)
+        }.value
+    }
+
+    /// Shows an open panel for .sql files.
+    @MainActor
+    static func showOpenPanel() async -> [URL]? {
+        let panel = NSOpenPanel()
+        panel.allowedContentTypes = [UTType(filenameExtension: "sql") ?? .plainText]
+        panel.allowsMultipleSelection = true
+        panel.message = String(localized: "Select SQL files to open")
+        let response = await panel.begin()
+        guard response == .OK else { return nil }
+        return panel.urls
+    }
+
+    /// Shows a save panel for .sql files.
+    @MainActor
+    static func showSavePanel(suggestedName: String = "query.sql") async -> URL? {
+        let panel = NSSavePanel()
+        panel.allowedContentTypes = [UTType(filenameExtension: "sql") ?? .plainText]
+        panel.canCreateDirectories = true
+        panel.nameFieldStringValue = suggestedName
+        panel.message = String(localized: "Save SQL file")
+        let response = await panel.begin()
+        guard response == .OK else { return nil }
+        return panel.url
+    }
+}
diff --git a/TablePro/Core/Services/Infrastructure/TabPersistenceCoordinator.swift b/TablePro/Core/Services/Infrastructure/TabPersistenceCoordinator.swift
@@ -147,7 +147,8 @@ internal final class TabPersistenceCoordinator {
             tabType: tab.tabType,
             tableName: tab.tableName,
             isView: tab.isView,
-            databaseName: tab.databaseName
+            databaseName: tab.databaseName,
+            sourceFileURL: tab.sourceFileURL
         )
     }
 }
diff --git a/TablePro/Models/Connection/ConnectionToolbarState.swift b/TablePro/Models/Connection/ConnectionToolbarState.swift
@@ -174,9 +174,12 @@ final class ConnectionToolbarState {
     /// Whether the current tab is a table tab (enables filter/sort actions)
     var isTableTab: Bool = false
 
-    /// Whether there are pending changes to preview
+    /// Whether there are pending changes (data grid or file)
     var hasPendingChanges: Bool = false
 
+    /// Whether there are pending data grid changes (for SQL preview button)
+    var hasDataPendingChanges: Bool = false
+
     /// Whether the SQL review popover is showing
     var showSQLReviewPopover: Bool = false
 
diff --git a/TablePro/Models/Query/QueryTab.swift b/TablePro/Models/Query/QueryTab.swift
@@ -371,12 +371,27 @@ struct QueryTab: Identifiable, Equatable {
     // Source file URL for .sql files opened from disk (used for deduplication)
     var sourceFileURL: URL?
 
+    // Snapshot of file content at last save/load (nil for non-file tabs).
+    // Used to detect unsaved changes via isFileDirty.
+    var savedFileContent: String?
+
     // Version counter incremented when resultRows changes (used for sort caching)
     var resultVersion: Int
 
     // Version counter incremented when FK/metadata arrives (Phase 2), used to invalidate caches
     var metadataVersion: Int
 
+    /// Whether the editor content differs from the last saved/loaded file content.
+    /// Returns false for tabs not backed by a file.
+    /// Uses O(1) length pre-check to avoid O(n) string comparison on every keystroke.
+    var isFileDirty: Bool {
+        guard sourceFileURL != nil, let saved = savedFileContent else { return false }
+        let queryNS = query as NSString
+        let savedNS = saved as NSString
+        if queryNS.length != savedNS.length { return true }
+        return queryNS != savedNS
+    }
+
     init(
         id: UUID = UUID(),
         title: String = "Query",
@@ -576,6 +591,9 @@ final class QueryTabManager {
 
         newTab.databaseName = databaseName
         newTab.sourceFileURL = sourceFileURL
+        if sourceFileURL != nil {
+            newTab.savedFileContent = newTab.query
+        }
         tabs.append(newTab)
         selectedTabId = newTab.id
     }
diff --git a/TablePro/Models/UI/KeyboardShortcutModels.swift b/TablePro/Models/UI/KeyboardShortcutModels.swift
@@ -39,8 +39,10 @@ enum ShortcutAction: String, Codable, CaseIterable, Identifiable {
     case newConnection
     case newTab
     case openDatabase
+    case openFile
     case switchConnection
     case saveChanges
+    case saveAs
     case previewSQL
     case closeTab
     case refresh
@@ -84,8 +86,8 @@ enum ShortcutAction: String, Codable, CaseIterable, Identifiable {
 
     var category: ShortcutCategory {
         switch self {
-        case .newConnection, .newTab, .openDatabase, .switchConnection,
-             .saveChanges, .previewSQL, .closeTab, .refresh,
+        case .newConnection, .newTab, .openDatabase, .openFile, .switchConnection,
+             .saveChanges, .saveAs, .previewSQL, .closeTab, .refresh,
              .explainQuery, .export, .importData, .quickSwitcher:
             return .file
         case .undo, .redo, .cut, .copy, .copyWithHeaders, .copyAsJson, .paste,
@@ -107,8 +109,10 @@ enum ShortcutAction: String, Codable, CaseIterable, Identifiable {
         case .newConnection: return String(localized: "New Connection")
         case .newTab: return String(localized: "New Tab")
         case .openDatabase: return String(localized: "Open Database")
+        case .openFile: return String(localized: "Open File")
         case .switchConnection: return String(localized: "Switch Connection")
         case .saveChanges: return String(localized: "Save Changes")
+        case .saveAs: return String(localized: "Save As")
         case .previewSQL: return String(localized: "Preview SQL")
         case .closeTab: return String(localized: "Close Tab")
         case .refresh: return String(localized: "Refresh")
@@ -404,8 +408,10 @@ struct KeyboardSettings: Codable, Equatable {
         .newConnection: KeyCombo(key: "n", command: true),
         .newTab: KeyCombo(key: "t", command: true),
         .openDatabase: KeyCombo(key: "k", command: true),
+        .openFile: KeyCombo(key: "o", command: true),
         .switchConnection: KeyCombo(key: "c", command: true, option: true),
         .saveChanges: KeyCombo(key: "s", command: true),
+        .saveAs: KeyCombo(key: "s", command: true, shift: true),
         .previewSQL: KeyCombo(key: "p", command: true, shift: true),
         .closeTab: KeyCombo(key: "w", command: true),
         .refresh: KeyCombo(key: "r", command: true),
diff --git a/TablePro/TableProApp.swift b/TablePro/TableProApp.swift
@@ -182,6 +182,12 @@ struct AppMenuCommands: Commands {
             .optionalKeyboardShortcut(shortcut(for: .openDatabase))
             .disabled(!appState.isConnected || !appState.supportsDatabaseSwitching)
 
+            Button(String(localized: "Open File...")) {
+                actions?.openSQLFile()
+            }
+            .optionalKeyboardShortcut(shortcut(for: .openFile))
+            .disabled(!appState.isConnected)
+
             Button("Switch Connection...") {
                 NotificationCenter.default.post(name: .openConnectionSwitcher, object: nil)
             }
@@ -202,6 +208,12 @@ struct AppMenuCommands: Commands {
             .optionalKeyboardShortcut(shortcut(for: .saveChanges))
             .disabled(!appState.isConnected || appState.isReadOnly)
 
+            Button(String(localized: "Save As...")) {
+                actions?.saveFileAs()
+            }
+            .optionalKeyboardShortcut(shortcut(for: .saveAs))
+            .disabled(!appState.isConnected)
+
             Button {
                 actions?.previewSQL()
             } label: {
diff --git a/TablePro/Views/Main/Child/MainEditorContentView.swift b/TablePro/Views/Main/Child/MainEditorContentView.swift
@@ -53,7 +53,7 @@ struct MainEditorContentView: View {
     let onFilterColumn: (String) -> Void
     let onApplyFilters: ([TableFilter]) -> Void
     let onClearFilters: () -> Void
-    let onQuickSearch: (String) -> Void
+    let onQuickSearch: ((String) -> Void)?
     let onRefresh: () -> Void
 
     // Pagination callbacks
@@ -246,6 +246,16 @@ struct MainEditorContentView: View {
                 tabManager.tabs[index].query = newValue
                 AppState.shared.hasQueryText = !newValue.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
 
+                // Update window dirty indicator and toolbar for file-backed tabs
+                if tabManager.tabs[index].sourceFileURL != nil {
+                    let isDirty = tabManager.tabs[index].isFileDirty
+                    DispatchQueue.main.async {
+                        if let window = NSApp.keyWindow {
+                            window.isDocumentEdited = isDirty
+                        }
+                    }
+                }
+
                 // Skip persistence for very large queries (e.g., imported SQL dumps).
                 // JSON-encoding 40MB freezes the main thread.
                 let queryLength = (newValue as NSString).length
diff --git a/TablePro/Views/Main/Extensions/MainContentView+Bindings.swift b/TablePro/Views/Main/Extensions/MainContentView+Bindings.swift
@@ -124,4 +124,5 @@ struct PendingChangeTrigger: Equatable {
     let pendingTruncates: Set<String>
     let pendingDeletes: Set<String>
     let hasStructureChanges: Bool
+    let isFileDirty: Bool
 }
diff --git a/TablePro/Views/Main/MainContentCommandActions.swift b/TablePro/Views/Main/MainContentCommandActions.swift
@@ -270,7 +270,8 @@ final class MainContentCommandActions {
         let hasPendingTableOps = !pendingTruncates.wrappedValue.isEmpty
             || !pendingDeletes.wrappedValue.isEmpty
         let hasSidebarEdits = rightPanelState.editState.hasEdits
-        return hasEditedCells || hasPendingTableOps || hasSidebarEdits
+        let hasFileDirty = coordinator?.tabManager.selectedTab?.isFileDirty ?? false
+        return hasEditedCells || hasPendingTableOps || hasSidebarEdits || hasFileDirty
     }
 
     // MARK: - Editor Query Loading (Group A — Called Directly)
@@ -375,6 +376,24 @@ final class MainContentCommandActions {
         }
     }
 
+    private func saveFileToSourceURL() {
+        guard let tab = coordinator?.tabManager.selectedTab,
+              let url = tab.sourceFileURL else { return }
+        let content = tab.query
+        Task { @MainActor in
+            do {
+                try await SQLFileService.writeFile(content: content, to: url)
+                if let index = coordinator?.tabManager.tabs.firstIndex(where: { $0.id == tab.id }) {
+                    coordinator?.tabManager.tabs[index].savedFileContent = content
+                }
+            } catch {
+                // File may have been deleted or become inaccessible
+                Self.logger.error("Failed to save file: \(error.localizedDescription)")
+                saveFileAs()
+            }
+        }
+    }
+
     private func discardAndClose() {
         coordinator?.changeManager.clearChangesAndUndoHistory()
         pendingTruncates.wrappedValue.removeAll()
@@ -441,6 +460,44 @@ final class MainContentCommandActions {
             // Save sidebar-only edits (edits made directly in the right panel)
             rightPanelState.onSave?()
         }
+        // File save: write query back to source file
+        else if let tab = coordinator?.tabManager.selectedTab,
+                tab.sourceFileURL != nil, tab.isFileDirty {
+            saveFileToSourceURL()
+        }
+        // Save As: untitled query tab with content
+        else if let tab = coordinator?.tabManager.selectedTab,
+                tab.tabType == .query, tab.sourceFileURL == nil,
+                !tab.query.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+            saveFileAs()
+        }
+    }
+
+    func saveFileAs() {
+        guard let tab = coordinator?.tabManager.selectedTab,
+              tab.tabType == .query else { return }
+        let content = tab.query
+        let suggestedName = tab.sourceFileURL?.lastPathComponent ?? "\(tab.title).sql"
+        Task { @MainActor in
+            guard let url = await SQLFileService.showSavePanel(suggestedName: suggestedName) else { return }
+            do {
+                try await SQLFileService.writeFile(content: content, to: url)
+                if let index = coordinator?.tabManager.tabs.firstIndex(where: { $0.id == tab.id }) {
+                    coordinator?.tabManager.tabs[index].sourceFileURL = url
+                    coordinator?.tabManager.tabs[index].savedFileContent = content
+                    coordinator?.tabManager.tabs[index].title = url.deletingPathExtension().lastPathComponent
+                }
+            } catch {
+                Self.logger.error("Failed to save file: \(error.localizedDescription)")
+            }
+        }
+    }
+
+    func openSQLFile() {
+        Task { @MainActor in
+            guard let urls = await SQLFileService.showOpenPanel() else { return }
+            NotificationCenter.default.post(name: .openSQLFiles, object: urls)
+        }
     }
 
     func explainQuery() {
diff --git a/TablePro/Views/Main/MainContentView.swift b/TablePro/Views/Main/MainContentView.swift
diff --git a/TablePro/Views/Toolbar/TableProToolbarView.swift b/TablePro/Views/Toolbar/TableProToolbarView.swift
diff --git a/docs/features/keyboard-shortcuts.mdx b/docs/features/keyboard-shortcuts.mdx
diff --git a/docs/features/sql-editor.mdx b/docs/features/sql-editor.mdx

Original file line number	Diff line number	Diff line change
`@@ -147,7 +147,8 @@ internal final class TabPersistenceCoordinator {`
`147`	`147`	`tabType: tab.tabType,`
`148`	`148`	`tableName: tab.tableName,`
`149`	`149`	`isView: tab.isView,`
`150`		`- databaseName: tab.databaseName`
	`150`	`+ databaseName: tab.databaseName,`
	`151`	`+ sourceFileURL: tab.sourceFileURL`
`151`	`152`	`)`
`152`	`153`	`}`
`153`	`154`	`}`
Original file line number	Diff line number	Diff line change
`@@ -124,4 +124,5 @@ struct PendingChangeTrigger: Equatable {`
`124`	`124`	`let pendingTruncates: Set<String>`
`125`	`125`	`let pendingDeletes: Set<String>`
`126`	`126`	`let hasStructureChanges: Bool`
	`127`	`+ let isFileDirty: Bool`
`127`	`128`	`}`