> ## 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

> Each tab keeps its own SQL, results, pagination, sorting, and filters across restarts

# 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.

<Frame caption="Tab bar with multiple query and table tabs">
  <img className="block dark:hidden" src="https://mintlify.s3.us-west-1.amazonaws.com/ngquct/images/tabs.png" alt="Query Tabs" />

  <img className="hidden dark:block" src="https://mintlify.s3.us-west-1.amazonaws.com/ngquct/images/tabs-dark.png" alt="Query Tabs" />
</Frame>

## 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 |

Change tracking is available in table tabs by default. Query tabs support change tracking only for simple `SELECT * FROM table` results.

### Smart Tab Reuse

Clicking a table you already have open just switches to it. With preview tabs on (the default), clicking a different table reuses the active tab in place. A tab with unsaved edits, an applied filter, or sorting is never replaced: the click opens a new tab and leaves your work alone. Double-click a table to open it in its own permanent tab.

### 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)

A preview tab that is still open when you quit is restored as a permanent tab on next launch.

<Tip>
  Disable preview tabs in **Settings** > **Tabs** if you prefer every click to open a permanent tab.
</Tip>

<Frame caption="Different tab types: Query and Table">
  <img className="block dark:hidden" src="https://mintlify.s3.us-west-1.amazonaws.com/ngquct/images/tab-types.png" alt="Different tab types: Query and Table" />

  <img className="hidden dark:block" src="https://mintlify.s3.us-west-1.amazonaws.com/ngquct/images/tab-types-dark.png" alt="Different tab types: Query and Table" />
</Frame>

## 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           | Double-click a table in the sidebar (single-click reuses the preview tab) |

### Closing Tabs

| Action             | How                                |
| ------------------ | ---------------------------------- |
| Close current tab  | `Cmd+W`                            |
| Close specific tab | Hover and click **x**              |
| Close other tabs   | Right-click > **Close Other Tabs** |

<Warning>
  Closing a tab with unsaved changes discards those changes. TablePro warns you before closing if there are pending data modifications.
</Warning>

### Switching Tabs

* `Cmd+1` through `Cmd+9` to jump by position
* `Cmd+Shift+[` / `Cmd+Option+Left` for previous tab
* `Cmd+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.

<Frame caption="Drag and drop tab reordering">
  <img className="block dark:hidden" src="https://mintlify.s3.us-west-1.amazonaws.com/ngquct/images/tab-reorder.png" alt="Drag and drop tab reordering" />

  <img className="hidden dark:block" src="https://mintlify.s3.us-west-1.amazonaws.com/ngquct/images/tab-reorder-dark.png" alt="Drag and drop tab reordering" />
</Frame>

### 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**.

<Frame caption="Pinned tab with pin indicator">
  <img className="block dark:hidden" src="https://mintlify.s3.us-west-1.amazonaws.com/ngquct/images/pinned-tab.png" alt="Pinned tab with pin indicator" />

  <img className="hidden dark:block" src="https://mintlify.s3.us-west-1.amazonaws.com/ngquct/images/pinned-tab-dark.png" alt="Pinned tab with pin indicator" />
</Frame>

### 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 and cursor position | Pending data changes                 |
| Tab type and table name         | Selected rows                        |
| Applied sort, filters, and page |                                      |
| Column widths                   |                                      |
| Active database and schema      |                                      |
| Pin state                       |                                      |

Tab state auto-saves 500ms after any change, plus a background save every 30 seconds so a crash or force quit keeps your recent work. On reconnect, TablePro restores your tabs and re-runs table queries with the sort, filters, and page you left them on. Connections reconnect lazily, when you first interact with a restored tab, so launch stays fast and unreachable hosts do not block startup.

Whether the session reopens on launch is controlled by [Startup Behavior](/customization/settings#general), which defaults to reopening your last session.

### Multi-Window Restoration

Tabs restore in their original order across launches. If a previous session was recovered after a crash, TablePro reopens each connection that had open tabs.

### 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.

## Pagination

### 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**.

<Frame caption="Server-side pagination in a table tab">
  <img className="block dark:hidden" src="https://mintlify.s3.us-west-1.amazonaws.com/ngquct/images/tab-pagination.png" alt="Server-side pagination in a table tab" />

  <img className="hidden dark:block" src="https://mintlify.s3.us-west-1.amazonaws.com/ngquct/images/tab-pagination-dark.png" alt="Server-side pagination in a table tab" />
</Frame>

### 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).

## Tab Context Menu

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) |

<Frame caption="Tab context menu">
  <img className="block dark:hidden" src="https://mintlify.s3.us-west-1.amazonaws.com/ngquct/images/tab-context-menu.png" alt="Tab context menu" />

  <img className="hidden dark:block" src="https://mintlify.s3.us-west-1.amazonaws.com/ngquct/images/tab-context-menu-dark.png" alt="Tab context menu" />
</Frame>

## 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](/external-api/raycast#commands) wraps these tools. See [MCP Tools](/external-api/mcp-tools) for input and output schemas.