feat(sidebar): recent tables section (opt-in)

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Recent section at the top of the sidebar tracks the last 10 tables you opened per connection and database, in every sidebar layout, and remembers them between launches. It records a table when you open it, not while you arrow through previews. Click a recent table to reopen it, or right-click to remove one or clear the list. Off by default, turn it on in Settings > General > Sidebar. (#1352)
+
 ### Fixed
 
 - Switching schemas on an Oracle connection no longer hangs on an infinite loading spinner. Oracle now switches by schema like BigQuery, the sidebar lists every schema with its tables loading on expand, Oracle queries respect the query timeout setting and reconnect automatically after a timeout, and a schema load that fails shows an error with a Retry button instead of spinning forever. Works with an already-installed Oracle plugin; updating the plugin adds the query timeout enforcement. (#1807)

CLAUDE.md

@@ -183,6 +183,7 @@ Missing a case produces a wrong "{Language} Query" title on the first frame.
 | Per-table filters    | JSON files       | `FilterSettingsStorage` (one file per connection + database + schema + table; saves the valid working set, each row's enabled flag included) |
 | Favorite tables      | UserDefaults     | `FavoriteTablesStorage` (per connection + database + schema; iCloud-synced) |
 | Tree database filter | UserDefaults     | `DatabaseTreeFilterStorage` (per connection; selected database set, empty = show all; device-local). Live value held in `SharedSidebarState`. |
+| Recent tables        | UserDefaults     | `RecentTablesStore` (per connection, keyed by database, last 10 each; device-local). Live value held in `SharedSidebarState`, recorded at the `QueryTabManager` open chokepoint. |
 
 ### Logging & Debugging
 

TablePro/Core/Services/Infrastructure/SessionStateFactory.swift

@@ -62,6 +62,11 @@ enum SessionStateFactory {
             },
             tabSessionRegistry: tabSessionRegistry
         )
+        tabMgr.onTableOpened = { tableName, schemaName, databaseName, isView, isPreview in
+            SharedSidebarState.forConnection(connectionId).recordTableOpen(
+                database: databaseName, schema: schemaName, name: tableName, isView: isView, isPreview: isPreview
+            )
+        }
         let changeMgr = DataChangeManager()
         changeMgr.databaseType = connection.type
         let toolbarSt = ConnectionToolbarState(connection: connection)
@@ -100,14 +105,16 @@ enum SessionStateFactory {
                                     tableName: tableName,
                                     databaseType: connection.type,
                                     databaseName: payload.databaseName ?? activeDatabaseName,
-                                    schemaName: resolvedSchemaName
+                                    schemaName: resolvedSchemaName,
+                                    isView: payload.isView
                                 )
                             } else {
                                 try tabMgr.addTableTab(
                                     tableName: tableName,
                                     databaseType: connection.type,
                                     databaseName: payload.databaseName ?? activeDatabaseName,
-                                    schemaName: resolvedSchemaName
+                                    schemaName: resolvedSchemaName,
+                                    isView: payload.isView
                                 )
                             }
                         } catch {

TablePro/Core/Storage/RecentTablesStore.swift

@@ -0,0 +1,95 @@
+import Foundation
+import TableProPluginKit
+
+struct RecentTableEntry: Codable, Equatable, Identifiable {
+    let database: String?
+    let schema: String?
+    let name: String
+    let isView: Bool
+    let openedAt: Date
+
+    static func identityKey(schema: String?, name: String) -> String {
+        "\(schema ?? "")\u{1}\(name)"
+    }
+
+    var scopeKey: String { database ?? "" }
+
+    var identityKey: String { Self.identityKey(schema: schema, name: name) }
+
+    var id: String { "\(scopeKey)\u{1}\(identityKey)" }
+
+    var tableInfo: TableInfo {
+        TableInfo(name: name, type: isView ? .view : .table, rowCount: nil, schema: schema)
+    }
+}
+
+struct RecentTableRow: Identifiable {
+    let table: TableInfo
+
+    var id: String { "recent\u{1}\(table.id)" }
+}
+
+@MainActor
+final class RecentTablesStore {
+    static let shared = RecentTablesStore()
+
+    static let perDatabaseCap = 10
+
+    private let defaults: UserDefaults
+    private let keyPrefix = "RecentTables.v1."
+
+    init(defaults: UserDefaults = .standard) {
+        self.defaults = defaults
+    }
+
+    func entries(connectionId: UUID) -> [RecentTableEntry] {
+        guard let data = defaults.data(forKey: storageKey(connectionId)) else { return [] }
+        return (try? JSONDecoder().decode([RecentTableEntry].self, from: data)) ?? []
+    }
+
+    @discardableResult
+    func record(
+        connectionId: UUID, database: String?, schema: String?, name: String, isView: Bool, at date: Date = Date()
+    ) -> [RecentTableEntry] {
+        let entry = RecentTableEntry(database: database, schema: schema, name: name, isView: isView, openedAt: date)
+        let updated = Self.merged(entry, into: entries(connectionId: connectionId))
+        persist(updated, connectionId: connectionId)
+        return updated
+    }
+
+    @discardableResult
+    func remove(connectionId: UUID, entry: RecentTableEntry) -> [RecentTableEntry] {
+        let updated = entries(connectionId: connectionId).filter { $0.id != entry.id }
+        persist(updated, connectionId: connectionId)
+        return updated
+    }
+
+    @discardableResult
+    func clear(connectionId: UUID, database: String?) -> [RecentTableEntry] {
+        let scope = database ?? ""
+        let updated = entries(connectionId: connectionId).filter { $0.scopeKey != scope }
+        persist(updated, connectionId: connectionId)
+        return updated
+    }
+
+    static func merged(_ entry: RecentTableEntry, into existing: [RecentTableEntry]) -> [RecentTableEntry] {
+        var result = existing.filter { $0.id != entry.id }
+        result.insert(entry, at: 0)
+        var perScopeCount: [String: Int] = [:]
+        return result.filter { candidate in
+            let count = perScopeCount[candidate.scopeKey, default: 0]
+            guard count < perDatabaseCap else { return false }
+            perScopeCount[candidate.scopeKey] = count + 1
+            return true
+        }
+    }
+
+    private func persist(_ entries: [RecentTableEntry], connectionId: UUID) {
+        guard let data = try? JSONEncoder().encode(entries) else { return }
+        defaults.set(data, forKey: storageKey(connectionId))
+    }
+
+    private func storageKey(_ connectionId: UUID) -> String {
+        keyPrefix + connectionId.uuidString
+    }
+}

TablePro/Models/Query/QueryTabManager.swift

@@ -143,11 +143,20 @@ final class QueryTabManager {
         }
     }
 
+    var onTableOpened: ((_ tableName: String, _ schemaName: String?, _ databaseName: String, _ isView: Bool, _ isPreview: Bool) -> Void)?
+
+    private func notifyTableOpened(
+        tableName: String, schemaName: String?, databaseName: String, isView: Bool, isPreview: Bool
+    ) {
+        onTableOpened?(tableName, schemaName, databaseName, isView, isPreview)
+    }
+
     func addTableTab(
         tableName: String,
         databaseType: DatabaseType = .mysql,
         databaseName: String = "",
         schemaName: String? = nil,
+        isView: Bool = false,
         quoteIdentifier: ((String) -> String)? = nil
     ) throws {
         if let existingTab = tabs.first(where: {
@@ -157,6 +166,10 @@ final class QueryTabManager {
                 && $0.tableContext.schemaName == schemaName
         }) {
             selectedTabId = existingTab.id
+            notifyTableOpened(
+                tableName: tableName, schemaName: schemaName, databaseName: databaseName,
+                isView: isView, isPreview: false
+            )
             return
         }
 
@@ -178,6 +191,10 @@ final class QueryTabManager {
         newTab.tableContext.schemaName = schemaName
         tabs.append(newTab)
         selectedTabId = newTab.id
+        notifyTableOpened(
+            tableName: tableName, schemaName: schemaName, databaseName: databaseName,
+            isView: isView, isPreview: false
+        )
     }
 
     static func tabTitle(name: String, schema: String?, databaseType: DatabaseType) -> String {
@@ -227,6 +244,7 @@ final class QueryTabManager {
         databaseType: DatabaseType = .mysql,
         databaseName: String = "",
         schemaName: String? = nil,
+        isView: Bool = false,
         quoteIdentifier: ((String) -> String)? = nil
     ) throws {
         if let existing = tabs.first(where: {
@@ -236,6 +254,10 @@ final class QueryTabManager {
                 && $0.tableContext.schemaName == schemaName
         }) {
             selectedTabId = existing.id
+            notifyTableOpened(
+                tableName: tableName, schemaName: schemaName, databaseName: databaseName,
+                isView: isView, isPreview: true
+            )
             return
         }
 
@@ -258,6 +280,10 @@ final class QueryTabManager {
         newTab.isPreview = true
         tabs.append(newTab)
         selectedTabId = newTab.id
+        notifyTableOpened(
+            tableName: tableName, schemaName: schemaName, databaseName: databaseName,
+            isView: isView, isPreview: true
+        )
     }
 
     /// Replace the currently selected tab's content with a new table.
@@ -309,6 +335,10 @@ final class QueryTabManager {
         tab.isPreview = isPreview
         tabs[selectedIndex] = tab
         tabStructureVersion += 1
+        notifyTableOpened(
+            tableName: tableName, schemaName: schemaName, databaseName: databaseName,
+            isView: isView, isPreview: isPreview
+        )
         return true
     }
 

TablePro/Models/Settings/GeneralSettings.swift

@@ -63,6 +63,9 @@ struct GeneralSettings: Codable, Equatable {
     /// Whether to share anonymous usage analytics
     var shareAnalytics: Bool
 
+    /// Whether the sidebar shows a Recent section with recently opened tables
+    var showRecentTables: Bool
+
     /// Whether to show database object comments in the sidebar and data grid headers
     var showObjectComments: Bool
 
@@ -72,6 +75,7 @@ struct GeneralSettings: Codable, Equatable {
         automaticallyCheckForUpdates: true,
         queryTimeoutSeconds: 60,
         shareAnalytics: true,
+        showRecentTables: false,
         showObjectComments: true
     )
 
@@ -81,13 +85,15 @@ struct GeneralSettings: Codable, Equatable {
         automaticallyCheckForUpdates: Bool = true,
         queryTimeoutSeconds: Int = 60,
         shareAnalytics: Bool = true,
+        showRecentTables: Bool = false,
         showObjectComments: Bool = true
     ) {
         self.startupBehavior = startupBehavior
         self.language = language
         self.automaticallyCheckForUpdates = automaticallyCheckForUpdates
         self.queryTimeoutSeconds = queryTimeoutSeconds
         self.shareAnalytics = shareAnalytics
+        self.showRecentTables = showRecentTables
         self.showObjectComments = showObjectComments
     }
 
@@ -98,6 +104,7 @@ struct GeneralSettings: Codable, Equatable {
         automaticallyCheckForUpdates = try container.decodeIfPresent(Bool.self, forKey: .automaticallyCheckForUpdates) ?? true
         queryTimeoutSeconds = try container.decodeIfPresent(Int.self, forKey: .queryTimeoutSeconds) ?? 60
         shareAnalytics = try container.decodeIfPresent(Bool.self, forKey: .shareAnalytics) ?? true
+        showRecentTables = try container.decodeIfPresent(Bool.self, forKey: .showRecentTables) ?? false
         showObjectComments = try container.decodeIfPresent(Bool.self, forKey: .showObjectComments) ?? true
     }
 }

TablePro/Models/UI/QuickSwitcherItem.swift

@@ -72,6 +72,10 @@ internal struct QuickSwitcherItem: Identifiable, Hashable, Sendable {
     var payload: String?
     var isOpenInTab: Bool = false
 
+    static func tableItemId(name: String, isView: Bool) -> String {
+        "table_\(name)_\(isView ? "VIEW" : "TABLE")"
+    }
+
     /// SF Symbol name for this item's icon
     var iconName: String {
         switch kind {

TablePro/Models/UI/SharedSidebarState.swift

@@ -27,6 +27,64 @@ final class SharedSidebarState {
     var searchText: String = ""
     var favoritesSearchText: String = ""
 
+    var recentTables: [RecentTableEntry] = []
+
+    @ObservationIgnored private var pendingRecordTask: Task<Void, Never>?
+
+    func recentEntries(inDatabase database: String?) -> [RecentTableEntry] {
+        recentTables.filter { $0.database == normalizedDatabase(database) }
+    }
+
+    func recordTableOpen(database: String?, schema: String?, name: String, isView: Bool, isPreview: Bool) {
+        guard isPreview else {
+            pendingRecordTask?.cancel()
+            pendingRecordTask = nil
+            commitTableOpen(database: database, schema: schema, name: name, isView: isView)
+            return
+        }
+        pendingRecordTask?.cancel()
+        pendingRecordTask = Task { @MainActor [weak self] in
+            try? await Task.sleep(nanoseconds: 250_000_000)
+            guard let self, !Task.isCancelled else { return }
+            self.commitTableOpen(database: database, schema: schema, name: name, isView: isView)
+        }
+    }
+
+    private func commitTableOpen(database: String?, schema: String?, name: String, isView: Bool) {
+        QuickSwitcherFrecencyStore(connectionId: connectionId).recordAccess(
+            itemId: QuickSwitcherItem.tableItemId(name: name, isView: isView)
+        )
+        guard AppSettingsManager.shared.general.showRecentTables else { return }
+        recentTables = RecentTablesStore.shared.record(
+            connectionId: connectionId, database: normalizedDatabase(database),
+            schema: schema, name: name, isView: isView
+        )
+    }
+
+    func removeRecentTable(database: String?, schema: String?, name: String) {
+        let entry = RecentTableEntry(
+            database: normalizedDatabase(database), schema: schema, name: name, isView: false, openedAt: Date()
+        )
+        recentTables = RecentTablesStore.shared.remove(connectionId: connectionId, entry: entry)
+    }
+
+    func clearRecentTables(inDatabase database: String?) {
+        recentTables = RecentTablesStore.shared.clear(
+            connectionId: connectionId, database: normalizedDatabase(database)
+        )
+    }
+
+    func reloadRecentTablesFromStore() {
+        recentTables = AppSettingsManager.shared.general.showRecentTables
+            ? RecentTablesStore.shared.entries(connectionId: connectionId)
+            : []
+    }
+
+    private func normalizedDatabase(_ database: String?) -> String? {
+        guard let database, !database.isEmpty else { return nil }
+        return database
+    }
+
     var selectedSidebarTab: SidebarTab {
         didSet {
             UserDefaults.standard.set(
@@ -101,6 +159,9 @@ final class SharedSidebarState {
         self.selectedFavorite = UserDefaults.standard.string(
             forKey: SidebarPersistenceKey.selectedFavorite(connectionId: connectionId)
         ).flatMap(FavoriteSelection.init(rawValue:))
+        if AppSettingsManager.shared.general.showRecentTables {
+            self.recentTables = RecentTablesStore.shared.entries(connectionId: connectionId)
+        }
     }
 
     /// Default init for previews and tests
@@ -112,6 +173,10 @@ final class SharedSidebarState {
         self.selectedFavorite = nil
     }
 
+    deinit {
+        pendingRecordTask?.cancel()
+    }
+
     private static var registry: [UUID: SharedSidebarState] = [:]
 
     static func forConnection(_ id: UUID) -> SharedSidebarState {