Skip to content

A native macOS / windows / Linux database IDE built with Swift and AppKit. Connect to PostgreSQL, MySQL, SQLite, and Redis from a single app with a fast, keyboard-driven interface.

C++

feat(query): Profile preset + Analyze hint banner

Tobib72bd17ae0d7
diff --git a/macos/Core/Models/Query/ExplainOptions.swift b/macos/Core/Models/Query/ExplainOptions.swift
index f75d31f..2b8260d 100644
--- a/macos/Core/Models/Query/ExplainOptions.swift
+++ b/macos/Core/Models/Query/ExplainOptions.swift
@@ -91,6 +91,26 @@ struct ExplainOptions: Equatable, Codable, Sendable {
/// Matches the legacy hard-coded `EXPLAIN (ANALYZE false, COSTS true, FORMAT TEXT)`
/// — used when callers don't pass options.
static let `default` = ExplainOptions()
+
+ /// "Profile" preset — what a senior dev would tick before debugging a slow
+ /// SELECT: actual times, buffer hits/reads, schema-qualified output, plus
+ /// the planning/execution summary. Does NOT change FORMAT — caller keeps
+ /// whatever they already set so JSON-tree users don't get downgraded to
+ /// TEXT after applying the preset.
+ ///
+ /// **Caution**: enabling ANALYZE means the query is actually executed.
+ /// Safe for SELECT, dangerous for INSERT/UPDATE/DELETE (will modify data).
+ /// The UI surfaces this preset as "Profile (SELECT)" to make the
+ /// expectation explicit.
+ static func profilePreset(currentFormat: Format) -> ExplainOptions {
+ var opts = ExplainOptions.default
+ opts.analyze = true
+ opts.buffers = true
+ opts.verbose = true
+ opts.summary = true
+ opts.format = currentFormat
+ return opts
+ }
}
// MARK: - Cross-disable rules
diff --git a/macos/Presentation/Views/QueryEditor/Explain/ExplainOptionsMenu.swift b/macos/Presentation/Views/QueryEditor/Explain/ExplainOptionsMenu.swift
index 9f6e996..178cdb7 100644
--- a/macos/Presentation/Views/QueryEditor/Explain/ExplainOptionsMenu.swift
+++ b/macos/Presentation/Views/QueryEditor/Explain/ExplainOptionsMenu.swift
@@ -20,6 +20,17 @@ struct ExplainOptionsMenu: View {
var body: some View {
Menu {
+ // Quick preset — sets the four options a senior dev would tick
+ // before debugging a slow SELECT (Analyze, Buffers, Verbose,
+ // Summary). Keeps current Format so users on Tree view don't get
+ // bumped back to Text. The "(SELECT)" suffix is a load-bearing
+ // hint that this turns on ANALYZE → query is actually executed.
+ Button("Apply ‘Profile’ preset (SELECT)") {
+ options = ExplainOptions.profilePreset(currentFormat: options.format)
+ }
+
+ Divider()
+
// ANALYZE — toggle prominently at the top. It's the load-bearing
// setting (off = plan only / safe; on = execute query / measure).
Toggle("Analyze (execute query)", isOn: $options.analyze)
diff --git a/macos/Presentation/Views/QueryEditor/Explain/ExplainOutputView.swift b/macos/Presentation/Views/QueryEditor/Explain/ExplainOutputView.swift
index 021a315..4b09d05 100644
--- a/macos/Presentation/Views/QueryEditor/Explain/ExplainOutputView.swift
+++ b/macos/Presentation/Views/QueryEditor/Explain/ExplainOutputView.swift
@@ -44,12 +44,19 @@ struct ExplainOutputView: View {
/// to gate the Tree view (only meaningful for JSON/YAML output).
let format: ExplainOptions.Format
+ /// Whether the EXPLAIN was run with ANALYZE on. Drives the inline hint
+ /// banner below — without ANALYZE the user only sees plan estimates, not
+ /// actual times / row counts / buffer stats, which is rarely enough to
+ /// debug a real performance issue.
+ let analyzed: Bool
+
@State private var mode: ExplainViewMode
@State private var wordWrap: Bool = true
- init(raw: String, format: ExplainOptions.Format) {
+ init(raw: String, format: ExplainOptions.Format, analyzed: Bool) {
self.raw = raw
self.format = format
+ self.analyzed = analyzed
// Auto-pick: if the user asked for JSON, default to Tree (most useful).
// Otherwise default to Text.
let initial: ExplainViewMode = (format == .json) ? .tree : .text
@@ -67,10 +74,32 @@ struct ExplainOutputView: View {
VStack(spacing: 0) {
header
Divider()
+ if !analyzed {
+ analyzeHint
+ Divider()
+ }
content
}
}
+ /// Inline tip surfaced when ANALYZE is off. Most user-facing perf debug
+ /// requires actual times / row counts / cache stats — this nudges the
+ /// user toward the right toggles without forcing them.
+ private var analyzeHint: some View {
+ HStack(alignment: .firstTextBaseline, spacing: 6) {
+ Image(systemName: "lightbulb")
+ .font(.system(size: 11))
+ .foregroundStyle(.yellow)
+ Text("Tip: enable **Analyze** + **Buffers** in the options menu to see actual times and cache stats. The current output is plan estimates only.")
+ .font(.system(size: 11))
+ .foregroundStyle(.secondary)
+ Spacer()
+ }
+ .padding(.horizontal, 10)
+ .padding(.vertical, 6)
+ .background(Color(nsColor: .controlBackgroundColor).opacity(0.5))
+ }
+
// MARK: - Header
private var header: some View {
diff --git a/macos/Presentation/Views/QueryEditor/QueryEditorView.swift b/macos/Presentation/Views/QueryEditor/QueryEditorView.swift
index 49b6be6..18f3cb1 100644
--- a/macos/Presentation/Views/QueryEditor/QueryEditorView.swift
+++ b/macos/Presentation/Views/QueryEditor/QueryEditorView.swift
@@ -33,6 +33,7 @@ struct QueryEditorView: View {
/// browser instead of the data grid. Cleared by every regular Run.
@State private var explainOutput: String?
@State private var explainOutputFormat: ExplainOptions.Format = .text
+ @State private var explainOutputAnalyzed: Bool = false
private var isRedis: Bool { appState.activeConfig?.databaseType == .redis }
private var isPostgres: Bool { appState.activeConfig?.databaseType == .postgresql }
@@ -162,7 +163,11 @@ struct QueryEditorView: View {
.frame(maxWidth: .infinity, maxHeight: .infinity)
.padding()
} else if let output = explainOutput {
- ExplainOutputView(raw: output, format: explainOutputFormat)
+ ExplainOutputView(
+ raw: output,
+ format: explainOutputFormat,
+ analyzed: explainOutputAnalyzed
+ )
} else if !resultViewModel.columns.isEmpty {
AppKitDataGrid(
viewModel: resultViewModel,
@@ -444,6 +449,7 @@ struct QueryEditorView: View {
.joined(separator: "\n")
explainOutput = raw
explainOutputFormat = isPostgres ? optsForBuild.format : .text
+ explainOutputAnalyzed = isPostgres ? optsForBuild.analyze : false
resultViewModel.columns = [] // hide grid; show explain panel
resultViewModel.rows = []
resultRowCount = 0
diff --git a/macos/Tests/GridexTests/ExplainOptionsTests.swift b/macos/Tests/GridexTests/ExplainOptionsTests.swift
index 8233fe1..9701120 100644
--- a/macos/Tests/GridexTests/ExplainOptionsTests.swift
+++ b/macos/Tests/GridexTests/ExplainOptionsTests.swift
@@ -198,6 +198,50 @@ final class ExplainOptionsTests: XCTestCase {
XCTAssertEqual(restored, opts)
}
+ // MARK: - Profile preset
+
+ func test_profilePreset_setsTheRightFourFlags() {
+ let preset = ExplainOptions.profilePreset(currentFormat: .text)
+ XCTAssertTrue(preset.analyze, "ANALYZE — actual times require it")
+ XCTAssertTrue(preset.buffers, "BUFFERS — cache hit/read stats")
+ XCTAssertTrue(preset.verbose, "VERBOSE — schema-qualified output")
+ XCTAssertTrue(preset.summary, "SUMMARY — planning + execution time")
+ }
+
+ func test_profilePreset_doesNotSetUnrelatedFlags() {
+ // Memory / Generic Plan / Settings / Timing / WAL / Serialize are
+ // problem-specific. Default preset must not over-commit — leaves
+ // them off so the user can layer them in if needed.
+ let preset = ExplainOptions.profilePreset(currentFormat: .text)
+ XCTAssertFalse(preset.memory)
+ XCTAssertFalse(preset.genericPlan)
+ XCTAssertFalse(preset.settings)
+ XCTAssertFalse(preset.timing)
+ XCTAssertFalse(preset.wal)
+ XCTAssertEqual(preset.serialize, .off)
+ }
+
+ func test_profilePreset_keepsCurrentFormat() {
+ // User on Tree view (FORMAT JSON) clicking the preset must NOT get
+ // bumped back to TEXT — that would silently switch their view mode.
+ for format in ExplainOptions.Format.allCases {
+ let preset = ExplainOptions.profilePreset(currentFormat: format)
+ XCTAssertEqual(preset.format, format,
+ "preset must preserve user's chosen format \(format)")
+ }
+ }
+
+ func test_profilePreset_buildsValidPGOptionList() {
+ // Sanity: the preset must produce a valid `EXPLAIN (...)` shape that
+ // includes ANALYZE true / BUFFERS true / VERBOSE true / SUMMARY true.
+ let preset = ExplainOptions.profilePreset(currentFormat: .json)
+ let sql = DatabaseType.postgresql.explainSQL(for: "SELECT 1", options: preset)!
+ for piece in ["ANALYZE true", "BUFFERS true", "VERBOSE true",
+ "SUMMARY true", "FORMAT JSON"] {
+ XCTAssertTrue(sql.contains(piece), "preset SQL missing '\(piece)': \(sql)")
+ }
+ }
+
// MARK: - PG version banner parsing
func test_parsePostgresMajor_examples() {