Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion connections/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,7 @@ Red for production, green for development. On production, set **Safe Mode** to *
| **Groups** | Folders in the connection list, nested up to three levels. Choose **File > New Group…**, or right-click empty space for **New Group…**. Right-click a group for **Rename**, **Edit Group…**, **New Subgroup…**, **Color**, **Move Group To**, and **Delete Group…**. **Edit Group…** changes the name, icon, color and parent group in one sheet. Deleting a group deletes its subgroups too and leaves the connections inside ungrouped rather than deleted |
| **Tags** | Several per connection, each with a name and color. Type a tag's name in the search field and pick it to filter by it, or choose tags from **Filter by Tag** in the **View Options** menu. With two or more chosen, **Match** switches between any and all of them, and **Clear Filters** removes them |
| **Favorites** | Right-click a connection and choose **Add to Favorites**, or drag it onto the **Favorites** header. Favorites gather in a section at the top while the connection keeps its place in its group |
| **Projects** | One project per product, each holding groups and connections. Choosing one from the pop-up button at the leading edge of the toolbar narrows the list, its search, **Favorites** and **Recent** to it. See [Projects](/connections/projects) |
| **Recent** | The five connections you opened last, favorites left out. Right-click one for **Remove from Recent**, or the section header for **Clear Recent**. To hide the section, turn off **Show recent connections** in [General settings](/customization/general-settings#connections) |

A connection's icon, group, tags, and favorite sync through iCloud, and so does a group's icon, to the iPhone and iPad app as well, unless it is marked local only. See [iCloud Sync](/features/icloud-sync).
Expand Down Expand Up @@ -124,4 +125,4 @@ Right-click a connection to edit or delete it, or select it and press `Delete`.

Connections are stored in `~/Library/Application Support/TablePro/connections.json` with their passwords in the macOS Keychain, so copying that file to another Mac restores the connections without the passwords. Each save keeps the file it replaces as `connections.json.backup`. A connection this version cannot read is kept as it is and the others load; it stays in the file, or moves to `connections.json.unreadable-records` when the file changed outside TablePro. A file that no longer reads as a list is restored from the backup, and the damaged copy is kept as `connections.json.unreadable`.

Right-clicking the Dock icon lists saved connections under **Open Connection**.
Right-clicking the Dock icon lists saved connections under **Open Connection**: those of the active [project](/connections/projects), or all of them in **All Connections**.
87 changes: 87 additions & 0 deletions connections/projects.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
---
title: Projects
description: Keep one product's connections, saved queries and history apart from the rest
---

The pop-up button at the leading edge of the welcome window's toolbar names what the list shows. It starts on **All Connections**, which is built in and shows everything. Choose a project there, or under **File > Project**, and the connection list narrows to it, along with its search, **Favorites** and **Recent**.

<Frame caption="All Connections is checked until you choose a project">
<img className="block dark:hidden" src="/images/connection-projects.png" alt="Welcome window with the project pop-up button open on All Connections, Acme, Globex, New Project and Manage Projects, over a list of Acme and Globex groups" />
<img className="hidden dark:block" src="/images/connection-projects-dark.png" alt="Welcome window with the project pop-up button open on All Connections, Acme, Globex, New Project and Manage Projects, over a list of Acme and Globex groups" />
</Frame>

## Create a project

<Steps>
<Step title="Choose New Project…">
It is at the foot of the pop-up button's menu and under **File > Project**.
</Step>
<Step title="Name it">
Type a name and click **Create**. A name another project holds is refused, whatever its case.
</Step>
<Step title="Fill it">
The list switches to the new project and reads **No Connections in** with its name. Add a connection with the button under that, or go back to **All Connections** and move connections in.
</Step>
</Steps>

## Move connections into a project

A project holds top-level groups and ungrouped connections. Right-click one and choose **Move to Project**, then the project, or **None** to take it out of every project. Select several first to move them together. **Edit > Undo** puts a move back.

- A group takes its subgroups and their connections along.
- A connection inside a group has no **Move to Project**. Move its top-level group, or take the connection out of the group first.
- A connection is in one project at most.

While a project is active, a new connection, a new group and an import land in it. An imported file that names a project of its own keeps it: a project with that name is reused, and a missing one is created.

## What follows the active project

| Place | What it lists |
|---|---|
| Welcome window | The project's groups and connections. Search, **Favorites** and **Recent** stay inside it |
| [**Switch Connection**](/connections#switch-connections-and-databases) | The project's saved connections. A connection that is already open stays listed |
| [Query History](/features/query-history#filtering) and [Query Insights](/features/query-insights#filtering) | With the scope on all connections, the queries run on the project's connections |
| [Open Quickly](/features/open-quickly#across-connections) | Saved and recent queries of the project's connections, plus the window's own connection |
| [Compare & Sync](/features/compare-sync) and [Copy and duplicate](/features/copy-objects) | The project's connections in the connection pickers |
| The connection form | The project's groups under **Group** |
| The Dock menu | The project's connections under **Open Connection** |
| **File > Export > Export Connections…** | The project's connections |

Open windows stay open when you switch. A `tablepro://` link and a saved Shortcut still open a connection of another project, since they name it by id.

A search that finds nothing inside a project offers **Search All Connections**, which switches to **All Connections** and keeps the text you typed.

## Manage projects

Choose **Manage Projects…** from the pop-up button or from **File > Project**.

<Frame caption="Rename a project in its row">
<img className="block dark:hidden" src="/images/connection-projects-manage.png" alt="Projects sheet listing Acme and Globex over add and remove buttons, with a Done button" />
<img className="hidden dark:block" src="/images/connection-projects-manage-dark.png" alt="Projects sheet listing Acme and Globex over add and remove buttons, with a Done button" />
</Frame>

| To | Do this |
|---|---|
| Add | Click **+** and type the name |
| Rename | Edit the name in its row and press `Return` |
| Reorder | Drag a row. The pop-up button and **File > Project** list projects in this order |
| Delete | Select the project and click **−**, then **Delete** |

Deleting a project keeps its connections and groups. They leave the project and show under **All Connections**, and when the deleted project was the active one, so does the list.

## Per device

Projects, and the one that is active, stay on the Mac they were set on. iCloud Sync does not carry them.

## Outside clients

Switching project also narrows what other programs are offered:

| Client | What follows the project |
|---|---|
| [MCP clients](/developers/mcp-tools#the-active-project) | `list_connections` and the connections resource. A call that names a connection of another project by id is refused |
| The [`tablepro` command](/integrations/terminal#what-a-query-may-do) | `connections`, and the names and ids `-c` accepts |
| [AppleScript](/developers/applescript#objects) | The `connections` list |
| [Shortcuts](/integrations/shortcuts) | The connections the picker offers. A shortcut that already holds a connection still runs |

The assistant inside TablePro is not narrowed: it works on its own window's connection. A project only narrows. Tokens, **External Clients** and approvals apply as before, so a client reaches nothing through a project that it could not reach without one.
3 changes: 2 additions & 1 deletion developers/applescript.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,8 @@ application
```

`connections` lists every saved connection whose **External Clients** level is not Blocked, sorted
by name. Reach one by name or by id.
by name. With a [project](/connections/projects) active, it lists that project's connections only.
Reach one by name or by id. An id also reaches a connection of another project.

```applescript
tell application "TablePro"
Expand Down
2 changes: 1 addition & 1 deletion developers/mcp-protocol.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -329,7 +329,7 @@ TablePro's own error codes live in `-33000` and above. The `-32000` block is fro
| `-33003` | 200 | Request timeout. The statement or the handler deadline ran out. |
| `-33005` | 413 | Payload too large. The body cap is 10 MB. |
| `-33006` | 503 | Server disabled. |
| `-33007` | 403 | Forbidden. Token scope, connection allowlist, AI policy, or external access rejected the call. |
| `-33007` | 403 | Forbidden. Token scope, connection allowlist, AI policy, external access, or [the active project](/developers/mcp-tools#the-active-project) rejected the call. |
| `-33008` | 401 | Token expired. |
| `-33009` | 401 | Unauthenticated. No token, or an unknown or revoked one. |
| `-33010` | 429 | Rate limited. Carries `Retry-After`. |
Expand Down
11 changes: 10 additions & 1 deletion developers/mcp-tools.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,15 @@ Past the scope, a call clears three more gates:
2. **Connection policy.** **External Clients** set to **Blocked** hides the connection: `list_connections` omits it and any tool that names it is refused. An AI policy of **Never** does the same, except that [`purpose: "display"`](#listing-for-display) still lists it. Otherwise the first call that touches a connection asks the user, as often as **Settings > MCP > Approval** says. That question is always a dialog on the user's Mac, never an elicitation: a client that could answer it could also grant itself the connection. It has no deadline, so the client owns the timeout, and a refusal stands for 60 seconds before the question can be put again.
3. **Safe Mode.** A write goes through the connection's Safe Mode, which may ask the user to confirm it or to authenticate. See [Approvals](/developers/mcp-protocol#approvals-and-input-required).

### The active project

When the user has a [project](/connections/projects) active in TablePro, `list_connections` and the [`tablepro://connections`](/developers/mcp-resources) resource hold that project's connections only. A tool that names a connection of another project by id is refused with `-33007` and the text "This connection is in another project. Switch to that project or to All Connections in TablePro to reach it."

- The user switches project in the app, so the answer can change between two calls of one client.
- With **All Connections** chosen, nothing is narrowed.
- The scope only narrows. The token, the allowlist, the connection policy and Safe Mode are checked as before.
- TablePro for Linux and Windows return a tool error with the code `out_of_scope` instead. See [Linux tools](/integrations/mcp-clients#linux-tools).

`completion/complete` clears the same connection policy without asking: on a connection this client is not approved for, it completes nothing. See [Context matters](/developers/mcp-prompts#context-matters).

A call that opens a connection may also need approval on the Mac for a pre-connect script, environment variables, or [local sign-in credentials](/connections/connection-form#sign-ins-from-this-mac). A refusal returns `denied`; an unanswered prompt returns `timeout`.
Expand Down Expand Up @@ -91,7 +100,7 @@ To read a value that was cut, select part of it with a narrower query. To get mo

`switch_database` and `switch_schema` move what the user sees: the sidebar, and the tab strip, which lists the tabs of the database or schema the connection is on. The user's other tabs stay open under their own database.

`list_connections` omits connections blocked for external clients, connections whose AI policy is **Never**, and connections outside the token's allowlist. Its `database` is the session's browsed database when connected, the saved default otherwise.
`list_connections` omits connections blocked for external clients, connections whose AI policy is **Never**, connections outside the token's allowlist, and connections outside [the active project](#the-active-project). Its `database` is the session's browsed database when connected, the saved default otherwise.

The labels the user gave a connection come with it, so a client can show the list the way the app does:

Expand Down
2 changes: 2 additions & 0 deletions docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -231,6 +231,7 @@
"icon": "plug",
"pages": [
"connections/index",
"connections/projects",
"connections/connection-form",
"connections/urls",
"connections/ssh-tunneling",
Expand Down Expand Up @@ -465,6 +466,7 @@
"pages": [
"windows/data-grid",
"windows/browsing",
"windows/projects",
"windows/account"
]
}
Expand Down
1 change: 1 addition & 0 deletions features/mcp.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,7 @@ Every request needs a token, including one from your own Mac. The server supplie

- Clients work through your saved connections. Passwords never leave the Keychain and are not readable over MCP.
- AI access is set per connection, including blocking a connection from external clients entirely. A blocked connection is not even listed.
- With a [project](/connections/projects#outside-clients) active, clients are offered that project's connections only. A project narrows the list and grants nothing.
- Tokens carry scopes and can be limited to named connections. A request without one gets `401`, from your own Mac too. See [No token, no access](/developers/tokens#no-token-no-access).
- Writes go through the connection's [Safe Mode](/features/safe-mode#external-clients). Destructive statements need a full-access token and approval every time. See [the confirmation tool](/developers/mcp-tools#writing-data).
- Reads use the driver's read-only mode where supported. Statements that access files or run server-side code are refused. [What Read Only allows](/developers#what-read-only-allows) covers engine limits and other refusals.
Expand Down
2 changes: 1 addition & 1 deletion features/open-quickly.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ The **Connections** and **Queries** scopes reach into every connected window, an

An empty search groups results under each connection's name. Once you type, everything is ranked in one list and each row names the connection, database, and schema it belongs to; the path is matched too, so typing a connection's name narrows the list to it. Opening a result brings that connection's window forward.

**Queries** holds your saved queries plus up to 200 recent ones, drawn evenly across connections rather than by raw recency, with execution times on the recent rows. Global saved queries open in the connection you opened the panel from, which stays listed even while it is reconnecting.
**Queries** holds your saved queries plus up to 200 recent ones, drawn evenly across connections rather than by raw recency, with execution times on the recent rows. Global saved queries open in the connection you opened the panel from, which stays listed even while it is reconnecting. With a [project](/connections/projects) active, the queries of other connections come from that project only.

<Frame caption="Query history results from two open connections">
<img src="/images/quick-switcher-cross-connection-queries.png" alt="Open Quickly showing query history from Chinook and Analytics connections" />
Expand Down
2 changes: 1 addition & 1 deletion features/query-history.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Recent queries also appear in [Open Quickly](/features/open-quickly). For the su

| Control | What it does |
|---------|--------------|
| Scope | This connection, or all connections |
| Scope | This connection, or all connections. With a [project](/connections/projects) active, all connections means the project's |
| Source | Which parts of the app a query came from |
| Date | Last hour, today, last 7 days, last 4 weeks, all time |
| Outcome | Any, succeeded, or failed |
Expand Down
2 changes: 1 addition & 1 deletion features/query-insights.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ Two things stay apart: table and column names keep their capitalization, since `

| Control | What it does |
|---------|--------------|
| Scope | This connection, or all connections |
| Scope | This connection, or all connections. With a [project](/connections/projects) active, all connections means the project's |
| Source | Which parts of the app the queries came from |
| Date | Last hour, today, last 7 days, last 4 weeks, all time |

Expand Down
Binary file added images/connection-projects-dark.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/connection-projects-manage-dark.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/connection-projects-manage.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/connection-projects.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/windows-connection-projects-dark.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/windows-connection-projects.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 3 additions & 1 deletion integrations/mcp-clients.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -205,6 +205,8 @@ Call it again to check for `open`.

Arguments marked `?` are optional. Unknown arguments are rejected.

With a [project](/linux/connect#projects) picked in the app, `list_connections` holds that project's connections. A call that names a connection of another project by id fails with a tool error whose text starts with `out_of_scope`. Picking that project, or **All Connections**, in the app clears it.

| Tool | Arguments | Result |
|---|---|---|
| `list_connections` | None | Saved connections visible to clients, their open state, external access and Safe Mode |
Expand Down Expand Up @@ -301,7 +303,7 @@ The bridge is newer than the app it found. Update TablePro.

### Forbidden (`-33007`)

**External Clients** is **Blocked**, the connection's AI policy is **Never**, or the token's allowlist excludes it. Any of the three also hides the connection from `list_connections`, except that a launcher token granted [`connections:display`](/developers/mcp-tools#listing-for-display) still lists a connection whose AI policy is **Never**.
**External Clients** is **Blocked**, the connection's AI policy is **Never**, the token's allowlist excludes it, or it is outside the [project](/connections/projects) active in TablePro. Any of the four also hides the connection from `list_connections`, except that a launcher token granted [`connections:display`](/developers/mcp-tools#listing-for-display) still lists a connection whose AI policy is **Never**.

### Unauthenticated (`-33009`)

Expand Down
2 changes: 1 addition & 1 deletion integrations/shortcuts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ The iOS app's build is under **Settings > About**; it ships on its own schedule,
In a new shortcut, add **Run Query** and type the statement, such as `SELECT count(*) FROM orders`.
</Step>
<Step title="Pick the connection">
**Connection** lists every saved connection whose **External Clients** level is not Blocked.
**Connection** lists every saved connection whose **External Clients** level is not Blocked, or those of the active [project](/connections/projects). A shortcut keeps the connection it was saved with.
**Database or Schema** is optional and works as it does for the insert actions.
</Step>
<Step title="Choose the result">
Expand Down
2 changes: 1 addition & 1 deletion integrations/terminal.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,7 @@ Pairing refusal or expiry also exits 3. See [Status and pairing](#status-and-pai

The command follows the [MCP connection access rules](/features/mcp#connection-access):

- **Blocked** connections, an AI policy of **Never**, and connections outside the token's allowlist are hidden. Naming one exits 2.
- **Blocked** connections, an AI policy of **Never**, connections outside the token's allowlist, and connections outside the active [project](/connections/projects) are hidden. Naming one exits 2.
- Writes need both a **Read & Write** token and **Read & Write** external access. `--read-only` still refuses them.
- **Approval** in **Settings > MCP** controls connection approval. [Safe Mode](/features/safe-mode) also applies to writes.
- Destructive statements such as `DROP`, `TRUNCATE`, `ALTER ... DROP` and `DELETE` without `WHERE` are refused. Run them in the app. Statements that access files or run server-side code are also refused.
Expand Down
Loading
Loading