Documentation Index
Fetch the complete documentation index at: https://docs.tablepro.app/llms.txt
Use this file to discover all available pages before exploring further.
Query Tabs
Every tab is a native macOS window tab. Each tab is a separate NSWindow in a tab group, managed by the system window tabbing API. This means you get standard macOS tab behavior: drag tabs between windows, merge windows via Window > Merge All Windows, and use Window > Move Tab to New Window to split them out.
Each tab is an independent workspace with its own SQL content, results, pagination, sorting, and filter state. Open as many as you need. They persist across app restarts.
Tab Types
| Type | Icon | Purpose |
|---|
| Query Tab | Document icon | Write and execute custom SQL |
| Table Tab | Table icon (blue) | Browse table data with pagination and filtering |
SELECT * FROM table results.
Smart Tab Reuse
Clicking the same table switches to its existing tab. Clicking a different table opens a new tab.
Enable Reuse clean table tab in Settings > Tabs for TablePlus-style behavior: clicking a different table replaces the current table tab if it has no unsaved changes, no user interaction, and is not pinned.
Preview Tabs
Single-clicking a table opens a temporary preview tab that gets replaced when you click a different table (like VS Code’s preview tabs). Preview tabs show “Preview” in the window subtitle.
A preview tab becomes permanent when you:
- Double-click a table in the sidebar
- Interact with the tab (sort, filter, edit data, select rows)
Preview tabs are not saved across restarts.
Disable preview tabs in Settings > Tabs if you prefer every click to open a permanent tab.
Managing Tabs
Creating Tabs
| Action | How |
|---|
| New query tab | Cmd+T or click + in the tab bar |
| New query tab (toolbar) | Click the SQL button |
| New table tab | Click a table name in the sidebar |
Closing Tabs
| Action | How |
|---|
| Close current tab | Cmd+W |
| Close specific tab | Hover and click x |
| Close other tabs | Right-click > Close Other Tabs |
Closing a tab with unsaved changes discards those changes. TablePro warns you before closing if there are pending data modifications.
Switching Tabs
Cmd+1 through Cmd+9 to jump by positionCmd+Shift+[ / Cmd+Option+Left for previous tabCmd+Shift+] / Cmd+Option+Right for next tab
Each tab preserves its full state when you switch away: SQL content, cursor position, results, scroll position, selected rows, sort/filter state, and pending changes.
Reordering Tabs
Drag any tab to a new position. The tab bar scrolls horizontally when tabs overflow.
Pinning Tabs
Right-click a tab > Pin Tab. Pinned tabs:
- Cannot be closed via close button,
Cmd+W, or context menu
- Are not closed by Close Other Tabs
- Are not replaced by table tab reuse
- Persist across sessions
Unpin via right-click > Unpin Tab.
Duplicating Tabs
Right-click a tab > Duplicate Tab. The copy opens immediately after the original with the same query and results.
Per-Tab Change Tracking
Each tab maintains its own pending changes. Switching tabs saves and restores each tab’s change state.
Tab Persistence
What Is Persisted
| Saved | Not Saved |
|---|
| Tab ID and title | Query results (re-queried on reopen) |
| SQL content | Pending data changes |
| Tab type and table name | Selected rows, sort/filter state |
| Pin state | Preview tabs (discarded) |
Multi-Window Restoration
If you had several editor windows open with their own tab groups, TablePro restores every window on next launch. Earlier versions kept tabs from one window and dropped the rest.
Window Size, Position, and Zoom
Each editor window remembers its frame and zoom across launches. Reopen a connection and the window comes back at the same size, position, and zoom state. The first window opens at 1200x800 centered on the active screen.
Table Tabs (Server-Side)
Table tabs use SQL LIMIT and OFFSET. Only the current page loads from the database. Page navigation triggers a new query. Configure page size in Settings > Editor.
Query Tabs (Client-Side)
Query tabs execute the full query and receive all results. For large result sets, TablePro paginates client-side without re-querying. Sorting is done locally on cached results.
Configure page size in Settings > Editor: Small (100), Medium (500), Large (1,000), or Custom (10-100,000).
Right-click any tab:
| Action | Description |
|---|
| Duplicate Tab | Create a copy of this tab |
| Pin Tab / Unpin Tab | Toggle pin state |
| Close Tab | Close this tab |
| Close Other Tabs | Close all except this one (respects pins) |
From External Clients
Raycast, Cursor, Claude Desktop, and other MCP clients can list and focus tabs across windows. Four MCP tools cover the surface:
list_recent_tabs enumerates open tabs across every window.focus_query_tab brings an existing tab to the front by id.open_connection_window opens a saved connection.open_table_tab opens a specific table.
The Raycast extension’s Recent Tabs command wraps these tools. See MCP Tools for input and output schemas.
