Skip to main content

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.

​
SQL Favorites

Save queries you run often. Organize them in folders, assign keyword shortcuts, and expand them inline via autocomplete.

​
Creating a Favorite

Three ways to save a favorite:
  • From the editor: Right-click selected SQL > Save as Favorite
  • From query history: Right-click an entry > Save as Favorite
  • From the sidebar: Click + New Favorite in the Favorites tab
Enter a name, the SQL text, and optionally a keyword and scope.
Creating a new SQL favorite

​
Keyword Expansion

Assign a unique keyword to a favorite (e.g., selall). Type the keyword in the editor and it appears as an autocomplete suggestion. Select it to insert the full SQL. Keywords must be unique across all favorites in the same scope.
Keyword expansion in autocomplete

​
Browsing and Managing Favorites

Switch to the Favorites tab in the sidebar to browse saved queries. Double-click a favorite to insert it into the editor. Right-click to edit, copy, run, move, or delete.

​
Folders

Organize favorites into folders. Right-click in the Favorites sidebar to create, rename, or delete folders. Drag favorites between folders.

​
Scope

Each favorite is either global or connection-scoped:
ScopeBehavior
GlobalVisible in all connections
ConnectionVisible only in the connection where it was created
Set the scope when creating or editing a favorite.

​
Linked SQL Folders

Link a folder of .sql files on disk and they show up in the Favorites sidebar live. Useful for a Git repo of shared queries: clone the repo, link the folder, the team’s queries appear next to your DB-stored favorites.

​
Adding a folder

In the Favorites sidebar, click the + at the bottom and choose Add Linked SQL Folder… Pick any folder. Subfolders nest in the sidebar in the same shape as on disk. Add as many folders as you want, and assign each one to a specific connection or leave it global. To set the scope, right-click an existing linked folder and use Add Another SQL Folder… to add more, or open Settings > Editor > Linked SQL Folders to toggle which connection each folder belongs to. Global folders show in every connection’s Favorites tab. Per-connection folders show only when that connection is active.

​
Editing files

Click a linked file to open it as a regular editor tab. Cmd+S writes back to disk in the file’s original encoding. UTF-8, UTF-16, ISO Latin-1 and a few others are auto-detected on load and preserved on save. If the file was modified outside TablePro since you opened it, two things happen:
  • A yellow banner appears above the editor with a one-click Reload from Disk.
  • If you save anyway, TablePro shows a side-by-side diff sheet with Keep My Changes, Reload from Disk, and Cancel.
External edits propagate to the sidebar within about a second via FSEvents. Drop a new file into the folder and it appears. Delete a file in Finder and the row disappears. git pull triggers the same refresh. Non-UTF-8 files show a yellow warning triangle in the sidebar. Saving works in their native encoding. If you type a character that doesn’t fit (e.g., an emoji into ISO Latin-1), the save fails with a clear error so you don’t silently lose data.

​
Frontmatter

Top-of-file SQL comments set the display name, autocomplete keyword, and tooltip: 
-- @name: Active Users (24h)
-- @keyword: dau
-- @description: Daily active users from the last 24 hours
SELECT user_id, last_seen
FROM users
WHERE last_seen > NOW() - INTERVAL 24 HOUR;
KeyEffect
@nameDisplay name in the sidebar. Falls back to the filename without .sql.
@keywordAutocomplete trigger. Type the keyword in the editor and the file content expands as a query.
@descriptionOptional. Shown in tooltips.
The parser stops at the first non-frontmatter line, so put these at the very top of the file. UTF-8 BOM at the start of the file is handled. Files without frontmatter still appear, with the filename as the display name and no keyword registered. To edit frontmatter without opening the file, right-click a linked row and choose Edit Metadata… The dialog rewrites only the leading comment block and preserves the rest of the file plus its original encoding.

​
Drag and drop

Drag a row from the Favorites sidebar (linked or DB-stored) onto the SQL editor to insert its content at the cursor.

​
Removing files and folders

Press Delete on a linked file or right-click > Move File to Trash. The file goes to the macOS Trash and stays recoverable from Finder. Right-click a linked folder root for Disable, Reload, Copy Path, Show in Finder, Add Another SQL Folder…, or Remove from Sidebar. Removing only unlinks the folder from TablePro. Files on disk stay where they are.

​
Storage

Linked folder paths live in UserDefaults under com.TablePro.linkedSQLFolders. Parsed metadata (name, keyword, mtime, size, encoding) is cached in linked_sql_index.db under ~/Library/Application Support/TablePro/ so the sidebar renders without re-reading every file. File content always lives on disk. Linked folder paths are not part of iCloud Sync. Each Mac links its own copy of a shared repo.

​
Storage

Favorites live in a SQLite database (sql_favorites.db) in ~/Library/Application Support/TablePro/. Search covers name, keyword, and query text.