Skip to main content
open "mysql://…" goes to whichever app claims the mysql:// scheme, and with another database client installed that may not be TablePro. Name TablePro instead, either by bundle identifier or through the tablepro command:
Any connection URL works, including its query parameters. TablePro uses a saved connection when one matches on type, host, port, database and user; otherwise the session is temporary and never written to disk. Running tablepro with no argument opens the app and nothing else.

​
Add the tablepro command to your PATH

The command ships inside the app at TablePro.app/Contents/SharedSupport/bin/tablepro. It runs query and connections itself and hands anything else to open -b com.TablePro. Link it into /usr/local/bin once:
sudo asks for your password in Terminal. TablePro itself never writes outside its own folders and never asks for an administrator password. Settings > General > Command Line prints the same line with the path of the copy you are running, and reads Linked once the link is in place. Any other directory on your PATH works too, and one you own needs no sudo.
Command Line section in TablePro settings with the Terminal command to link tableproCommand Line section in TablePro settings with the Terminal command to link tablepro

The Command Line section in Settings > General

To remove it, run sudo rm /usr/local/bin/tablepro. The link follows the app, so updating TablePro updates the command; move the app and the link needs making again.

​
Open a file

Files route the same way, whether double-clicked in Finder or passed on the command line:
  • .sql, .psql and .pgsql open in a query tab on the current connection. A window already holding that file comes to front. With no connection open, the file waits until you connect.
  • Database files open a connection to the file itself and save nothing: .db, .db3, .s3db, .sl3, .sqlite, .sqlite3 and .sqlitedb open with SQLite, .duckdb and .ddb with the DuckDB plugin. A window already connected to that file comes to front instead of a second one opening.

​
Run a query

--connection takes a saved connection’s name or its id, and tablepro connections lists both. The SQL comes from the argument, from -f <file>, or from standard input. Rows go to standard output, messages and errors to standard error. Pass --format in a script rather than relying on the terminal check. A result cut short by --limit says so on standard error.

​
Output formats

Every value is text, as in the grid. Binary columns come out as Base64. Two columns with the same name become name and name_2 in JSON.

​
Pair the command

The command reaches TablePro through its MCP server, so turn on Enable MCP Server under Settings > MCP first. With it off, every run exits 3. When TablePro is not running, the command starts it in the background, with no window.
1

Run any query in Terminal

TablePro asks Allow tablepro command to access TablePro?
2

Choose what the command may do

The sheet starts at Read Only. Pick Read & Write if your scripts write, and limit the connections or set an expiry if you want.
3

Approve

Your browser opens a page saying the command is paired. Close it. The query you ran continues.
The token lives in your login Keychain. Revoke it under Settings > MCP and the next run exits 3; the run after that asks to pair again. A run whose standard error is not a terminal, such as a cron job, exits 3 instead of opening the sheet.

​
What a query may do

A query clears the same gates as any MCP client:
  • The connection’s External Clients level: Blocked hides it, Read Only refuses writes.
  • A connection whose AI policy is Never is refused.
  • The first query on each connection asks you, as often as Approval under Settings > MCP says.
  • Safe Mode confirms or authenticates writes on your Mac.
  • DROP and TRUNCATE are refused. Run them in TablePro.
  • One statement per run. A SQL Server script runs batch by batch at its GO lines and prints every result set, separated by a blank line, or in JSON as one array per result set.
Every statement goes to the execution audit log, and to the history drawer under Command Line.

​
List connections

Each entry has the connection’s name, id and type, never a host, user or password. The list leaves out connections the command may not reach. The first time a link connects, TablePro asks: Open External Database Connection?, showing the host, user and database. This is what stops a web page from opening a connection behind your back. For a database on your own machine (localhost, 127.0.0.1, ::1, or any 127.x.x.x address) the alert adds Always Allow. Choose it and that database stops asking, which is what makes ddev tablepro a one-step command. Trust is keyed on database type, host, database name, user and the URL’s name parameter, not the port, so a tool that picks a new port on each start stays trusted.
Alert asking to confirm an external database link, with Always Allow for local databasesAlert asking to confirm an external database link, with Always Allow for local databases

The confirmation alert for an external database link

A link to a remote host asks every time. Only a database on this machine can be trusted.
Settings > General > Trusted Links lists what you have trusted, with Forget per entry and Forget All. Two things still prompt even on a trusted connection: a link carrying a filter (?query=, ?condition= or ?raw=) confirms the filter, and a connection with a pre-connect script shows the script.