A page for every feature: what it is, how to use it, and how it works underneath. The specifications are at the end.
Get started
Install the app, add a connection, and find your way around the window.
Install DBClient
DBClient ships as a signed and notarized disk image, and as a Homebrew cask. Both install the same app, and both are kept current by the app's own updater.
How to
Download DBClient.dmg, open it and drag the app to Applications. There is no "unidentified developer" step: the build is notarized by Apple.
Or install it with Homebrew: brew install --cask az-code-lab/taps/dbclient. Later releases arrive with brew upgrade, which quits the running app and reopens the new version, or through the app.
To check what you downloaded, run spctl -a -vv /Applications/DBClient.app. The answer names the Developer ID and says accepted.
To remove it, delete the app, or run brew uninstall --zap dbclient to remove its files as well.
The app, every library inside it and the disk image are signed with a Developer ID certificate under the hardened runtime, then notarized and stapled.
Saved passwords are Keychain items under the service dev.azcode.dbclient.connections; delete them in Keychain Access if you want them gone. Everything else the app keeps is listed under Where things are stored.
Your first connection
A connection is an engine, an address and a way to sign in. You can paste all of it as one connection string into the box at the top of the picker, or pick a tile and fill in the fields.
The picker a new connection starts on: a box for a pasted connection string, then the engines, the hosted services and the hosts, each on a card of its own.
How to
Click Add Connection under the sidebar, or press ⌘K and choose Add Connection…
Paste a connection string, an ssh command or a file path into the box at the top of the picker: the tile of the engine it names lights up, the line under the title says what it opens as, and Continue or Return opens that engine's form with the fields filled in. Text the app cannot read turns that line red. Or pick the engine or the hosted service yourself; a service tile sets the port and the SSL mode that service expects.
On the form, paste a connection string into Connection String and the fields fill themselves in, or type the Host, Port, Database, User and Password. For SQLite and DuckDB, click Choose… to pick a file or New… to create one.
Leave Save Password off to be asked each time you connect, or turn it on to keep the password in your Keychain.
Click Test Connection, then Add. A new connection is tried before it is filed; if the server does not answer, the sheet stays open and offers Add Anyway.
Double-click the connection in the sidebar to connect, or click its caret, or right-click it and choose Connect. Click a database to see its overview, a table to browse its rows, or press ⌘T for a query tab.
Oracle and IBM Db2 offer to download their maker's client library the first time. See Oracle and IBM Db2 clients.
Around the window
One window holds every connection. The sidebar is the map, the tab strip is what you have open, and each tab is an editor above its results.
One window: the sidebar, the tab strip and the toolbar, an editor above its results, and the status bar with the pager.
Sidebar. Folders of connections; under a connection its databases, and on PostgreSQL, SQL Server and Databricks the schemas inside each database; under those a folder per kind of object, plus Queries, Diagram and the accounts folder. ⌥⌘S hides and shows it. See The sidebar.
Tab strip. One strip across all connections. ⌘T opens a query tab, the terminal button a console, the grid button every open tab at once.
Toolbar. The connection menu, which lists your connections the way the sidebar does: folder by folder, under the same names. Then the boxes that say where the tab works — the database, and on the engines with schemas the schema; on PostgreSQL, SQL Server and Databricks the three read connection, database, schema — then Run, Explain, Watch, Auto-Commit, Inspector, AI Assist and Commands. The connection menu and the database and schema boxes act for a query tab, which they carry to the connection, database or schema you pick. In front of a console, a designer, a listing, the overview or a diagram they read as plain labels naming where the tab is: such a tab stays put. The connection menu is the one place that moves a tab to another connection: a click on a connection or a database in the sidebar brings that connection forward and leaves your tab where it is. An SSH host picked in the menu comes forward without the tab, since a host has no editor to run a query in. Double-click an empty part of the toolbar to zoom the window, or to minimize it, whichever System Settings ▸ Desktop & Dock says a double-click on a window's title bar does; with Do Nothing chosen there, it does nothing here too.
Status bar. The connection's state, what the last run returned, the pager, and any pending changes with Discard and Commit…
Technical notes
A tab belongs to one connection and one database. Changing the database of one tab never changes another's.
On PostgreSQL, SQL Server and Databricks a tab belongs to one database of the server, and to a schema inside it. The database box moves a query tab to another database of the server, opening that database if it is not open; the tab's text goes with it, as with the connection menu.
SQL Server reads a name written without its schema in the login's default schema, and no statement changes that, so the schema box there only names the schema: it is where a new table made from the tab lands. A USE run in a tab moves that tab to the database it names, with its results and its connection. A result that was already on screen stays with the database it came from: see Results.
Twelve engines, the hosted services built on them, and the ways to reach a server safely.
Engines and server versions
Every engine gets the sidebar, the grid, the assistant and a door to its own console client. The kinds of object that exist on an engine are the kinds it shows. The version ranges below come from each driver's own documentation, or from the catalog queries the app needs; a range is where things are known to work, not a promise about every release.
PostgreSQL
Default port
5432
SSL
Disabled, Required, Verify Certificate
Servers
PostgreSQL 11 and newer: the schema browser reads pg_proc.prokind, which arrived in 11.
Console
psql — brew install libpq
Values
Every value arrives as the text psql prints for it, whatever its type — intervals, arrays, ranges, network addresses, json, money, extension types — and an edit, a Copy as INSERT, an export or a transfer writes that text back, so the stored value comes back the same.
Notes
If you leave Database blank, PostgreSQL starts in the database named after your username. The sidebar lists all the databases you can open on that server with the same login. Every designer, including aggregates, conversions, operators, operator classes, extensions, casts and tablespaces. The fullest Users & Roles pane.
MySQL
Default port
3306
SSL
Disabled, Required, Verify Certificate
Servers
MySQL 5.7 and newer, as the driver documents.
Console
mysql — brew install mysql-client
Notes
Designers for tables, triggers, events and tablespaces. Each structure change applies at once, so a failure partway leaves the earlier changes in place; the designer says so.
MariaDB
Default port
3306
SSL
Disabled, Required, Verify Certificate
Servers
Supported through the MySQL driver, which publishes no minimum for MariaDB.
Console
mariadb — brew install mariadb
Notes
Everything MySQL gets, plus sequences.
SQLite
Connects to
A file on your Mac. No port, no SSL, no accounts.
Files
SQLite 3 database files, read with the SQLite library that comes with macOS.
Console
sqlite3 — brew install sqlite
Notes
A type, default, key or foreign-key change rebuilds the table in place, rows copied over in one transaction. Before that transaction commits, every row is checked against the foreign keys, and a row that would break one refuses the change. See The table designer.
SQL Server
Default port
1433
SSL
Disabled, Required
Servers
SQL Server 2017 and newer: the app speaks TDS 7.4 and its catalog queries use STRING_AGG. Every connection turns on the session options ODBC clients and SSMS use — QUOTED_IDENTIFIER, ANSI_NULLS, ANSI_WARNINGS, CONCAT_NULL_YIELDS_NULL, ANSI_PADDING and ARITHABORT — so a PERSISTED computed column, an indexed view or a filtered index can be created from a query tab.
Console
sqlcmd — brew install sqlcmd
Notes
One connection lists every database of the server; each opens beside the others in the sidebar, and a USE in a tab takes the tab to that database. Synonyms, partition functions and partition schemes; a DENY is kept apart from a missing grant in Users & Roles. Defaults are named constraints, so changing one needs SQL.
Oracle
Default port
1521, by Service Name or SID
SSL
Disabled, or Verify Certificate with a Wallet Folder
Servers
Oracle Database 19c and newer, as Oracle documents for its 23 client.
Console
SQL*Plus — brew install InstantClientTap/instantclient/instantclient-arm64-sqlplus — or SQLcl — brew install --cask sqlcl and brew install openjdk
Disabled, or Verify Certificate with an optional Server Certificate
Servers
Db2 for Linux, UNIX and Windows; checked against Db2 Community 12.1. Db2 for z/OS and IBM i are not supported.
Console
db2cli, which comes with the downloaded client. brew install rlwrap gives it history and line editing.
Notes
Needs IBM's CLI driver, downloaded on first use. A table is editable in the grid when its primary key is enforced.
MongoDB
Default port
27017
SSL
Disabled, Verify Certificate
Servers
MongoDB 3.6 and newer, as the driver documents.
Console
mongosh — brew install mongosh
Notes
Queries are JSON command documents; see MongoDB and Redis commands. TLS cannot be combined with an SSH or proxy tunnel yet.
Redis
Default port
6379
SSL
Disabled, Required, Verify Certificate
Servers
Redis 3 and newer; the ACL users pane needs 6.0. Valkey connects with the same driver.
Console
redis-cli or valkey-cli — brew install redis
Notes
One command per line. A SCAN reply becomes a key browser you can edit.
DuckDB and data files
Connects to
A DuckDB file, or a Data File: a CSV, TSV, Parquet or JSON file, or a folder of them.
Files
DuckDB 1.1.3 is built in. It opens files written by DuckDB 0.9, 0.10, 1.0 and 1.1; a file from a newer release may not open.
Console
None. A DuckDB file allows one process at a time, and the app is it.
Notes
A DuckDB file is opened once; every tab, and every other connection to the same file, gets a connection to that one instance. A data file is opened as a view through an in-memory DuckDB and read again on every query, so an edit to the file shows up on the next run. The view is named for the file, every character but an ASCII letter or digit written as _. In a folder, two files whose names come out alike get their extensions appended, then a number: a.csv and a.parquet are a and a_parquet. Alike means as DuckDB reads a name, without regard to letter case, so Orders.csv beside orders.json are Orders and orders_json. A TIMESTAMP_NS column shows every one of its nine digits in a browse, in Export Data… and in a copy, which read it as text; a query you type arrives at microseconds, where the built-in DuckDB hands the value over, and a result keyed by such a column is read-only, since an edit could land on another row. Type CAST(col AS VARCHAR) AS col, the browse's own spelling, to edit it.
ClickHouse
Default port
8123, the HTTP interface; ClickHouse Cloud uses 8443
SSL
Disabled, Required, Verify Certificate
Sign-in
Password, Cloud SSO or Cloud SSO (Read-Only). With SSO, click Sign In with Browser; no database password is needed. Cloud SSO (Read-Only) asks through ClickHouse Cloud's own gateway, which runs SELECT only and returns at most 384 KB of a result: a larger result is shown in smaller pages.
Console
clickhouse-client — brew install --cask clickhouse. A browser sign-in has no console.
Notes
ClickHouse has no transactions, so grid changes apply statement by statement. Keys are fixed when a table is created, and there are no foreign keys. A ClickHouse primary key is the table's sort key, which several rows may share, so before a grid edit or delete is saved the app counts the rows that share the row's key and refuses the save when there is not exactly one, naming the key. On a MergeTree table the mutation itself carries the same check, so a twin that appears in between leaves it changing nothing, and a count after the save reports that. ClickHouse allows no such check inside a mutation on a replicated table, so there the save finds the row by its key and by every other column whose value it can compare exactly, floating-point columns and arrays, maps and tuples included (an array, map or tuple is compared as the server's own JSON of it, so a map with a repeated key, or an array holding NaN, names its own row), and refuses when more than one row is the same in all of them. It then reads where the row sits in the table, the part and the offset within it, and the mutation names the row by that position and by its plain columns, in one mutation for the whole save: a row that arrives in between, even one the same in every column, sits in another part and is left alone, and a row someone else changed in between is met by nothing and reported. The part is named whole, version and all, so a row someone else deleted ahead of the saved row in between, which moves the rows behind it, leaves the save meeting nothing rather than the next row. The save first asks the server how it stores each edited value, and counts again once its changes are in and before any new row goes in: an edited row by the content it now has, against the rows that already looked like it, and a deleted row's key. A new row never stands in for a change that missed its row. A row that changed under the edit or the delete is reported, and the change kept for another try; so is a row with the same key that arrived while a delete ran, which a count by key cannot tell from a miss. An array, map or tuple is edited as JSON. Before anything is written, the server reads the text as the column's type with the rules an INSERT in JSON uses, and a value the type cannot hold, such as text that is not JSON, a word where a number belongs or a tuple with an element missing, is refused naming the field and the row. Every element is then converted exactly, and a null where the type takes none or a number past the type's range is refused too; what the server read is written back whole, so a long decimal keeps every digit and a map's key may be a number. A change the server cannot apply, such as one that would leave a nested column's arrays of different lengths, fails as it is applied, and ClickHouse keeps retrying it, holding every later change to the table behind it: the save withdraws such a change of its own and says so, with the server's reason, and while an earlier failed change still holds the table up it refuses up front, naming that change. Only the change the server names in its answer is withdrawn, never another writer's, and only on the table whose command failed: a save over joined tables changes one table at a time, since ClickHouse numbers mutations per table. A change is applied part by part, so the notice also names the rows whose changes had landed before the failure, and never says nothing changed unless every row's count says so; where two changes made their rows alike and only one landed, it says the changes may have landed. Where an edited column is one the save cannot compare, such as a FixedString or a JSON document, no count of the row's content can tell whether that part of the edit landed, whether or not the same edit changes a column the save can compare, so the save also counts, before and after, the rows that hold what it was asked to write in every edited column, and expects one more afterwards: a row that already looked like the change in every column stands in for nothing, and a change that did not land is reported and kept. That count is the server's, so it holds however many rows look alike. Text is compared byte for byte, as ClickHouse compares it: é as one character and as e with a combining accent are two values, and an edit from the one to the other is a change. NaN and the infinities show by name, nan, inf and -inf, in a float cell and inside an array, map or tuple, so an array holding NaN names its own row apart from one holding inf. The app never follows an HTTP redirect from the server: a redirect is refused with a message naming where it pointed, so your user name and password reach no other address. A DateTime or DateTime64 cell shows the server's own text, every digit of a DateTime64(9) kept, and a grid edit names its row by that text.
Databricks
Connects to
A SQL warehouse over HTTPS on port 443, certificate always verified.
Fields
Host, Warehouse ID, Catalog, Schema and an Access Token. The connection starts in that catalog and lists the workspace's other catalogs in the sidebar.
Console
dbsqlcli — pip install databricks-sql-cli
Notes
Each request runs on its own, so interactive transactions and temporary objects are not available. No SSH or proxy tunnels: the connection is direct. Timestamps arrive rounded to milliseconds, so a save does not check that a timestamp cell was unchanged since it was loaded, and a table whose primary key is a timestamp is read-only.
Hosted services
A service tile in the New Connection picker is an engine with the right defaults already set. Pick the tile, paste the host, and the port and SSL mode are what the service expects. Switching to another tile puts back whatever you had not touched.
Service
Driver
Port
SSL
Supabase
PostgreSQL
5432
Verify Certificate
Neon
PostgreSQL
5432
Verify Certificate
CockroachDB
PostgreSQL
26257
Verify Certificate
TimescaleDB
PostgreSQL
5432
Disabled
YugabyteDB
PostgreSQL
5433
Disabled
Valkey
Redis
6379
Disabled
ClickHouse Cloud
ClickHouse
8443
Verify Certificate
Technical notes
A service uses its engine's driver unchanged, so which features work depends on how closely the service follows that engine's protocol and catalogs.
Every default can be changed after the tile fills it in.
The connection editor
The editor is one sheet with up to four pages: General, Options, SSH Tunnel and Proxy. File-based engines show the first two only.
The General page of a saved PostgreSQL connection. The Connection String under the fields always spells what they hold.
How to
General holds the server: Host, Port, Database, User, Password with Save Password, the SSL mode and the Connection String. A file engine shows Database File with Choose… and New… instead.
Options holds the Name shown in the sidebar, the folder it is filed in, a Color and the Production switch.
Test Connection dials the server with what is on the sheet, without saving anything.
To change an existing connection, right-click it in the sidebar and choose Edit… Changing the engine keeps your server details and credentials.
On PostgreSQL, SQL Server and Databricks one connection reaches every database of its server: Database (Catalog on Databricks) only says which one it starts in, and left blank on PostgreSQL or SQL Server it is the one the server picks for the user. On the other engines, to make a sibling of a connection — the same server, another database — right-click it and choose Duplicate. The copy lands right under the original as "name copy", in the same folder, with the same settings, colour and saved passwords; it is not connected until you connect it.
Technical notes
An engine offers only the SSL modes it can carry out. A pasted or saved mode it cannot is moved to the strongest one it can.
Oracle's General page asks for a Service Name or an SID — the row's label is the choice — and, when SSL verifies the server, a Wallet Folder. Its Options page holds what a connection can do without: the Oracle Client row, Certificate DN (optional), which only a connection through a tunnel or proxy needs, and Call Timeout (seconds), 60 by default. IBM Db2's Options page holds the Db2 Client row, Server Certificate and Query Timeout (seconds), 60 by default.
Amazon RDS and Aurora PostgreSQL can sign in with AWS IAM: turn it on under Options, name the AWS profile and region when they are not the default ones, and the app signs a token with the credentials in ~/.aws (or AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY) at every connect, for the user named on the General page. The token lives fifteen minutes and is never stored; the password field is unused; TLS is required. The console's psql and a dump's pg_dump get the same token. MySQL's IAM sign-in needs the client's cleartext password plugin, which the app's MySQL driver does not speak.
Connection strings
The Connection String field reads a URL and fills in the fields above it, and it writes the URL for whatever the fields hold. Use it to paste what your host gave you, or to copy a connection to a colleague.
How to
Paste a string such as postgresql://user@host:5432/database, sqlite:///path/to/database.sqlite or duckdb:///path/to/file.duckdb.
If the string carries a password, Save Password turns itself on. Turn it off again to keep nothing.
Click the copy button to copy the string. It leaves the password out unless you have revealed it, and revealing a password asks for Touch ID.
Technical notes
Schemes read: postgres, postgresql, mysql, mariadb, sqlite, sqlite3, file, mssql, sqlserver, oracle, db2, mongodb, redis, rediss, duckdb, csv, tsv, clickhouse and databricks. A bare path starting with / or ~ is a file database.
Query keys read: sslmode (disable, require, verify-full), and per engine warehouse_id, schema, server_certificate, query_timeout, connect_using, wallet, certificate_dn, call_timeout and auth.
Text that is not a connection string changes nothing: the field says so and leaves the fields alone.
An IPv6 address goes in square brackets, as in postgresql://user@[::1]:5432/database. The Host field holds it without them, and the string written for it puts them back. An address with its colons outside brackets is refused, since they cannot be told from the port's.
Passwords, Keychain and Touch ID
A password is either in your Mac's Keychain or nowhere. There is no password file, and no setting that writes one.
What connecting asks when Save Password is off.
How to
Keep it: turn on Save Password. The password, and any SSH or proxy password, become Keychain items.
Keep nothing: leave Save Password off, which is how a new connection starts. Connecting then asks with a sheet titled Connect to “name”. The answer is held until the app quits, so a reconnect does not ask again; tick Save Password on that sheet to stop being asked.
Guard it: in Settings ▸ Security, Require authentication to connect asks for Touch ID or your login password each time a connection connects: a database, a file or an SSH host, with a saved password or without. It is on by default.
Technical notes
All secrets sit under one Keychain service, dev.azcode.dbclient.connections: database, SSH and proxy passwords, and AI provider keys.
Showing a saved password, or an AI provider's key, on screen always asks for Touch ID, whatever the setting.
A connection asks once. A reconnect after a dropped connection does not ask again, so it never interrupts you with a prompt; Disconnect locks the connection, and its next connect asks.
Turning Save Password off and saving removes the Keychain item.
An SSH password, a key passphrase and a proxy password have no switch: each is kept when you type one, and only then. Leave the field empty and nothing is saved; empty it and save, and its Keychain item is removed.
SSL modes
Three modes, named for what they check.
Mode
What it does
Disabled
No encryption. For localhost, or inside an SSH tunnel, which is already encrypted.
Required (no certificate check)
Encrypts the connection, without checking who is at the other end.
Verify Certificate
Encrypts, and checks the server's certificate and that it was issued for the host you typed.
Technical notes
PostgreSQL, MySQL, MariaDB, Redis and ClickHouse offer all three. SQL Server offers Disabled and Required. Oracle, IBM Db2 and MongoDB offer Disabled and Verify Certificate. Databricks is always Verify Certificate.
Verify Certificate is refused through an SSH or proxy tunnel: the driver dials the tunnel's local end, so there is no server name to check. Use Required there; an SSH tunnel has already authenticated the server.
Oracle reads its certificates from a wallet folder, and Db2 can be given a server certificate file. The other engines have no field for a private CA certificate.
SSH tunnels and proxies
Reach a database that only a bastion host can see, or one behind a corporate proxy. DBClient starts and closes the tunnel with your connection.
The SSH Tunnel page, set up for a bastion host with a private key.
How to
On the SSH Tunnel page, turn on Connect through an SSH tunnel and fill in SSH Host: a server's name, or a Host entry from your ~/.ssh/config. SSH Port and SSH User can stay blank: the placeholders show what ssh will use for that name, from the entry or from its defaults. Fill one in to override the entry, the way -p and -l do.
Choose Password or Private Key, and for a key click Choose Key… The panel opens in ~/.ssh. If the key is encrypted, enter its Key Passphrase. With no key chosen, ssh offers the keys it would offer in Terminal: the entry's IdentityFile lines, its own ~/.ssh/id_* files and the agent's.
Connect. The first time DBClient meets an SSH server, a sheet titled Trust the SSH server “name”? shows the server's key fingerprint. Compare it with the one from whoever runs the server, then click Trust and Connect. Cancel connects nothing and saves nothing.
For a proxy, open the Proxy page, turn on Connect through a proxy server, choose SOCKS5 or HTTP and fill in the host, the port and, if it wants them, a user and password.
How a server's key is checked
The server's key
What the app does
Saved, and the same
Connects. Nothing is asked.
Not saved yet
Asks, showing the fingerprint. Trust and Connect saves the key in ~/.ssh/known_hosts and connects.
Saved, but different now
Refuses the connection and names the line in known_hosts. An impersonating server looks exactly like this, and so does a server that was reinstalled.
Revoked
Refuses the connection.
This is what ssh does in Terminal, in a sheet, and it uses the same file: ~/.ssh/known_hosts. A server you trusted in Terminal is already trusted here, and one you trust here is trusted in Terminal. If you know ssh, there is nothing new to learn.
When a server has been reinstalled, its key is new and the connection is refused. Remove the old key the usual way, ssh-keygen -R host (or ssh-keygen -R "[host]:port" for a port other than 22), and connect again. DBClient asks about the new key.
Technical notes
SSH uses macOS OpenSSH and supports RSA, Ed25519 and ECDSA private keys, including encrypted keys. A matching key in the SSH agent can be used.
~/.ssh/config and /etc/ssh/ssh_config are read by ssh itself, exactly as in Terminal: Host and Match blocks, Include, HostName, Port, User, IdentityFile, IdentitiesOnly, ProxyJump, ProxyCommand, HashKnownHosts and the rest all apply to the name you give. What the form fills in outranks the entry, as command-line options outrank the config. The app sets only the tunnel's own mechanics (the forward, its control socket, keepalives, the connect limit), and never lets a config forward the agent or X11 or run a LocalCommand.
With a ProxyJump in the config, the jump host is asked about too, by its own name, the first time. The password or passphrase you enter answers the first prompt; a jump host should sign in with a key or the agent. With the app's Proxy page on as well, the proxy carries the SSH connection, and the entry's ProxyJump or ProxyCommand is set aside.
Host keys are read from and saved to ~/.ssh/known_hosts, as ssh does. ~/.ssh/known_hosts2 and the Mac-wide /etc/ssh/ssh_known_hosts are read too, which are ssh's own defaults. DBClient keeps no list of its own. A changed or revoked key is refused, with OpenSSH diagnostics naming the file and the line.
OpenSSH writes the file, not DBClient: it adds one line when you click Trust and Connect, and creates ~/.ssh if it is missing. Hashed names, patterns and @revoked lines in your file all work. A server is saved under the host name ssh dials — the entry's HostName, or the name you gave — with the port when it is not 22 ([host]:port), as ssh saves it; a HostKeyAlias in the config is honored, and new lines are hashed if the config says HashKnownHosts yes.
The fingerprint on the sheet is the SHA256 one ssh-keygen -l prints. On the server, ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub shows the same value.
Versions up to 0.1.2 saved keys in a file of their own, ~/Library/Application Support/DBClient/known_hosts, without asking. That file is no longer read, so a server saved only there is asked about once.
Test Connection and Add ask the same question. Cancelling it there is not a failed test. While the sheet is up, the 15-second authentication limit below does not run.
There is no setting that turns the check off. Connections saved with the earlier Host Key menu, including Accept Any (insecure), are checked like any other from now on.
With both pages on, the SSH connection itself goes through the proxy. An HTTP proxy is reached with CONNECT; default ports are 1080 for SOCKS5 and 3128 for HTTP. Connecting times out after 10 seconds; SSH authentication has a 15-second limit.
Every network engine can use a tunnel except Databricks. MongoDB through a tunnel reaches the one server you named, not the rest of a replica set, and cannot use TLS there.
SSH hosts and This Mac: a terminal
A server you reach over SSH can be a connection too, with no database behind it: connecting opens a terminal on it in a tab. This Mac is a second kind of host, whose terminals run your own login shell.
A Terminal tab on This Mac, running the login shell.
How to
Click Add Connection and pick SSH Host, the row under the picker's Hosts heading, or paste an ssh command into the box at the top of the picker and press Return. The General page holds the same rows as the SSH Tunnel page: SSH Host (a server's name, or a Host entry of ~/.ssh/config), the port and user you want to override, and Password or Private Key. A blank port, user or key is decided as ssh decides it in Terminal, and the placeholders show that decision. Under the rows, Connection String is the ssh command for them: paste one to fill the rows, or copy it to connect from Terminal. It reads -p, -l, -i and user@host, or an ssh:// address; a command with anything else is refused whole rather than read in part.
Test Connection dials once. The first time, the server's key is asked about in the Trust the SSH server sheet, exactly as for a tunnel. Add saves the host and connects it.
Connecting opens a Terminal tab: your shell on the server, with your profile and prompt. The tab is named by what that shell reports: most Linux shells print user@host:~/folder as the window title at every prompt, and the tab shows it and follows every cd; a shell that reports nothing leaves the tab reading Terminal. The tab bar's terminal button, ⌘T and the row's New Terminal each open another. Typing exit closes the tab; a shell that ends with an error keeps its tab, with a Restart button, so the message stays readable.
For a terminal on your own Mac, use the toolbar's Terminal button at the right of the bar, or ⌃⌘T, or Terminal on This Mac in the File menu and the ⌘K palette: it opens a terminal running your login shell in your home folder, the way Terminal starts it. The tab reads the folder the shell is in, ~ to start with, and follows every cd; a program that names itself, such as an editor, holds the tab's title while it runs. The connection behind it, This Mac, is filed for you the first time and listed nowhere, not in the sidebar and not in the picker. The terminal button at the foot of the sidebar is the selected connection's: a terminal on a host, the engine's console on a database.
Open AI Assist from the toolbar or press ⌥⌘A. Ask the assistant to explain terminal output or suggest a command for this machine. Click Insert into the terminal, then press Return to run it.
Files on the host
An SSH host's row unfolds to a Files row. It opens a Files tab: one folder of the host, listed over the same connection, with the Finder as the other side of every copy.
The Files tab of an SSH host, in the account's backups folder, with a finished copy in the log below.
Click the Files row under the host, or right-click the host and choose Browse Files… (the ⌘K palette offers Files too). The tab opens in the account's home, shown as ~, and is named by the folder it shows. Double-click a folder to open it, or the .. row at the top to go up. Every folder has that row except the root; an empty folder shows it too, with Empty folder under it. Up, Home and Refresh stand in the header, and Hidden Files shows the dotfiles: a folder that holds only dotfiles reads as empty until you turn it on. Refresh reads the folder again, and so does ⌘R, the key shown beside Refresh when you right-click the list. A spinner beside the folder's path shows the read, for half a second at the least.
To copy files to the host, drag them from the Finder onto the tab: they land in the folder on screen, or in the folder whose row you drop them on, which lights up as you hover. The copy runs in a log that opens at the bottom of the tab, the same console a query tab shows its runs in: the rsync command as the statement line, every line rsync prints, and a verdict line, with a progress line and a Stop button above while it runs. The folder is read again when it finishes. Copies asked for together run one after another; Hide Log and ⌘L fold the log away, and dragging the line above the log makes it taller or shorter. A file or folder whose name is already there is asked about first, even when it is the same: Replace writes over it (a folder file by file), Cancel copies nothing. A name is taken the way the receiving disk reads names: on a host whose disk ignores letter case, such as a Mac, readme.md is asked about where README.md stands, and so is a download into a Mac folder. Two things copied together that would be one item there, such as Makefile and makefile from a Linux host onto a Mac, are not copied, and the log names them.
To copy files from the host, drag rows out of the tab into a Finder window: the copy runs as you drop, in the same log, and the files appear where you dropped them. Or right-click a row and choose Download to…, which asks for the folder. Copy Path puts the row's path on the clipboard.
To move files or folders within the host, drag their rows onto a folder's row, or onto the .. row for the folder above: they move there, logged like a copy, and nothing is asked unless an item of the same name already stands in that folder, where Replace writes over it and Cancel moves nothing. A folder never moves into itself, nor over a folder of its own name that holds it, such as the inner archive of archive/archive dropped on ..: Replace would delete it along with that folder, so the drop is not taken.
To copy or move within the host without dragging, choose Copy or Cut on the rows (⌘C, ⌘X, or the row menu) and Paste (⌘V) in the folder you want, an empty one included. A copy pasted beside its original is named "name copy"; a name already in another folder is asked about first, by the host's own reading of names. A paste over a folder that holds what is pasted, a paste of a row onto itself through another path to its folder (a folder mounted in two places, or a Mac's own disk under /System/Volumes/Data), and a paste of two rows that would be one item there copy or move nothing, and the log says why. The same Copy pastes into a Finder window as a download, and files copied in the Finder paste into the tab as an upload.
To remove files or folders on the host, right-click the rows and choose Delete…, or press ⌫. The question names what goes and says there is no Trash on the host; the red Delete runs rm -rf over the connection, logged like a copy.
Technical notes
An SSH host keeps ONE authenticated connection open while it is connected: a control master, as ssh -M makes. Every terminal is a second ssh joining it through the master's socket, so nothing is typed or authenticated twice. Disconnect closes the master, and a master the server drops shows the row as failed, with Reconnect in its menu.
The Files tab is sftp in batch mode over the same master, and every copy is rsync — Homebrew's where it is installed, else the Mac's own — with -rlpt --progress and -e ssh pointed at the master's socket, so a copy authenticates nothing either. The host needs rsync installed; the log says so when it is missing. Before a copy runs, a dry run with --itemize-changes finds the files it would write over, inside folders too, and the side that receives the copy is asked whether a name among the sources stands there, the host over the same connection and the Mac's own disk directly: the Replace question lists both, so a file that is already there is asked about even when it is identical and rsync would transfer nothing, and a name counts as taken by that disk's own rule. Everything the dry run lists is also held to that rule, so two files a download would write under one name on the Mac are found before anything is copied. The log keeps rsync's own lines; its progress line, which rewrites itself, feeds the bar instead. It follows its last line as a terminal does: on the tail, new lines and a change of the panel's size keep the tail in view; scrolled up, nothing moves.
Every row carries its file's exact name, as the host spells it, byte for byte. A Linux server can keep café written with é and café written with e and an accent mark as two files; each is a row of its own, and a click, Delete, a move or a copy acts on that file alone. The listing is read as UTF-8, so a name in any alphabet shows as it is, and a name holding a carriage return or a line break, such as the Mac's custom-icon file Icon and a return, is listed whole, its control characters drawn as ␍ and ␊. A link is listed under its own name, which may hold an arrow; its target is not shown. A folder whose listing names one item twice — which only a name made to look like a line of the listing can do — is not shown, and the tab says to use the terminal for it.
A row dragged out is a file promise: nothing is copied until the Finder (or another app) accepts the drop, and then one rsync brings every dragged row to that folder. A move within the host is mv -f over the same connection, and a paste after Copy is cp -R, each after the host has been asked what stands where the rows would land: one line of sh, run over the same connection with every path an argument of its own, tests each place and says whether something is there, whether it is a folder, and whether it is the row itself or a folder that holds it. The host answers by its own disk, so a name one letter case away counts where the disk ignores case, a folder that can be written but not listed is asked about like any other, and a folder reached by another path is known for the folder it is. Replace removes what stands there first, so a folder lands whole rather than inside its namesake; a row that would land on itself moves nowhere, and one whose namesake holds it is refused. Where two rows about to land together differ only in letter case or in the form of an accent, the host is asked whether its folder would make one item of them: it makes a hidden folder of its own there, .dbclient-names- and a number, tries the two names inside it, and removes it again. A host that cannot be asked moves and copies nothing. A copy beside its original still reads the folder, for the name it takes, and takes one free in every letter case. Copy puts the rows on the pasteboard as file promises, the kind the Finder redeems on paste, so nothing is downloaded until a paste asks for it. The tab browses, copies, moves and deletes: there is no rename or new folder — the terminal is a tab away.
Connecting a host asks for Touch ID like any other connection while Require authentication to connect is on, whether the host signs in with a password or with a key. The SSH password or key passphrase, when there is one, is kept in the Keychain. The host's key is checked against ~/.ssh/known_hosts, the file ssh uses.
A host can go through a Proxy (the editor's Proxy page), which then carries the SSH connection — as it carries a tunnel's.
A host has no SQL, so the toolbar shows no Run, Explain or Watch on its tabs, while Commands and AI Assist stay, and the sidebar row has nothing to unfold. It keeps everything a connection has: folders, a colour, Production, Duplicate, Export and Import.
When an SSH host connects, one more command runs over the link, once: uname -srm, the account's SHELL and /etc/os-release, read for the assistant, which writes commands for that system. The read never holds the terminal up, and a host that does not answer leaves the assistant to read the screen.
This Mac runs the account's login shell (the directory service's, then SHELL, then /bin/zsh) with -l, so .zprofile, PATH and the prompt are yours. A zsh starts with the terminal's shell integration, the terminal library's own files loaded through ZDOTDIR, which hands your own startup files back to you and then reports the shell's folder at every prompt; nothing else is asked of it, so neither the title nor the cursor changes. Another shell names the tab only when it sets the terminal's title itself.
A terminal tab shows the latest of two reports, the way a terminal window names itself: the folder the shell reports (OSC 7) and the title a program sets (OSC 0 or 2). This Mac's shell reports its folder, shown under ~; a host's shell names the tab through the title it prints at its prompt, because the terminal library passes a folder report on only when it names no host or this Mac.
Production mode and connection colours
Two switches on the editor's Options page make a dangerous server hard to mistake for a safe one.
The Options page: red, and the Production switch, for a server that matters.
How to
Turn on Production. Every session on that connection then starts with auto-commit off, so a change waits for your commit. You can still switch auto-commit on for a session; the next connect starts it off again.
Pick a Color: Blue, Teal, Green, Amber, Red, Purple or Graphite. The whole workspace is tinted while that connection is in front.
Technical notes
Production mode relies on transactions. Databricks, ClickHouse, MongoDB and Redis have none, so they apply every change at once, and the editor says so under the switch.
Opening files
A database file is a connection. Drop one on the window or on the Dock icon, double-click it in Finder, or use File ▸ Open… (⌘O). The connection becomes the active one, and the sidebar shows it open down to its tables, opening the folder it is filed in.
A SQLite or DuckDB file becomes a saved connection named after the file, extension included. Opening the same file again selects that connection rather than making a second one.
A .sql script opens as a query tab on the connection you have selected.
A CSV, TSV, JSON, Excel, XML, Markdown or HTML file is data for a table: dropped on a table's row it imports into that table; dropped anywhere else, or opened here, it asks which table. To query a CSV, TSV, Parquet or JSON file as a database instead, use the New Connection picker's Data File tile.
Technical notes
The app reads the first bytes before it trusts the name: a file that starts with SQLite's header is SQLite, and one with DuckDB's is DuckDB, so a DuckDB file called backup.db opens as DuckDB.
Extensions known by name: sqlite, sqlite3, db, db3, s3db, sl3, duckdb and ddb.
A script larger than 16 MB is not opened in the editor.
Oracle and IBM Db2 clients
Oracle and IBM Db2 can only be reached through their makers' client libraries, and the app ships neither. The first Oracle or Db2 connection offers to download the client from Oracle or IBM.
How to
Connect to your Oracle or Db2 database, or click Test Connection or Add in the editor. If the required client is missing, its setup sheet opens automatically. You can also open Oracle Client Setup… or Db2 Client Setup… from the connection editor's Options page.
Click Download on first use, or Update if an older client is installed. Oracle's Instant Client is about 140 MB, IBM's CLI driver about 20 MB. When installation succeeds, your connection, test or Add continues automatically. Cancel stops the attempt without a connection error; a failed download leaves the sheet open for retry and keeps the old client.
Newer vendor clients become available after they are tested and included in a new DBClient release. After installing that release, your next connection guides you through any required client update. The setup sheet also offers Remove… and Show in Finder.
Technical notes
Downloads come from download.oracle.com and public.dhe.ibm.com, under those companies' own terms. The app downloads the version required by this DBClient build; it does not check for vendor releases.
The download, the license text inside it and then every extracted file are checked against SHA-256 digests built into the app. Nothing is kept unless all of them match.
Clients live in ~/Library/Application Support/DBClient/Oracle and …/Db2, one folder per version. brew uninstall --zap dbclient removes them.
This release is pinned to Instant Client 23.26 and the Db2 CLI driver 12.1.4, both for Apple silicon.
Dropped connections
Laptops sleep and VPNs drop. The app notices, reconnects, and tells you exactly what it knows about the statement that was in flight.
A statement that only reads is run again on the fresh connection, and you see its result, when the server confirms that running it a second time is harmless. A plain read of tables is.
A read the server cannot confirm, such as a query that calls a function of your own, is not run again. The message says the connection was lost while it ran, that the server may have run it already, and why it was not run again. Run it yourself if you still need it.
A read of something the old session held, such as a variable you had set or the last inserted id, is not run again either: the new connection is another session and would answer for itself. The message says so.
Anything else is not run again either. The message says the connection was lost while it ran, that the server may or may not have applied it, and asks you to check the data first.
When a tab's connection has been replaced, the result log of the next statement says NEW CONNECTION and names what did not come back with it: variables, what a SET had changed, temporary tables and prepared statements.
The second run is one you did not ask for: you ran the statement once, and the server may have finished it before its answer was lost. So the app goes by the same rule as for the count behind a page. A function can do more than read without changing any data in a way a read-only transaction refuses: write a row through a second connection, send a notification, call another server. A MySQL or MariaDB SET whose value calls a function, such as SET @total = count_rows(), or a SHOW whose WHERE does, such as SHOW COLUMNS FROM orders WHERE count_rows() = 1, is treated the same way, a call inside a /*! … */ comment included.
If a transaction was open, the server rolled it back, and the message says that too. The statement that was running inside it is not run again, even one that only reads, and a script stops there: what ran before it was rolled back, so nothing after it runs on its own.
A warning that only said there was no connection — The connection is closed. Reconnect and try again. — goes away once the connection is back, whether the app reconnected by itself or you did. A statement that failed for that reason alone leaves the tab with it; run it again. Its line stays in the result log.
Technical notes
The connection's own wire — the one behind the sidebar — is pinged every 15 seconds while it is idle, with 10 seconds to answer. The same loop keeps trying to reconnect while the server stays away. A tab's connection is never pinged: its next statement notices a lost connection and reconnects on the spot. File engines have no keepalive.
Every connection the app opens itself to PostgreSQL, MySQL, MariaDB and Redis, and the connection from the app to a SOCKS5 or HTTP proxy, carries a keepalive on the socket as well: after 15 seconds of silence the Mac probes the server every 5 seconds, and three unanswered probes close the connection. Bytes sent and never acknowledged close it after 30 seconds, since the probes do not run while data is in flight. So a connection that died without a word — the Mac slept, the network changed, a proxy cut an idle line — is noticed within about half a minute whatever was running on it, a tab's connection included, and the app reconnects as above. The price is that an outage of half a minute or more ends the connection: a read is run again where the server vouches for it, a write is reported as unconfirmed, an open transaction is lost. MongoDB, Oracle, Db2, SQL Server, ClickHouse and Databricks use their own clients' settings instead. An SSH tunnel has its own keepalive: ssh checks the server every 15 seconds and gives up after three misses.
A PostgreSQL, MySQL, MariaDB, Redis or ClickHouse connection attempt, the first one or a reconnect, has 10 seconds to become a signed-in connection. A port where nothing listens is refused at once. A port that takes the connection and then never answers, as a forwarded port does while the server behind it is away, is given up when the 10 seconds are over. Either way the attempt ends, and the loop above tries again on its next beat.
A ClickHouse Cloud service gets 2 minutes instead of 10 seconds. An idle Cloud service is paused and wakes on the first connection that reaches it, which takes a few tens of seconds. With Cloud SSO (Read-Only) the app asks through ClickHouse's own gateway, which keeps its own limit.
A reconnect counts only once the server has answered a ping, with the same 10 seconds to answer. A Redis connection without a password asks the server nothing as it connects, so a port with no server behind it would otherwise pass for the server.
"Only reads" is judged by the statement's first word — select, show, explain, describe, pragma, values and the like — and excludes statements that call functions with side effects such as nextval or an advisory lock. That reading of the text is a first filter, not the proof: a SELECT can still do more than read through a function of your own, whatever it is named, or through a view that calls one. The proof is the server's: the statement is run again only where the server vouches that a second run leaves nothing behind, by the same questions as for the count behind a page (Results, pages and the row cap, "How each server vouches"), and it is then sent the way such a count is, in a read-only transaction that is rolled back where the server has one. Until this release the rerun went out inside the server's read-only mode on PostgreSQL, MySQL and MariaDB, and that mode was taken for the proof. It is not one: on PostgreSQL a function that writes a row through a second connection (dblink) writes it inside a read-only transaction too, and wrote it a second time on the rerun. A statement the server refuses when it is sent again (SQLSTATE 25006) is reported as not run again, with the server's words. Session-state statements such as USE, and a SHOW or SET without a parenthesis, run again as they are: without one, no function and no subquery can run. A SHOW or SET with one, such as MySQL's SET @id = (SELECT max(id) FROM t), SET @total = bump() or SHOW COLUMNS FROM t WHERE bump() = 1, needs the server's word like a read, since a SET's value and a SHOW's WHERE can call a function of your own. On PostgreSQL only a query can be asked about, so an EXPLAIN is not run again by itself. A text of several statements is not either, unless none of them runs anything. On SQL Server the statements of a batch need no semicolon between them, so a batch is read whole: one that carries a text run by EXEC('…'), or a BACKUP, RESTORE, DBCC, KILL, SHUTDOWN, RAISERROR, RECONFIGURE or CHECKPOINT, behind its SELECT or its SET is not run again at all, and a SET or a USE with a SELECT behind it is asked about like the query it carries. On MariaDB, SET STATEMENT … FOR is read as the statement it wraps: a write wrapped so is not run again, and a read wrapped so needs the server's word. On MySQL and MariaDB a SET GLOBAL or SET PERSIST that takes its value from something it reads, such as SET GLOBAL max_connections = @@global.max_connections + 50, is not run again, since its second run would start from what the first left; one given a plain value lands on the same value however often it is sent, and runs again like any SET. A sequence stepped without a call — NEXT VALUE FOR seq on MariaDB, SQL Server and Db2, Db2's NEXTVAL FOR seq, Oracle's and MariaDB's seq.NEXTVAL — counts as nextval does, in a SET or a SHOW's WHERE as in a SELECT: the statement is not run again at all. On MySQL and MariaDB a statement is read as the server runs it: the body of an executable comment the server runs — /*! … */, a /*!NNNNN … */ gate at or below the server's version, on MariaDB its own /*M! … */ — is code, so SET @v = /*! bump() */ calls a function too, and /*! INSERT … */ is an INSERT and is not run again. A comment the server skips is a comment to the app as well: MySQL skips every /*M! … */, MariaDB every /*!50700 … */ up to /*!99999 … */, and each skips a gate above its own version, which the app reads from the server's banner as it connects — so /*M! SHOW */ UPDATE … is the UPDATE it is on MySQL, and is not run again. The banner also says which server answered: a MariaDB behind a connection saved as MySQL is read as MariaDB, and a MySQL behind one saved as MariaDB as MySQL. A lowercase /*m! … */ is a plain comment on both. Until the version is known, a gated comment is read both ways, and the statement is run again only if both readings are reads; a statement with more than eight such comments is not run again at all. A second statement hidden behind a ; inside such a comment is not run again either. CockroachDB has no way to be asked, so no statement that runs code is run again there. Oracle, Db2 and Databricks statements are never re-run.
An encrypted connection that ends without its closing handshake, as a MySQL connection does when it is killed or its server goes away, is a lost connection like any other: the app reconnects, and a statement that only reads is run again as described above.
A read is run again only when no transaction was open on its connection. A transfer that takes an amount off one row and adds it to another, cut between the two, keeps neither half: the run ends at the statement that was in flight, with a message that the transaction was rolled back.
On MySQL, MariaDB and PostgreSQL, a read that holds a backslash is not run again when the fresh connection reads backslashes in strings the other way, which happens when the lost connection had been switched by hand with SET sql_mode or SET standard_conforming_strings and the fresh one starts at the server's default. The same text can be a different statement under the other reading, so the run stops there with a message that says so, and you run it again yourself. A read without a backslash means the same either way and is run again.
A reconnect puts a tab's connection back on the tab's database; the sidebar's connection reloads the tree and sets auto-commit to what the connection starts with. Nothing else of the old session comes back: its variables, what a SET had changed, its temporary tables and prepared statements went with the connection, and a statement run after the reconnect is answered by the new session. The result log says so once, on the first statement the new connection takes. A statement whose own text reads the old session is not run again by the reconnect: on MySQL and MariaDB one that reads a user variable (one that only sets it, like SET @total = 5, runs again), LAST_INSERT_ID(), ROW_COUNT() or FOUND_ROWS(); on SQL Server SCOPE_IDENTITY(), @@IDENTITY, @@ROWCOUNT, the session's context or a #temporary table; on PostgreSQL lastval() or currval(); and a sequence's PREVIOUS VALUE FOR or .CURRVAL.
Only warnings about the connection itself are taken down by a reconnect. A server's refusal of a statement, a statement that was not run again because the server may have applied it, and a rolled-back transaction stay until you have dealt with them.
A statement you stop is given 5 seconds to end. If the server has not answered by then, the connection it ran on is closed, so nothing else queues behind it: the tab's next statement opens a fresh connection, and the sidebar's own connection reconnects.
Export and import connections
Move your set-up to another Mac, or hand a colleague the connections for a project, as one readable file.
Export Connections: tick what travels. Passwords stay behind unless you ask for them.
How to
Choose File ▸ Export Connections…, or right-click a connection and choose Export… to start with just that one.
Tick the connections and the saved queries to include. Turn on Include saved passwords only if you need them; it asks for Touch ID, an Apple Watch or your login password.
On the other Mac, choose File ▸ Import Connections…, or open the file. Each connection gets a choice: Add, Replace, Keep Both or Skip.
Technical notes
The file is plain JSON, marked "format": "dev.azcode.dbclient.connections", and carries each connection's settings, its folder and its place in the list.
Included passwords are plain text in that file. The sheet says so, and the file is written readable only by you.
On import, a connection that came from this same set-up is offered as Replace. One that only looks the same — the same engine, name and host and port, or the same file — is offered as Keep Both, and the copy is named "name (imported)". Imported passwords go straight into the Keychain.
A file from a newer version of the app is refused with a message to update, rather than half-read.
A file that lists the same connection twice, with the same id, is refused with a message naming the connection. Remove one of the copies and open it again.
The sidebar
One tree for everything: folders, connections, databases, and a folder for each kind of object. It stays quick with hundreds of tables open.
How to
Folders: click New Folder… under the sidebar, then drag connections in, or right-click a connection and choose Move to Folder.
Several at once:⌘-click or ⇧-click connections to gather them, then drag them into a folder together, or right-click for Move to Folder, Remove from Folder and Export…
Browse databases and catalogs. Expand a PostgreSQL or SQL Server connection to see the databases your account can open. On Databricks, expand the connection to see the catalogs available to you. CockroachDB, Neon, Supabase, TimescaleDB and YugabyteDB use the PostgreSQL sidebar. Your starting database or catalog is already open. The others are dimmed until you click the arrow or double-click a name to see its schemas and tables. Right-click an open database for Open Console, Compare Schemas…, Dump Database…, New Schema and Close Database, which closes that one database and leaves the rest of the connection up.
New and dropped databases: right-click the connection and choose New Database (New Catalog on Databricks). The server's CREATE DATABASE opens in a query tab; give it a name, run it, and the new database appears under the connection. To delete one, right-click it and choose Drop Database…, then type its name. It is offered on every database but the one the connection is in.
Filter: type in the Filter box to narrow the tree. The funnel beside it narrows by engine.
Objects: click a kind folder such as Tables for a listing tab of everything in it, with its own filter (⌘F). Right-click a table for Open, Show DDL, Show in Diagram, Copy Name, Rename…, Duplicate…, Edit Table…, Import Data…, Export Data…, Copy to Database…, Truncate… and Drop… The menu items wear the same glyphs the rest of the app uses for those actions.
Duplicate: right-click a table, a view, a function, a procedure, a trigger, an event, a sequence, a type, a synonym or a partition object and choose Duplicate… The sheet suggests name_copy, shows the statements it will run, and for a table lets you choose Structure and data or Structure only. A connection's Duplicate copies the connection itself; a saved query's copies the query.
Refresh: with the sidebar focused, press ⌘R to read the highlighted row's connection again — its tree, or its accounts when a Users & Roles row is highlighted; with a folder highlighted, every connected connection in it; with nothing highlighted, every connected connection. A connection that is not connected is left alone: ⌘R never connects. Right-click a connection, a database or a kind folder for the same Refresh, with the key shown beside it; the palette's Refresh Schema does it for the connection you are working in. A list of tables, views or any other kind of object, in its tab on the right, has the same Refresh: right-click a row or the space under the rows, or press ⌘R while the list is in front. The list's icon turns into a spinner while it is read again. While a connection is read again, its icon turns into a spinner and the rows under it fade; they come back as the fresh tree arrives, after half a second at the least, so even a refresh that answers at once shows. A refresh is one step on the connection: it takes its turn behind a copy or an import the app is running there, and a switch to a tab working in another database waits for it, so the tree it brings is one database's.
Working: while the app runs a statement of its own for you — a drop, a rename, an import, the read behind Show DDL — the connection's icon turns into the same spinner until the server answers. The sheet that asked first, such as Drop…, spins beside its buttons too. A query tab shows its own run on its chip and over its grid, so the sidebar stays still.
With the sidebar hidden (⌥⌘S): the connection's icon in the title bar turns into the spinner in the row's place — for a refresh asked where the sidebar is not needed (Refresh Schema from the palette, ⌘R in a list of objects or in the Users & Roles tab), and while the app runs a statement of its own. With the sidebar showing, the title bar stays still.
Several objects: click a row in a listing tab, then press ⌘A to select every row the filter shows, or ⌘-click and ⇧-click to pick some. Right-click them for Open All, Copy Names, Copy to Database… and Drop 26 Tables… (the item counts what you picked), or press ⌫. Dropping asks you to type how many objects go.
Backups: once a dump has finished, a Backups folder hangs under the connection beside Users & Roles, with a row per backup. Click it for the list, with Restore… beside each; right-click a backup for Restore…, Show in Finder, Remove from List and Move to Trash…
Technical notes
The filter searches what is already loaded. It never connects to a server or fetches a schema to answer.
Each open database of a PostgreSQL, SQL Server or Databricks server works over connections of its own to that database. The sign-in, Touch ID and the tunnel are the connection's and are asked for once. A database you have not opened costs nothing: the list of them is one read when the connection comes up. It is read again with every refresh of the connection or of one of its databases, and after a statement that creates, alters or drops something, so a CREATE DATABASE run in any tab shows under the connection. A database that is dropped while it is open keeps its row, with the server's message under it, until you close it.
Drop Database… closes the database first if it is open here, and its tabs with it, then runs DROP DATABASE from the database the connection is in. The server refuses while anyone else is connected to the database, and the sheet shows its message; the database then stays closed until you open it again. A Databricks catalog must be empty first, its default schema included. To drop the database a connection starts in, connect through another database of the server.
PostgreSQL lists the databases its user may connect to, without the templates. On these three engines a schema's row wears layers and a database's a cylinder; Tablespaces and Backups belong to the whole server and stand beside its databases, while Extensions, Casts, the partition folders and Users & Roles stand inside each database, with that database's grants.
The workspace follows a row you click or move to with the keyboard. A highlight that moves on its own, when the tree is rebuilt by a refresh or by the filter, stays a highlight and switches nothing.
A connection's dot is green once it is connected and its tree has loaded. A connection that was refused shows a red dot, with the reason on a line under it.
A connected connection shows how long it took to connect at the right of its row, when the whole name still fits beside it, and in its tooltip. The time covers the sign-in, tunnels included, not the reading of the tree; a reconnect shows its own.
Table rows, in the tree and in the Tables listing, show about how many rows each table holds, as the server's own statistics have it, marked with a tilde: ~48K. Nothing is counted. PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, Db2, ClickHouse, DuckDB and MongoDB keep such a figure; SQLite and Databricks do not, and views have none. A figure the server has not gathered yet is left blank. ⌘R reads them again with the tree.
Settings ▸ Browsing ▸ Show built-in database objects decides whether system schemas and objects are listed.
When several tables are dropped together, a table that points at another one in the group with a foreign key is dropped first, so the server never refuses a drop over a key that is about to go too. A key names the table spelled the way the key spells it: beside cafe and Cafe on a server that keeps both, a table with a key to cafe is dropped before cafe.
On PostgreSQL, SQLite, DuckDB and SQL Server the drops run in one transaction: if the server refuses one, none of them happen. Other engines drop each object in turn, so a refusal part way leaves the earlier ones gone; the confirmation then says how many went and asks again for the rest.
A duplicated table is copied by the engine's own statement where it has one — CREATE TABLE … (LIKE … INCLUDING ALL) on PostgreSQL, CREATE TABLE … LIKE on MySQL and MariaDB, CREATE TABLE … AS on ClickHouse — which copies columns, defaults, keys and indexes but not foreign keys. On the other engines the copy is written from the table's columns, keys and indexes, the way a copy to another engine is: indexes take the copy's name as a prefix where an engine names them schema-wide, and foreign keys are recreated unnamed so the server names them. The rows follow by INSERT … SELECT on the server, and the copy's own id generators are advanced past them: on PostgreSQL every identity column, GENERATED ALWAYS included, takes the copied ids, and its sequence is moved past them the way it counts, up or down and within its bounds, so the copy hands out the next one; on SQL Server the copy is rebuilt with its key's IDENTITY(1,1), and its rows go in with IDENTITY_INSERT switched on for the copy and off after, the server counting on past them. A duplicated view or routine is its definition with the name in the CREATE head replaced; the sheet shows the statements before anything runs.
A duplicate needs a name the server tells apart from the original's and from its neighbours'. On PostgreSQL, Oracle and Db2 Orders is a name of its own beside orders; on SQLite, SQL Server and DuckDB it is the same name, and the sheet says so.
Names are told apart the way the server tells them apart. Two names that look alike but are stored differently, such as an accented letter kept as one character and the same letter followed by a combining accent, are two objects everywhere in the app: two rows here, two roles under Users & Roles, two columns in a designer, each copied and compared on its own. Letter case counts where the server keeps it: Idx and idx are two indexes on PostgreSQL, Oracle and Db2, and one name on MySQL, MariaDB, SQLite and DuckDB. On SQL Server the database's collation decides both for the names inside it, and the server's collation for the names of its databases.
Query
Write SQL, run it, read what came back, and keep what you want to run again.
The SQL editor
The editor knows where one statement ends and the next begins, so you can keep a whole script in a tab and run the one line you are looking at.
A misspelt table is underlined, completion fixes it and writes the join, then ⌘↩ runs the statement under the cursor.
How to
⌘↩ runs the statement under the cursor, or the selection when there is one. The status bar says ⌘↩ runs selection while text is selected.
⇧⌘↩ runs everything in the tab, statement by statement, and stops at the first failure. With text selected, it runs only the selected statements.
⌘. stops a running query. ⌘R runs the last one again, and the tab spins for half a second at the least, so a query that answers at once still shows it ran.
Completion opens by itself after two typed characters; esc opens it at once. ↑↓ move, ↩ or ⇥ accepts.
After JOIN, the tables a foreign key ties to the ones already in your query come first, each with its ON condition written; accept one and the whole join goes in. After ON, the condition alone. Beside two tables named alike but for letter case, users and Users, only the one the key names is offered.
A dotted underline marks a problem as you type: red for a string or bracket that is never closed or a clause with nothing after it, orange for a table or column the tree does not have. Hover it for the reason. The word you are typing is not judged until you move on. In a MySQL or MariaDB tab an orange mark under --asdf says that the engine needs a space after -- to start a comment: without one, those two engines read two minus signs.
⇧⌘F formats the SQL, or only the selection: it lays the statement out and writes its keywords in capitals. The names in it stay as you typed them, also a column or a table whose name is a keyword, such as key or comment. ⌘/ comments or uncomments the lines you are on. ⌘D deletes a line and ⇧⌘D duplicates it.
⌘F opens the find bar; ⌘G and ⇧⌘G walk the matches; ⌥⌘F finds and replaces.
Technical notes
Statements are split on ; with quotes, comments, nested block comments and PostgreSQL dollar-quoting respected. A chunk that is only a comment is not a statement, with one exception: on MySQL and MariaDB an executable comment standing alone, such as the /*!40101 SET NAMES utf8mb4 */; lines a mysqldump opens with, is a statement, since the server runs its body. MariaDB also runs its own /*M! … */; MySQL skips that one, so there it stays a comment. The server that answered decides, not the type the connection was saved as: a MariaDB behind a connection saved as MySQL runs its own mark, and a MySQL behind one saved as MariaDB skips it. A CREATE FUNCTION, PROCEDURE, TRIGGER or EVENT takes the rest of the script as its body, with a comment above it or not; on SQL Server it ends at the next GO line. A MariaDB CREATE PACKAGE or CREATE PACKAGE BODY does the same, so the semicolons after its routines stay inside it. On Oracle a PL/SQL block ends at a / on a line of its own, and a -- comment at the end of its line, whether the lines end the Unix or the Windows way.
On SQL Server a script is split only where T-SQL allows it. A BEGIN … END block is one statement with every semicolon inside it, BEGIN TRY … END TRY BEGIN CATCH … END CATCH included, and an ELSE stays with its IF, so IF 1 = 1 BEGIN SELECT 1; SELECT 2; END; runs as written. A variable lasts until its batch ends, so the statement that declares it with DECLARE, every statement that uses it and the statements between them run together; the statements after the last one that uses it run one by one again. DECLARE @n int = 5; SELECT @n; runs as one, and a WHILE loop sees its counter. A RETURN keeps everything after it with it, so it stops the rest of the script as it does on the server: when the condition in IF … RETURN; holds, the statements behind it do not run. A script with a GOTO runs whole. ⌘↩ inside such a group runs the whole group. BEGIN TRANSACTION opens no block, and a routine's definition or a SET SHOWPLAN_ALL is always sent by itself.
On SQL Server a line that holds only GO ends a batch, as it does in Management Studio and sqlcmd, so a script written there runs as it is. The line itself is not sent to the server. Nothing is kept together across it: a variable declared before a GO is unknown after it, and a procedure's definition ends at it, so one script can define several. GO 3 runs the batch before it three times, and GO 0 skips it. A large count starts right away: the batch is sent again and again, one run at a time, the summary shows how many statements are left, and Stop ends the run where it is. A count above 1,000,000 is not read as a count, so that line is ordinary text too. Spaces and tabs may stand around the word, and a -- comment after it. With anything else on the line, such as GO;, the line is ordinary text and the server answers it. A GO inside a string, a quoted name or a comment is part of that text. ⌘↩ runs the one statement under the cursor, once, whatever count its batch has. The completion list, the problem marks and Format read each batch by itself.
Strings, quoted names and comments are read the way the connection's engine reads them, so a semicolon inside one never ends a statement, also when the text begins with a combining accent, which a server reads as the string's first character. A backslash escapes a quote on MySQL, MariaDB, ClickHouse and Databricks, as in 'it\'s; fine'; on MySQL and MariaDB that follows the connection's NO_BACKSLASH_ESCAPES. On PostgreSQL a backslash in a plain string is a character like any other unless the connection's standard_conforming_strings is off, and then it escapes there too. Either setting is followed as the connection reports it, also when a statement in the script switches it. E'…' strings escape on PostgreSQL and DuckDB whatever the setting. The tag of a dollar-quoted string is read as the server reads one: PostgreSQL and DuckDB take any character outside ASCII in it, a letter or not, as in $é$ … $é$; ClickHouse takes ASCII only, and lets a digit come first. Backticks quote a name on MySQL, MariaDB, SQLite, ClickHouse and Databricks, and square brackets on SQL Server and SQLite. # starts a comment on MySQL and MariaDB, and on ClickHouse when a space follows it. On MySQL and MariaDB -- starts a comment only when a space, a tab or the end of the line follows it, as the server itself reads it; everywhere else any -- does. A Databricks raw string, written with an r before its quote, takes no escape and ends at its next quote.
The editor reads its text the same way. Colors, the completion list, the problem marks and Format all follow the tab's engine, so a keyword inside a MySQL string that holds an escaped quote is colored as part of the string, and Format leaves it as you typed it. The read-only SQL previews and the result log follow the engine too.
Format changes two things only: white space, and the letter case of the statement's own keywords. A word is a keyword by where it stands, not by how it is spelled. A column, a table, an alias, a WITH query, a variable (@owner), a parameter (:key) or a temporary table (#comment) whose name is also a keyword keeps its spelling, and so does a word after a dot. That matters where another letter case is another name: on ClickHouse, in a SQL Server database with a case-sensitive collation, and for tables and their aliases on MySQL and MariaDB under Linux. A function's name is written in capitals where it is called and keeps its parenthesis next to it, so cast(a AS int) becomes CAST(a AS int). On ClickHouse, where most function names exist in one spelling only, calls keep the spelling you typed, and so do types and engines such as Array(String) and Null. A table whose name is also a function's, such as count, keeps the space you typed before its column list, since MySQL reads count( as the function. Lines that mean something keep their line: a GO line on SQL Server, the / that ends a PL/SQL block on Oracle, and whatever follows a -- or # comment starts on the next line. On SQL Server a column or an alias named go is never left alone on a line, because that line would be read as GO. Format checks its own result before it changes your text: the formatted script must split into the same statements, with the same words in each. In the rare case where it would not, Format leaves the text as you typed it. Edit View opens a view's stored definition through Format, with the same rules.
Completion reads an outline of the statement under the cursor: its WITH clauses, its subqueries, what each reads from and where its clauses begin. It offers the columns of the tables in your statement, tables and views, schemas, the schema's own functions and procedures, SQL keywords and built-in functions. After FROM or JOIN it offers tables only; after alias. that source's columns — a table's, a CTE's or a subquery's, a * expanded to the columns behind it. In WHERE, ON, GROUP BY and ORDER BY it offers columns and never a table; a subquery also sees the tables of the query around it. Keywords and built-in functions are the tab's engine's own: a MySQL tab sees SHOW TABLES, a ClickHouse tab PREWHERE, and neither sees the other's. Names come from the tab's own database; another schema is a schema. away. It never opens inside a string or a comment. A table or an alias whose name is also a SQL keyword, such as transaction or key, is read as the name it is, so its columns are offered after it like any other table's.
The problem marks read the same outline and the tree's catalog, with no grammar behind them, so they only ever say what they can tell: a name is marked when the tree holds the schema it would be in and still lacks it, never for a CTE, an alias, a table the script itself creates, a temporary or system table, a schema the tree has not loaded, or a word that may be a field of a structured column. Marks come 0.7 seconds after you pause.
The formatter moves clauses onto their own lines, puts list items one per line, and writes keywords in capitals. It changes whitespace and keyword case and nothing else: strings, comments, quoted names and type names pass through as written. One ⌘Z undoes it.
Formatting and Explain are SQL features; MongoDB and Redis tabs do not have them.
Results, pages and the row cap
A statement that returns rows shows them in a grid. One that returns none, such as a CREATE, an INSERT or an UPDATE, is a line in the Summary: the statement, how it ended and how long it took. It is the same list whether you ran one statement or a whole script, and results appear as each statement finishes.
A script run with ⇧⌘↩. The Summary lists each statement with how it ended; the one that returned rows has a result of its own beside it.
How to
After a script, a strip above the grid shows Summary and a chip for each statement that returned rows. The summary lists every statement with how it ended — a green check mark when it worked — and how long it took; click one to read its SQL, the server's reply, and its error if it failed. On SQL Server one statement can return several results, such as a block with two SELECTs or a stored procedure that selects twice: each result has a chip and a line of its own, in the order the server sent them.
A run shows a grid for its first 100 results. The statements after that still run: each is a line in the Summary with its row count and a note that its rows are not shown. Run one of them on its own to see its rows. The limit keeps a long run, such as a SELECT above GO 10000, from opening thousands of grids.
A statement run on its own reads the same way. If it returned rows you get its grid and nothing else. If it returned none, failed, or is waiting for a commit, you get the Summary with that one line, and the strip's count beside it, such as 1 completed.
Page through a large result with the pager in the status bar: first, previous, a page number you can type, next, last, and the rows-per-page menu. ↑ and ↓ in the page field turn pages. The pager is there for every SELECT, alone or in a script, and every table opened from the sidebar, even one that fits on a page: it then reads the whole result, such as 1–31 of 31, with the page turns dimmed. In a script, each SELECT has a pager of its own: pick its result in the strip above the grid, and the pager pages that statement. A page you turn to starts at its first row, and it comes from the database the result came from, even if a USE later in the script, or a database you picked since, has moved the tab to another one. A sort from a column header reads that database too. Scrolling past the last row of a page brings the next page in under it, and scrolling up at the first row brings the page before it in above.
The pager shows how many rows and pages a result has. The app counts them in the background once the first page is on screen. Counting runs your query a second time, so it is done only when the server confirms that this is harmless. Where it cannot, as with a query that calls a function of your own, the pager shows Count rows in place of the total: click it to count. Count rows also stands there after a count you stopped or one that failed, and for every result on Databricks.
Double-click a column header to sort by that column: once for ascending, again for descending, a third time to clear the sort. Double-clicking another header sorts by that column alone. A double-click only sorts: it selects nothing, and the column never lights, because a single click's highlight waits until the double-click moment has passed. The sort shows beside the column's name as a bold mark in the connection's color, ↑ or ↓, so the name and the mark read apart, and the column keeps its width, because every header leaves room for the mark.
Every column header ends in an up-and-down chevron. Click it, or right-click the header, for the column's menu. Sort Ascending and Sort Descending sort by that column alone. While another column is sorted, Add to Sort Ascending and Add to Sort Descending add this one after it, and the headers then show the order as ↑1, ↓2; Remove from Sort takes a column back out and leaves the others. Then come Clear All Sorts, Fit Column Width, Fit All Column Widths, Copy Column and Copy Column Name. The chevron stays the same on a sorted column.
Scroll a wide result sideways and the row numbers stay put at the left edge; the columns slide under them. A row number still selects its row there, and its right-click menu is the row menu.
Click a cell, then move around with the arrow keys; the grid scrolls to keep the cell in view. Hold ⌘ with an arrow to jump to the first or last row or column, press Home or End for the row's first or last column, ⌘Home or ⌘End for the first or last row, and Page Up or Page Down to move a page, as in a text editor. Hold ⇧ with ↑ or ↓ to select rows, with ← or → to select cells along the row, one more with each press, or with any of the jumps to select all the way to there, as a text editor selects to the end of a line. Drag across the cells to select the rectangle you sweep, or down the row numbers to select rows.
The grid stops at its edges. A trackpad scroll that reaches the first or the last row, or either side, ends there: the rows do not slide past the edge and spring back.
Run a statement again, from the editor or with ⌘R, and its results start at the first row and column, however far you had scrolled the last ones. A sort from a column header or a page turn starts at the first row and stays on the columns you were reading. A Watch's re-runs keep your place.
⌘L shows the result log under the grid: what ran, when, and what the server said. It follows its last line as a terminal does: on the tail, new lines and a change of the panel's size keep the tail in view; scrolled up, nothing moves. Each tab keeps its own: showing or hiding the log in one tab leaves the other tabs as they are, and running a query never opens or closes it. A new tab starts the way you last chose; a duplicated tab, and a closed tab you reopen, keep the way they were.
Technical notes
Paging happens on the server: the app re-runs that statement for the window of rows you are looking at, and counts the total in the background where the server vouches for the statement, as described below. Rows per page can be 100, 200, 500, 1,000, 2,000 or 5,000; 1,000 to start with. The menu in the pager changes that tab only; the default is in Settings ▸ Browsing.
A statement whose own words change rows is never paged, counted or run a second time, however much it looks like a read. That covers a WITH whose body updates, inserts or deletes and hands the rows to a SELECT, a WITH that leads into a DELETE or an UPDATE, and Db2's SELECT … FROM FINAL TABLE (INSERT …). It runs once, exactly as typed, and its rows come back as one result up to the row cap. The same goes for a read that leaves something behind each time it runs, such as a SELECT that calls nextval() or takes an advisory lock: the count, a page turn and a server-side sort would each step the sequence again, so it runs once and its rows sort on screen.
On SQL Server the statements of a batch need no semicolon between them. A batch with another statement behind its SELECT, such as SELECT * FROM a EXEC dbo.refresh or a SELECT followed by PRINT, SET or DECLARE, is several statements and is not paged: it runs once, as typed, and each result is shown. A second SELECT is the exception: the batch is paged on its last SELECT.
A SELECT can also change data through a function it calls, and nothing in its text says so. Paged, it would change only a page of rows, then change them again at every page turn and once more for the count. So on the engines where a SELECT can do this, the server is asked first: each page is sent in a way that lets the server refuse a change. A statement whose page the server refuses changes data, and is treated as one that does: it runs once, exactly as typed, its rows as one result up to the row cap. With Auto-Commit off it runs inside a transaction and waits for your commit. Watch is not offered, a sort from a column header orders the rows on screen, the rows are not edited in the grid, and the result log says NOT PAGED and why.
How each server is asked. PostgreSQL: in a read-only transaction, inside a transaction you have open too. The mode lets a function write to a temporary table; a page keeps that write, as the statement's own, and the write of a count you asked for is rolled back. MySQL and MariaDB: in the session's read-only mode, which adds two short round trips to a page. Oracle: with COMMIT switched off inside PL/SQL, which is the one way a function called from a query writes there. IBM Db2 has no such mode, and one way for a SELECT to change data: a table function declared MODIFIES SQL DATA, which the statement has to name. The app reads the catalog's list of those functions, and a statement that names one runs once, as typed. On SQL Server, SQLite, DuckDB and ClickHouse a SELECT cannot change data through a function, and no page is asked about.
The count behind a page is the one statement nobody asked for, and it is your statement run a second time. A function can leave something behind without changing any data, which no read-only mode refuses and no rollback undoes: a temporary sequence stepped or a session's advisory lock taken on PostgreSQL, a user variable set or a named lock taken on MySQL and MariaDB, a sequence stepped on Oracle, a global variable set on Db2, a sequence stepped through a macro on DuckDB, a serial counter stepped on ClickHouse. So the count is made by itself only where the server vouches that a second run leaves nothing behind. Where it does not, no count is sent, the result log says why, the page count reads of ?, and Count rows stands behind the row range. The count you ask for is sent on your word, in the same read-only way as a page where the server has one, and rolled back; a statement the server then refuses as a change is not counted at all.
How each server vouches. PostgreSQL is asked twice. First its catalog, before anything of the count is so much as planned: the count goes no further if the statement can reach a function of somebody's own making, which is any function that neither came with the database nor belongs to an installed extension. A statement reaches a function, an operator or a type it names, in a schema on the search path or one it spells; from a table or a view, the view's own query, row policies, the expressions of indexes and CHECK constraints, partitions and the types of its columns; and a cast or an ordering built on such a function wherever it stands. A name is compared the way the server reads it: PostgreSQL keeps the first 63 bytes of a name, so a call spelled longer than that reaches the function with the shorter name, and it takes any character outside ASCII in an unquoted name. An operator counts where the statement spells no sign of it, too. IN, BETWEEN, LIKE and a join's USING are operators to the server (=, >= and <=, ~~), so while an operator by such a name runs a function of somebody's own making, every count in that database waits for you. An operator's negator and its commutator count with it, since the planner may use either in its place. A statement that spells a name with Unicode escapes, as in U&"…", is not counted by itself. The statement's strings are read the way its connection reads a backslash, so a call that stands between two strings where standard_conforming_strings is off is seen for the call it is. What a function is declared as does not count: PostgreSQL runs one declared IMMUTABLE or STABLE while it only plans a statement, and one declared PARALLEL SAFE in a worker, where a write through a second connection goes through. A default and a trigger are not reached, since neither runs on a read; a foreign table is, as a link to another database. Then the server is asked for its plan of the count, and the count is sent only if it would run all of it in a separate worker process, which leaves out what of its own it does not declare safe there: a sequence step, a lock, a setting, a temporary table. A statement, or a view under it, that calls one of the server-administration functions, or one of the functions that run a text as SQL, is not counted by itself either. In a worker the server refuses a sequence step and every write, and whatever else the worker does to its session ends with it; a count runs in one worker, so on a very large table it takes longer than it did. When the server has no worker process free, and inside a transaction you have open, the count waits for you to ask. MySQL, MariaDB, Oracle, Db2, SQL Server and ClickHouse are asked what each name in the statement is: the count is sent only if none is a function, a view or another thing of somebody's own making. That is read widely, so a column named like a function also leaves the count to you, and a view is not looked into. On MariaDB a package counts as well: its functions are called by the package's name. On MySQL and MariaDB a statement that sets a variable with := is not counted by itself; on Oracle neither is one that reads over a database link, a table with a virtual column or a security policy, or a synonym for anything but a table or one of Oracle's own views. On SQL Server a function may change no table, and may still run an extended stored procedure, which reaches outside the database; there a statement is not counted by itself either if it names a synonym, a table with a computed column that calls a function, a table under a security policy, an external table, another database or a linked server. DuckDB counts in a read-only transaction, which refuses a sequence step; a statement that reads a PostgreSQL, MySQL or SQLite database attached through an extension is read on that server, and is not counted by itself. SQLite keeps no functions of your own, and counts every result. CockroachDB has no worker process to ask, so every count there waits for Count rows. Databricks never counts by itself.
MySQL, MariaDB and CockroachDB cannot be asked while a transaction is open. Inside one, a SELECT is paged as its text reads, and on MySQL and MariaDB its count is made when you commit or roll back, if the server vouches for it then. A function that writes for some rows only can pass its first page: no count is made behind it, and a count you ask for, which runs every row, is refused, after which Count rows is offered no more and the result log says why. A page turn, a scroll past the last row, a Watch tick or a header sort never runs such a statement: a later page the server refuses is not read, and says why, and a Watch stops there.
A few reads have no place for a window of rows and run exactly as typed, as one result up to the row cap: a read that locks its rows, with FOR UPDATE, FOR SHARE or the MySQL family's LOCK IN SHARE MODE; one that writes its rows INTO a table or a file; a SQL Server statement with OPTION (…) hints or one that opens with a parenthesis, or a UNION ALL there without an ORDER BY; and a ClickHouse UNION, INTERSECT or EXCEPT, where the server reads a LIMIT as the last SELECT's alone. A SQL Server UNION ALL with an ORDER BY of its own is paged.
SQL Server pages with OFFSET … FETCH, which follows an ORDER BY. A statement keeps its own; one without is read in the server's own order, except a SELECT DISTINCT, UNION, INTERSECT or EXCEPT, which the server lets be ordered by its own columns only and which is paged in the order of its first column. TOP n is read as your own limit, also after a WITH list: the pages end at n rows, and TOP 0 returns the columns and no row. In a UNION each SELECT keeps its own TOP. MariaDB's FETCH FIRST n ROWS ONLY is read as a limit the same way.
One result never holds more than a fixed number of rows: 5,000 on PostgreSQL, MySQL, MariaDB, SQLite, DuckDB, ClickHouse and Redis; 10,000 on SQL Server, Oracle, IBM Db2 and Databricks; 1,000 documents on MongoDB. A result cut there shows a warning and First 5,000 rows. A single SELECT is paged instead, so every row of it can be reached. The app's own catalog reads are not capped.
Databricks stops a page of rows at its response limit, 24 MB, and says so. The pager does not take such a page for the last one: the total stays unknown, Next stays on, and the bar says The server cut this page at 612 rows — Next goes on from there. Next continues from the row the cut stopped at, so no row is skipped, and the pages after a cut page are counted as they are walked: the page after a page cut at 612 rows holds rows 613 on. Fewer rows per page keeps the pages whole.
ClickHouse Cloud with Cloud SSO (Read-Only) asks through ClickHouse's own gateway, which returns at most 384 KB of a result, counted as JSON with every column's name in every row, and refuses a larger one. The app then asks again for fewer rows: 64 first, to see what a row weighs, then as many as fit in 256 KB. The page shows those rows and the bar says The server cut this page at 214 rows — Next goes on from there. Next continues from the cut, and the pages after it ask for that many rows at once, so only the first page takes the extra queries. Every statement there is a SELECT, and each page is one run of it. A result that is not paged, such as a script of several statements, shows its first rows the same way, as First 214 rows. Where even two rows together are over the limit, the gateway's message is shown, Query result is too large to return safely or, past 2 MB, Response body exceeded 2097152 bytes: select fewer columns. Export Data… and a copy to another connection ask for a refused page again in halves. The app's own lists of databases, tables and columns are read a page at a time there, so a service with any number of tables loads. Names are told apart byte for byte there, as ClickHouse tells them apart: two tables, two columns, or a WITH name and a table, that differ only in how an accent is stored are two.
Sorting re-runs the query with a new ORDER BY when the tab holds exactly one statement, so the order covers every page. With several statements in the tab, one statement that changes rows, such as an UPDATE … RETURNING, or one that takes no ORDER BY, such as SHOW, CALL or EXPLAIN, it sorts the rows already loaded and sends nothing. Clearing the sort takes the ORDER BY back out and leaves the rest of the statement as you typed it: a LIMIT that stood behind it stays on its own line, under any comment on the line above.
A statement that ends in a comment on its last line, such as SELECT * FROM orders -- newest first, is paged, counted and sorted like any other: the window of rows, the count's closing parenthesis and the ORDER BY go on a line of their own after the comment, where the server reads them. A # comment counts on MySQL, MariaDB and ClickHouse, where # starts one.
Explain and Watch
Read the plan before you run something expensive, and keep an eye on a number that is changing.
How to
Click Explain, or press ⇧⌘E, for the plan of the statement under the cursor.
Click Watch to run the tab's last statement again on a timer. Click it again, or press ⌘., to stop.
Watch is for a statement that only reads. After a statement that changes data the button is off and says why, and running such a statement in a watched tab ends the watch.
Set the timer in Settings ▸ Browsing ▸ Watch interval: 1, 2, 5, 10 or 30 seconds, 1 minute or 5 minutes; 5 seconds to start with.
Technical notes
Explain sends the engine's own form: EXPLAIN on PostgreSQL, MySQL, MariaDB, DuckDB and ClickHouse; EXPLAIN QUERY PLAN on SQLite; EXPLAIN FORMATTED on Databricks; EXPLAIN PLAN FOR on Oracle and Db2; SET SHOWPLAN_ALL around the statement on SQL Server. A statement that already starts with EXPLAIN runs as written.
MongoDB and Redis have no Explain.
For Watch, a statement only reads when it starts with SELECT, WITH, SHOW, EXPLAIN, DESCRIBE, VALUES, TABLE or PRAGMA, changes no rows, writes nothing INTO a table or a file, and calls no function that leaves something behind, such as nextval. A SHOW is not scanned for verbs, since SHOW CREATE TABLE names one, but a call in its WHERE counts like any other: on MySQL SHOW TABLES WHERE GET_LOCK('x', 1) = 1 is not watched. Every statement of a script has to pass. On SQL Server, where a batch needs no semicolon between its statements, a batch that carries a procedure call, a text run by EXEC('…'), DDL, a grant, or a server command such as BACKUP or DBCC behind its SELECT is not watched. On MongoDB it is the reading commands, such as find and an aggregate without $out or $merge; on Redis the reading commands, such as GET and SCAN.
Auto-commit and transactions
With auto-commit on, each statement commits as it runs. With it off, changes wait in a transaction until you say so, and the app keeps reminding you that they are waiting.
Every tab that runs SQL has a connection of its own, so a transaction belongs to the tab that opened it. Another tab, the sidebar, Show DDL and the designers all keep working while it waits — and while a tab is still loading a big table.
How to
Click Auto-Commit in the toolbar, or press ⌥⌘T, to switch it off.
Run your changes. A dialog asks Commit changes to “connection”? with Commit, Roll Back and Not Yet.
After Not Yet, the status bar shows uncommitted transaction with Roll Back and Commit until you choose.
Closing the tab before you have chosen asks first: Commit & Close, Roll Back & Close, or Cancel to keep the tab open.
Technical notes
Available where the engine has transactions: PostgreSQL, MySQL, MariaDB, SQLite, SQL Server, Oracle, IBM Db2 and DuckDB. Not on Databricks, ClickHouse, MongoDB or Redis.
A connection marked Production starts every session with auto-commit off.
While a tab's transaction is open, a grid commit in that same tab is refused with a message asking you to commit or roll back first. Other tabs, imports and the designers run on their own connections and are not held up.
Closing a tab whose transaction is open never drops the changes silently. Commit & Close closes the tab only after the server has taken the commit: if the commit fails, or the connection is lost under it, the tab stays open with the reason in red. Roll Back & Close stops whatever the tab is still running, rolls back and closes. While a statement is still running in the tab, Commit & Close asks you to wait for it. If a script had stopped to ask for its commit, closing the tab ends the script there. SQL you typed in the tab is not saved anywhere and goes with it, as the question says. Close Others and Close All leave such a tab open.
A tab's connection is dialed the first time the tab runs something and handed back when the tab closes. The app keeps two of them idle for five minutes, so a browse straight after a browse doesn't dial again.
On MySQL, MariaDB and PostgreSQL, a tab's script is told apart into statements the way its own connection reads strings: by the NO_BACKSLASH_ESCAPES mode a MySQL or MariaDB connection reports, and by the standard_conforming_strings setting a PostgreSQL connection reports, as it opens and each time it changes. A SET sql_mode or a SET standard_conforming_strings in one tab changes that tab's connection alone, and a new tab starts on the server's default, so a statement that changes data is always seen for what it is before the transaction is opened. A switch is taken from the connection itself, so one made by a statement whose script then failed, or one PostgreSQL undid with a failed transaction, is followed as well. ⌘↩ runs the statement under the cursor as that connection reads it, nothing beside it, and Explain picks its statement the same way.
Whether a statement changes data is read the way its own server reads SQL: where a string, a quoted name or a comment ends. $tag$ … $tag$ is a string on PostgreSQL, DuckDB and ClickHouse, while SQLite reads $x$, @a(…) and :a(…) as parameters; a comment inside a comment nests on PostgreSQL, SQL Server and Db2 and ends at the first */ on MySQL, MariaDB, SQLite and Oracle; a carriage return ends a -- note on PostgreSQL, DuckDB and SQL Server, and a line feed alone elsewhere; q'[…]' quotes on Oracle alone. So no change passes for a read, however its text is written.
On SQL Server the statements of a batch need no semicolon between them, so a batch is read whole: SET NOCOUNT ON DELETE FROM items is a SET and a DELETE, and the DELETE waits for your commit. T-SQL's own writes count too: DENY, WRITETEXT, UPDATETEXT, RECEIVE and Service Broker's conversations, and so does a text run by EXEC('…') or EXECUTE(@sql) behind another statement. A batch that commits or rolls back partway and changes data after that point is not run, since nothing could hold the later changes; run them separately, or with auto-commit on. After a batch that begins, commits or rolls back a transaction itself, the app asks the server whether one is still open, and Commit ends every level, the batch's own BEGIN TRAN included.
On MariaDB, SET STATEMENT … FOR is read as the statement it wraps: SET STATEMENT max_statement_time=5 FOR DELETE FROM items is a DELETE, and waits for your commit.
A DuckDB file is opened once, and each tab's connection is a connection to that one instance, the way DuckDB expects. A commit in one tab is seen everywhere at once, and a transaction still belongs to the tab that opened it.
If the connection drops with a transaction open, the server rolls it back and the app tells you. See Dropped connections.
The command palette
⌘K opens one search box over your tables, their definitions, the app's actions and your other connections. It also lives in the toolbar as Commands and in the View menu as Command Palette…
⌘K, then a few letters of a table's name.
How to
Press ⌘K and start typing a table's name.
Pick Open schema.table to browse it, or DDL: table for its CREATE statement. Typing ddl, diagram or history narrows to those rows.
↑↓ move, ↩ runs the row, esc closes.
Technical notes
Rows: every table and view, twice (open, and DDL); a Diagram row per schema; the actions New Query Tab, New Table…, Open Console, Run Query, Run All Statements, Explain Statement, Show Result Log, Show Result as Chart, Refresh Schema and Add Connection…; the connection's remembered statements, newest first (see Query history); on PostgreSQL, SQL Server and Databricks every other database of the connection's server, to open it; and every other saved connection, to switch to it.
Typing narrows by the text you typed appearing anywhere in a row's title or subtitle, in any case. Rows whose title starts with it come first.
Console tabs
A console tab is a real terminal running the engine's own command-line client, already signed in with the connection's host, port, user and password, and through its SSH tunnel or proxy if it has one. The prompt, history and pager are the client's own. The cursor wears the connection's color theme; with no theme chosen it takes your Mac's accent color, and with the default accent it is the gray Terminal's cursor has. Text you select is shown in your Mac's highlight color, the one chosen in System Settings ▸ Appearance, as selected text is in the editor.
A console tab running sqlite3 on a SQLite file.
How to
Click the terminal button in the tab strip, or right-click a connection and choose Open Console. The console opens in a new tab, and the tab you were on stays as it was. On a database's overview, the Console card opens the client with that database as the current one.
If the client is not installed, a sheet names it and shows the Homebrew line that installs it, with a copy button. Run the line in Terminal, then click Check Again.
When the client exits, the tab offers Restart.
Open AI Assist to ask about console output or get help writing SQL. The assistant can read recent output and check your database structure. Click Insert into the terminal, then press Return to run the SQL.
Technical notes
Clients: psql; mysql or mariadb; sqlite3; sqlcmd; clickhouse-client; mongosh; redis-cli or valkey-cli; SQL*Plus or SQLcl; db2cli; dbsqlcli. The install line for each is under Engines.
The password is never put on the command line, where other processes could read it. It goes through the client's own environment variable — PGPASSWORD, MYSQL_PWD, SQLCMDPASSWORD, REDISCLI_AUTH — or is typed at the client's own password prompt with echo off.
The app looks for a client on your PATH, in Homebrew and in the usual install folders, and looks again whenever it comes to the front.
A console opens where its tab works: the tab's database on MySQL, MariaDB, ClickHouse, SQL Server, MongoDB and Redis, and on PostgreSQL the tab's database, with the tab's schema handed to psql as its search_path under its quoted name, so Sales is never read as sales and a name with a space is carried whole.
No console for DuckDB and data files, where one process may hold the file, nor for a ClickHouse Cloud browser sign-in. clickhouse-client speaks ClickHouse's native protocol, which a tunnel set up for the app's HTTP port does not carry, so a tunnelled ClickHouse connection has no console either.
The terminal is Ghostty's, built into the app.
A console stays on its connection. While it is in front, the connection and the database in the toolbar read as labels, not menus.
A console gets a tab of its own. It does not open inside an empty query tab, and it does not take the place of a tab whose title is in italics. The Console card on an overview is the one exception: while the overview's title is in italics, the console opens in the overview's tab, like everything else its cards open.
A console opened from the tab strip starts in the database of the tab in front. One opened from a database's overview starts in that database: the database itself on MySQL, MariaDB, ClickHouse and MongoDB, and the schema, as the search path, on PostgreSQL. Clicking the card again brings that console forward; another database's card opens a console of its own. Oracle, Db2, Databricks and SQLite clients cannot be told a database to start in, so there the card opens the connection's console.
MongoDB and Redis commands
MongoDB and Redis do not speak SQL, so their query tabs take the engine's own commands and show the reply as a grid.
MongoDB: a tab holds one or more JSON command documents — anything db.runCommand accepts. For example { "find": "users", "filter": {}, "limit": 10 } or { "aggregate": "orders", "pipeline": [], "cursor": {} }. Documents come back one row each, one column per key; two keys that look alike but are stored differently, such as an accented letter as one character and as a letter with a combining accent, are two columns. Keys go to the server in the order you type them, so "sort": { "last": 1, "first": 1 } sorts by last name and then by first name.
Redis: one command per line, written as in redis-cli, with quotes for values that contain spaces. A line starting with # is a comment. SELECT 2 moves the tab to database 2.
Technical notes
A plain find on one collection, with _id in the result and no projection, can be edited in the grid. So can the key browser a Redis SCAN returns: key, type, TTL and value. A key name or value with a line break in it is written whole, and a change the browser cannot write, such as a TTL that is not a number of seconds, is refused on the commit sheet and stays pending until you mend it.
A grid edit names its MongoDB document by the document's own _id, kept with its kind: text, an ObjectId, a number, a date, a UUID or other binary value, or an embedded document. An ObjectId and a text _id of the same 24 characters look alike in the grid and are still two different documents. A document whose _id is a Decimal128 or a regular expression cannot be edited in the grid.
A value edited in the grid is saved as the type its field holds. Text stays text, also 01235 or true. A number stays a number of the same kind: a 32-bit integer, a 64-bit integer or a double. True or false, a date and an ObjectId stay what they are. A field that is empty or missing takes the type the column's other documents hold, and so does a new document. An embedded document, an array and binary data are shown and cannot be edited in the grid; change them with an update command.
A MongoDB command that writes fails when the server turns a write down, such as a duplicate under a unique index, even though the server's reply says the command itself was received. You get the server's own message. Numbers in a typed command keep every digit, and the wrappers $oid, $date, $numberLong, $numberInt, $numberDouble, $binary, $uuid and $timestamp are read as the values they stand for.
Several Redis lines run in order and the last reply fills the grid.
Tabs and the overview
One strip holds the tabs of every connection, in the order you opened them: a new tab is always the last one, whatever its connection. Clicking a tab of another connection takes you to that connection, and closing the last tab of the connection in front takes you to the tab beside it, whatever connection that one belongs to.
Show all tabs: the arrow keys walk the cards, Return opens one.
How to
⌘T opens a query tab, ⌘W closes the one in front, ⇧⌘T brings back the last one you closed.
A tab that holds an uncommitted transaction or pending changes asks before it closes: Commit & Close, Roll Back & Close (Discard & Close for pending changes), or Cancel to keep it open.
⌃⇥ and ⌃⇧⇥ step through tabs; ⌘1 to ⌘8 jump to a tab by position and ⌘9 to the last.
The two arrows at the left of the strip, Back and Forward, step through what you looked at, in order: another tab, or the page the same tab showed before. Back also brings back a tab you just closed.
Click the grid button, Show all tabs, for a card per open tab with its first lines. Arrow keys move, ↩ opens, esc closes.
Right-click a tab for Save Query…, Duplicate, Close, Close Others and Close All.
Drag a tab to arrange the strip; a line between two tabs shows where it will land. A drag never changes a tab's connection.
Technical notes
A tab opened by clicking something in the sidebar is provisional, its title in italics: the next thing you open takes its place, so browsing does not pile up tabs. Clicking in it or on its tab, typing, running or editing a row makes it stay.
What you open from an overview takes the overview's place in the same tab while the overview's title is still in italics: the connection's page, a database's overview and its list of tables are one tab, not three. Click the overview, or its tab, and the title turns upright: the overview is kept, and what you open from it gets a tab of its own. Clicking a card does not keep the overview. A list or a diagram keeps its tab, and what you open from it gets a tab of its own, its title in italics like one opened from the sidebar. Something already open in another tab is brought forward instead.
A page that gave its place to another is not lost: Back shows it again in the same tab, and Forward returns. A list comes back with its filter and the rows you had picked, a diagram with its zoom, its place and the tables you moved; a table is read again. An overview that comes back leaves its tab as it was: still in italics if you had not kept it.
A tab is never replaced while it holds something you would lose: row edits not yet committed, an open transaction, SQL you changed, a designer with changes not applied, a statement you ran that is still running, a watch, or a console. The other page opens beside it instead.
A console, a dump and a restore open in a new tab at the end of the strip and leave the other tabs as they are. An empty query tab stays, and so does a tab whose title is in italics, which goes on waiting for the next thing you open from the sidebar. The one exception is the Console card on an overview whose title is still in italics: it opens in the overview's tab, like every card.
The tab you click is highlighted at once; its editor and results follow a moment later, so a connection with many large results open never holds the click back. Nothing fades or slides on the way: the tab lights in one step and the content changes in the next.
The workspaces of the last ten connections you used stay ready behind the one on screen, so switching back to a connection is as quick as switching tabs. The eleventh takes the place of the one you used longest ago. The toolbar, the title and the keyboard shortcuts belong to the window and always act on the connection and tab in front.
Picking another connection in the toolbar's connection menu carries the query tab on screen to that connection, and the tab keeps its place on the strip. A console, a designer, a listing, the overview or a diagram stays on its connection, and the connection you picked comes forward with its own tabs, or its overview when it has none. An SSH host takes no query tab: picking one brings the host forward with its own terminal, and the tab stays on its connection. A click in the sidebar, the command palette and Compare Schemas bring a connection forward and move no tab. A query tab that holds pending changes or an uncommitted transaction is not carried either: it stays on its connection with the reason in red, until you have committed or rolled back.
A tab wears its connection's color, if the connection has one; a tab of a connection without a theme is plain.
SQL counts as changed when any character of it differs from what was opened or saved. That includes a difference you cannot see: é stored as one character, or as an e followed by a separate accent, is the same letter on screen and two different values to a server, so retyping one as the other is a change, in the editor and in a cell.
Closing tabs that hold unsaved work asks once, for all of them. A tab that holds an uncommitted transaction or pending changes is left open by Close Others and Close All: close it by itself to be asked what to do with them.
Saved queries
A saved query lives in the sidebar beside the database it was written for.
How to
Press ⌘S in a query tab. The Save Query sheet suggests a name from the first line.
Find it under that database's Queries folder. Click it to open it in a tab.
⌘S in a tab that came from a saved query saves back to it, without asking.
Technical notes
A query is filed under its connection and database, and each database's folder shows only its own.
When a grid has pending changes, ⌘S reviews and commits those instead.
Saved queries are kept in ~/Library/Application Support/DBClient/saved-queries.json, and can travel in an exported connections file.
Query history
Every statement you run is remembered, newest first, and one ⌘K away.
Type history in ⌘K: what you ran, newest first. Return puts one back in a tab.
How to
Press ⌘K and type a few letters of the statement, or history to see only remembered statements. Each row shows the statement's first line and when it last ran.
Pick one: it opens in the blank tab, or in a new tab when the one you are on holds text.
Settings ▸ Browsing says how many statements are kept, and Clear History forgets them all. There is no switch to stop the remembering.
Technical notes
A statement is remembered when you run it yourself — ⌘↩, ⇧⌘↩, the Run button. The same text run again on the same connection is the same entry moved to the top, with its runs counted; the same means letter for letter, so a statement retyped with an accent stored another way is another entry. A re-run, a watch turn, a browse page or a resumed script records nothing new.
Each entry keeps its connection and database, when it first and last ran, how long the last run took and how it ended: the rows returned, plain completion, or the server's error.
The list holds 1,000 statements across every connection; the oldest go first. The palette shows the current connection's latest 100 and narrows through all of them as you type.
Kept in ~/Library/Application Support/DBClient/query-history.json; it never travels in an exported connections file. A statement is kept as typed, literals included; after running one that carries a password, Clear History forgets it along with the rest.
Edit
Change rows in the grid, read the SQL that will run, and move rows in and out as files.
Editing rows in the grid
A result is editable when the app can tell, for every cell, which row of which table it came from. Nothing you type reaches the server until you commit.
One changed cell, one row marked for deletion and one new row: 3 pending, in the status bar.
How to
Double-click a cell, press ↩ on a selected cell, or right-click it and choose Edit Cell. ↩ keeps the change, esc drops it, and either way the cell stays selected, so the arrow keys move on from it and ↩ edits the next one. Leaving a cell as you found it changes nothing: a NULL cell you open and click away from stays NULL.
Use the buttons beside the editor: a picker for dates, enums and foreign keys, Restore original value, and Set NULL. In a number or a boolean, ↑ and ↓ step the value.
Click + in the status bar to add a row. Right-click a row number for Add Row and Delete Row.
Changed cells are washed orange, new rows green, rows marked for deletion red and struck through. The status bar counts them: 3 pending.
Technical notes
What is editable: one SELECT whose columns are plain table columns — no grouping, DISTINCT or UNION — from tables, not views, with every table's whole primary key in the result. Joins qualify: each cell is written to the table that owns it, with that table's key. A table without a primary key is read-only, and so is a Db2 table whose key is not enforced. A row whose primary key is NULL, which SQLite allows, takes no edit and no delete, since no statement could single it out; the same goes for a row whose key is a binary value, which SQLite can hold beside rows with plain keys. Comments in the statement, ahead of the SELECT or anywhere inside it, make no difference. Table aliases are read the engine's way: on PostgreSQL and Oracle a quoted alias keeps its case and an unquoted one is folded, so a self-join under a and "A" writes each cell to the row its own alias names. A result column is matched to the table's column by its exact name first, so a column beside its case twin, id beside ID, is written as its own type. In a join, a column named without its table belongs to the table that has it under that exact name, where the server keeps Label and label as two columns. On SQL Server a result is edited by the tables of the database it ran in, read under that database's collation, even when it arrived while a tab on another database was in front. A column, a table or an alias may wear any name your server accepts without quotes, also one that is a SQL keyword elsewhere: SELECT id, owner FROM tasks is editable like SELECT *, and so are SELECT * FROM transaction and FROM tasks AS key. The one exception is a word the server itself reads as a value when it stands alone. Beside a column named user, a bare user is the signed-in user on PostgreSQL, SQL Server, Oracle and Db2, and the column on MySQL, MariaDB, SQLite, DuckDB and ClickHouse; current_date, null and Oracle's sysdate and rownum are values the same way. Such a result is read-only where the server answered with the value. Quote the name, or write its table in front as in t.user, to get the column. When one SQL Server statement returns several results, none of them is editable.
A read-only result shows a lock in the status bar; its tooltip says why. On an editable result, a cell that takes no edit, such as a generated column, a binary value, a row whose key is NULL or binary, or the empty side of an outer join, says why in the status bar while it is selected.
Editors by column: text, whole and decimal numbers, booleans, dates, dates with times, enums, and foreign keys. A foreign key's picker shows the first 500 rows of the table the column points at, as a small table: each key first, then the rest of its row under that table's own column names, so an id sits beside the name or title it stands for. The table's name stands beside the picker's filter box. A long key such as a UUID shows whole, and the picker opens wider for it. The row the cell points at is marked and in view as the picker opens. The filter searches every column shown, a click on a row writes its key, and any other value can still be typed. A key belongs to the column it is on: where the server keeps Owner and owner as two columns, as PostgreSQL does, a key on Owner gives owner no picker.
A narrow status bar: the bar is as wide as the results, so beside an open inspector it may not fit all it holds. Its words step aside first — the connection's status word, the row range, the rows-per-page menu, then the pending count — and Discard, Commit… and the page buttons always stay.
PostgreSQL values: every cell is the text psql prints for it — an interval, an array, a range, a network address, json, money, an extension type — and an edit, a Copy as INSERT, an export or a transfer writes that text back, so the stored value comes back the same for every type. A timestamp keeps its microseconds and its zone offset; a numeric keeps every digit.
Long text and JSON — a JSON column, or a value with a line break or 80 characters — opens in its own editor sheet with Format and Condense, so the grid's rows stay one line tall.
Selection: click a row number for a row, a header for a column, a cell for a cell; ⌘ toggles and ⇧ extends. Drag across the cells to select the rectangle you sweep, or down the row numbers to select those rows; the grid scrolls when you drag past its edge. ⇧-click a cell to select the rectangle from the selected cell to it. Click the blank corner above the row numbers, or press ⌘A, to select every row. The arrow keys move the selected cell one step, and the grid scrolls to keep it in view. ⇧↑ and ⇧↓ select rows from that cell's row outward, ⇧← and ⇧→ the cells along its row: each press takes one more, a press back toward the start gives one back, and past the start the selection grows the other way, as in a text editor. ⌘↑ and ⌘↓ jump to the first and last row, ⌘← and ⌘→ to the first and last column; Home and End reach the row's first and last column, ⌘Home and ⌘End the first and last row, and Page Up and Page Down move a page of rows. With ⇧, each of those selects from the cell to there: ⇧⌘→ and ⇧End take the cells to the end of the row, ⇧⌘← and ⇧Home back to its start, ⇧⌘↓ the rows to the last, ⇧Page Down a page of rows. The keyboard goes with the selection's far end, as a text editor's cursor does, so a plain arrow afterwards returns to a single cell, the one at that end, moved one step. ↩ edits the selected cell, and when the edit ends the cell is selected again. esc clears whatever is selected, like a click on the blank space beside the rows. A selected cell wears the connection's colour, and the rest of its row a lighter wash of it, so the row is easy to follow across a wide result. Selections fill their cells to the corners; nothing in the grid is rounded. Right-click for Copy Cell (Copy Cells on a block of cells), Copy Row, Copy Column, Copy as Markdown, Copy as JSON and Copy as INSERT. Rows are copied tab-separated, ready to paste into a spreadsheet. Copy as INSERT reads a row's binary values back from the table by its key, since the grid holds only their size, so an image or a file goes into the statement as the engine's own binary literal rather than NULL; a row it cannot read back, or a value no statement can carry, is refused and the status bar says why. On PostgreSQL the statement carries OVERRIDING SYSTEM VALUE when a column is GENERATED ALWAYS AS IDENTITY, as the export's does. Copy as JSON names two columns of one name apart, the second as value_2, so each key stands once. Press ⌘C to copy whatever is highlighted: the cell's value, a block of cells as tab-separated lines, the selected rows, or the selected columns. The copied cells flash for a moment, so you can see what went to the clipboard.
Pending changes become SQL you can read before it runs, and they run together or not at all.
Review Changes: the exact statements, between BEGIN and COMMIT.
How to
Click Commit… in the status bar, or press ⌘S. Discard throws the pending changes away instead.
The Review Changes sheet shows every UPDATE, DELETE and INSERT, between BEGIN and COMMIT.
Click Commit. A spinner shows while the save runs. The sheet closes as soon as the server has taken the changes, and the grid reloads behind it. Only the result you edited is read again: the other statements of a script are not run a second time.
Closing the tab while changes are still pending asks first: Commit & Close saves them and closes the tab, Discard & Close throws them away, and Cancel keeps the tab open.
Technical notes
All statements run in a single transaction. If one fails, the app rolls back, shows the server's error, keeps your pending changes and leaves the sheet open. Every UPDATE and DELETE must reach exactly one row: a row that another connection deleted or re-keyed since the grid was loaded stops the save the same way, with nothing saved. On MySQL and MariaDB the count is the rows the change matched, not the rows whose values changed, so an edit to a value a column already holds still saves. SQL Server reports no counts while SET NOCOUNT ON is in effect on the tab's connection, so there the save turns the counts on for its own statements and puts the setting back as it was.
The wrapper is the engine's own: BEGIN…COMMIT, BEGIN TRANSACTION on SQL Server, an atomic block on Db2 and Databricks. ClickHouse has no transactions, so there the sheet says the changes apply statement by statement.
MongoDB changes go out as commands with no transaction around them, one document at a time, and the sheet says so. If the server turns a write down, or a document is no longer there under its _id, the save stops with the reason, your pending changes stay and the sheet stays open. What was written before that point stays written. A value its field's type cannot hold, such as a word typed into a number, is named in the sheet as it opens; Commit stays off and nothing is sent until you change it.
Every UPDATE and DELETE names its row by primary key.
Names and values are quoted the engine's way wherever the app writes a statement for you, every quote and backslash inside them escaped, also one with a combining accent directly behind it, which a server still reads as the quote. A text that holds a backslash is written so that it means the same whichever way the connection reads one: as a hex literal on MySQL and MariaDB, and as an E'…' string on PostgreSQL.
While changes are pending, running another query in that tab, refreshing and importing are held back, so the rows under your edits do not move.
Commit & Close saves the same statements the sheet would show, without opening it, for every result of the tab that holds changes. If a save is refused, the tab stays open with the reason in red and the changes still pending.
Changes are saved in the database their rows came from, and a foreign key's picker lists that database's rows. That matters when a script selects, runs USE and selects again: the tab ends up in the second database, and an edit to the first result still goes to the first.
The inspector
The inspector is a panel on the right for the row, or the object, you have selected. Open it with the Inspector button or ⌥⌘I.
The inspector on Fields: the selected row as a form.
Fields shows the selected row as a form, one field per column. On an editable result you can change values here, with the same pickers, restore and Set NULL as in the grid; the changes join the grid's pending ones.
JSON shows the selected rows as JSON, with Copy JSON.
DDL shows the CREATE statement of the object selected in the sidebar, with Copy SQL.
Technical notes
On a read-only result, Fields is a document you can select and copy from, not a form.
The inspector remembers which of the three you last used.
Drag the panel's left edge to size it. It can be as wide as the window allows; the editor and results keep a minimum width. With the inspector and the assistant both open, dragging one never resizes the other.
Export a result
Take the rows in front of you away as CSV, TSV, JSON, JSON Lines, SQL inserts, an Excel workbook, a Markdown table, an HTML page or XML — or a whole table, from its menu.
Export Result, with a preview of what will be written.
How to
Click the export button in the result bar, or select rows and right-click for Export Rows…. For a whole table, right-click the table in the sidebar or in the Tables listing and choose Export Data….
In the sheet, pick the Format: CSV, TSV, JSON, JSON Lines, SQL Inserts, Excel, Markdown, HTML or XML. For CSV, pick the Delimiter: comma, semicolon or pipe. For a result, pick All rows or the Selected ones. The sheet previews what will be written, HTML and XML coloured as markup; a workbook is binary, so Excel shows a description instead. For HTML, Preview in Browser opens the page in your browser.
Click Copy for the clipboard or Save… for a file. With Excel picked, Copy puts the rows on the clipboard tab-separated, ready to paste into a spreadsheet.
A table export reads every row from the server in pages of 5,000, or of 1,000 documents on MongoDB, while it writes, and says how many rows it has written so far. On MongoDB the collection's field names are read first, in pages of 1,000, compared as bytes so that names differing only in case, or in the way an accent is stored, stay apart, and every document's values are laid out on them by name. A view keeps the collation it was made with, so its names are grouped through a binary conversion on MongoDB 8.0 and later; on an older server they come as the view's collation compares them. A document with a field outside the listed names stops the export with a message naming the document and the field, so no value is written under another's name; the same happens when the names could not be listed and the first page's columns stand for them. Stop ends it and removes the partial file.
Technical notes
CSV and TSV have a header row, RFC 4180 quoting, and empty fields for NULL. A value holding the delimiter, a quotation mark or a line break of any kind, a Windows one included, is quoted. In a result of one column an empty value is written as "", so its line is still a row when the file is read back.
JSON is an array of objects, one per row, column order kept; a json column's value rides along as JSON rather than as a string. JSON Lines is one such object per line. Two columns of one name are written apart, the second as value_2, so each key stands once and the file reads back with both values; XML names its fields the same way. CSV, TSV, Markdown and HTML keep the repeated header, since their columns go by position.
SQL Inserts name the table the result came from, when it came from one, and result otherwise, with the names quoted the engine's way either way (backticks on MySQL and MariaDB), and spell the literals the engine's way. A generated column of that table is left out of the inserts, since the table computes it and refuses a value for it; the other formats carry it, since there it is data. A column of the result is the table's column of exactly that spelling, or else the one column of that name in another case, since MySQL and SQL Server return a column under the spelling the statement typed; two names that look alike but are stored differently, such as an accented letter as one character and as a letter with a combining accent, are two columns, and each keeps its own values. A table whose every column is generated exports each row as a row of defaults, INSERT INTO … DEFAULT VALUES or the engine's own form of it. The grid's Copy as INSERT does both the same way. Generated columns are read from the catalog on every engine, SQL Server computed columns and ClickHouse MATERIALIZED and ALIAS columns included. On PostgreSQL the inserts carry OVERRIDING SYSTEM VALUE when a column is GENERATED ALWAYS AS IDENTITY, so the file runs back in with the ids it holds; Copy as INSERT carries it too. When the exported columns include an id generator, an identity column or a serial, the file ends with the statements that move each generator past the exported ids, so the restored table's next row without an id takes a fresh one: PostgreSQL's setval, Oracle's START WITH LIMIT VALUE, Db2's restart and Databricks' SYNC IDENTITY. On Oracle and Db2 an identity that always generates its values is turned BY DEFAULT at the file's head and back at its end, the way a table copy surrounds its rows, since those engines have no override clause. On SQL Server, which has none either, the file opens with SET IDENTITY_INSERT … ON for the table and closes with OFF; the server counts on past the ids itself.
An infinite number, or NaN, is written the way its engine reads it back: 9.0e+999 on SQLite, which stores a NaN as NULL, 'Infinity'::DOUBLE on DuckDB, 'Infinity'::float8 on PostgreSQL, inf and nan on ClickHouse, BINARY_DOUBLE_INFINITY on Oracle, CAST('Infinity' AS DOUBLE) on Databricks and DECFLOAT('Infinity') on Db2. MySQL, MariaDB and SQL Server hold no such numbers, so there the word goes in quoted, and the server refuses it.
A table's binary column, such as PostgreSQL bytea, MySQL BLOB, SQL Server varbinary or Db2 BLOB, VARBINARY and FOR BIT DATA, is read as hex. SQL Inserts carry the value as the engine's own hex literal, decode('…', 'hex'), X'…' or 0x…, and the other formats carry the hex text. A result holds only the size of a binary value, so a result export writes NULL in SQL Inserts and the size elsewhere, and the sheet says so. On Oracle the app's helper reads RAW and BLOB values itself, since no SQL can spell a BLOB as hex; a value past 2,000 bytes is written as a PL/SQL block that builds it from 2,000-byte pieces, ended by a line holding a slash, which the app and SQL*Plus both take as the end of a block. A value over 16 MB stops the export with a message.
SQLite types values rather than columns, so the app reads each value as SQLite holds it, whatever its column is declared as: a blob stored in a column declared TEXT, or with no type at all, exports whole, as X'…' in SQL Inserts and as hex text elsewhere, and text or a number in a column declared BLOB stays text or a number, in the primary key too, where the pages follow each key by its own type. A row whose binary values pass 64 MB of hex stops the export with a message.
A table whose primary key is binary pages by the key's own bytes: the next page starts after the last key read, compared as the engine's binary literal, so every page is read once.
Excel holds 1,048,575 rows on a sheet. A table with more continues on a second sheet, named like the first with a number, and so on. The count the sheet reports is of every row written, and importing such a workbook reads the sheets back as one table.
Save… writes the rows to a file beside the destination, named like it with a tag of its own and .part added, such as orders.csv.3f9a2c.part, so two exports to one file never share it, and the destination changes only once the last row is in. A stopped or failed export leaves a file already at the path as it was, and no part-file behind.
Excel writes an .xlsx workbook with one sheet named for the table: the column names in a bold frozen header row, numbers and booleans as cells Excel can sum and filter, everything else as text, NULL as a blank cell, written out, so a row of NULLs is still a row when the workbook is imported again. An integer past 15 digits, a decimal with more, or a number too small for Excel's doubles (below 2.2251E-308, which Excel would read as zero) goes in as text rather than rounded; dates go in as the text the grid shows. Text keeps every character: a carriage return, a control character and text that reads like Excel's own escape, such as _x0041_, come back as written, in Excel and in the import. A sheet holds 1,048,575 rows; rows past that continue on the next sheet. A text longer than Excel's limit of 32,767 characters a cell goes in cut to that length, which no workbook can hold, and the sheet says how many values that touches: under the Excel pick for a result, before Save… is pressed, and in the saved line for a result and a table alike. Another format carries such a value whole.
Markdown is a pipe table with a header row. A table cell holds one line, so a pipe or a backslash in a value is escaped, a line break becomes <br> and a carriage return . A value's own <br> is text, not a line break, and is written \<br>; the spaces at a value's two ends, which a reader takes for the cell's padding, are written  . Each reads back as it was, and a Markdown viewer shows the value as it stands. HTML is a page holding one table, the column names as a header row. White space at a value's two ends is written as numbered references there, whatever kind it is: a space, a tab, a line break, a no-break space  , a thin space, a line separator. So is every carriage return. Each reads back as it was. At the two ends of a cell, a reader takes white space written any other way for the page's own and drops it: the indentation, a closing <br>, an . XML is a <table> of <row> elements, one <field name="…"> per column, NULL as null="true". A carriage return is written , so it reads back as itself; a control character, which XML cannot hold, is left out. A byte-order mark (U+FEFF) that a value or a column name holds is kept when an XML file or an Excel workbook is read, also at its very start, and also where the file names it by its number (), as a tool that writes plain ASCII does.
A result's export holds the rows that are loaded. Export Data… on a table reads every row, ordered by the primary key where the table has one. Each page after the first starts after the last row's key, so a row added or deleted while the export runs cannot shift the pages and lose a row. On ClickHouse and Databricks, whose keys need not be unique, and on a table without a key, the pages go by position instead. Copy to Database… reads its pages the same way.
Preview in Browser writes the page to a file in the temporary folder and opens it with the default browser: a result's rows whole, a table's first 100 rows.
Import data
Load a file into an existing table, with each of its columns mapped to the column it belongs in — or into a new table made from the file's columns. Any format the export writes: CSV, TSV, JSON, JSON Lines, Excel, XML, Markdown or HTML. A SQL file opens as a query tab instead.
Import Data: each column of the file, with a sample value, beside the table column it fills.
How to
Right-click a table in the sidebar or in the Tables listing and choose Import Data…, then pick the file. Or drag the file from Finder onto the table's row: the row lights up under the file, and the sheet opens for that table.
Dropped on a database in the sidebar, on its Tables folder, or on the ground of a Tables listing, the file lights what it is over and asks which table of that database takes it. Dropped anywhere else on the window, or opened with File ▸ Open…, it asks about the database in front. Dropped together with a SQLite or DuckDB file, it waits for that database to open, then asks about it.
To make a new table instead, press New Table…. The New Table designer opens in a tab with one column per column of the file, each typed by its values; change what you like and press Create Table. The Import Data sheet then comes up for the new table.
In the Import Data sheet, check the format it was read as. For delimited text, check the Delimiter — detected from the file, and changeable — and First row is header; a file that names its own columns, such as JSON, asks neither. Check Empty fields become NULL.
Look over the mapping: each column of the file, with a sample value, beside the table column it will fill. Choose another column, or — skip —.
Click Import. When it finishes, the table opens.
Technical notes
Header names and JSON keys are matched to column names: the column spelled exactly so first, spaces included, else the one column that matches without regard to case. Only when the table has neither does a name count without the spaces around it, so the id, name header of a hand-made CSV still fills name. A name that matches two columns loosely, such as Id against ID and id, is left for you to pick. With no header, columns map by position. A header that names one column twice maps both of the file's columns onto it, and the sheet says so and refuses to import until each has a column of its own or one is skipped. Through New Table… the designer names them apart, value and value_2, and the import maps the file by the designer's names.
A generated column, which the table computes itself, takes no value: it is not offered in the mapping, a file column with its name, in any case, maps onto nothing rather than onto another column by position, and the inserts never name it.
An Excel workbook is read whole or not at all. A workbook with a sheet cut short, a part that does not match its checksum, a sheet the workbook names and does not hold, a cell past Excel's last column (XFD), or a cell that refers to a shared text the workbook does not hold is refused as damaged, and nothing of it is imported.
A .csv, .tsv or .txt file is read as delimited text, its delimiter chosen from comma, tab, semicolon and pipe by which one splits its first lines the same way. A field is read character by character as the file holds it, so a value beginning with a combining accent is its own field, never joined to the delimiter before it. A file with no telling extension is read by its first bytes.
JSON is an array of objects, an array of arrays, an object whose only member is such an array, as in {"data": […]}, or any other object, which is one row: an order with its list of items is one row, the list as its JSON text. JSON Lines is one of those per line, a line ending at a line feed or a carriage return: a line or paragraph separator inside a value is part of the value, as it is in a Markdown cell. A record that names one field twice is refused, with the field named, rather than read with one of its two values; so is an XML row. Numbers and booleans go in as numbers and booleans, a nested object or array as its JSON text. A json column takes each value as the JSON it is: a string as a JSON string, quotes and all, a number or a boolean as JSON's own, so what a json column held comes back from its own JSON export unchanged, the string "123" a string and not the number 123. JSON's null is NULL. Excel's first sheet is read, with numbers, booleans and date-formatted cells typed, and text as Excel shows it: an escape such as _x000D_ is the character it stands for, and the reading Japanese Excel keeps beside a word typed in kanji is left out. XML takes the export's layout and its cousins: the root's children as rows, a field named by its name attribute or its element name. Markdown takes the first pipe table: an escaped pipe, backslash, < or & is the character itself, a <br> a line break, and a numbered reference such as | the character it names. HTML takes the first <table>.
In a file of one column an empty value is a row, whether it is written as "" or as an empty line. In a file of several columns an empty line is skipped. Empty lines before the first row and after the last are skipped in every file.
New Table… guesses each column's type from the file's values: whole numbers, decimals with the precision the values need, booleans written as true/false or yes/no, dates and timestamps in ISO form, and text otherwise — spelled the engine's way, a VARCHAR sized by the longest value where the engine sizes text. A number with a leading zero stays text. Every column is nullable; the table is named after the file.
A flag written as a word — true, false, yes, no — goes into a boolean column as the engine's own flag.
Hex text into a binary column goes in as the bytes it spells, as the engine's own literal: bare hex as Export Data… writes it, or with the \x or 0x prefix other tools write. Other text goes in as text. Into an Oracle BLOB column a value past 2,000 bytes goes in the same way an export writes it, as a PL/SQL block.
An Excel workbook whose later sheets carry the same header row as the first, such as one Export Data… wrote past Excel's row limit, is read as one table, sheet after sheet, and the sheet says how many were read. A sheet with other columns is left out. Rows at the end of a sheet that hold no value and only formatted blank cells, or no cells at all, are left out; a blank cell written out, as Export Data… writes a NULL, makes its row a row, so a workbook the app wrote comes back with every row.
A file's ids go into an id generator, an identity column or a serial, as they are: on PostgreSQL with OVERRIDING SYSTEM VALUE where the column always generates; on Oracle and Db2, which have no such clause, with the identity turned BY DEFAULT for the import and ALWAYS again after it, the way a table copy does; and on SQL Server with IDENTITY_INSERT switched on for the table around the import and off after it, on the import's own connection, whether or not the rows went in. Once the rows are in, each generator's counter is moved past the imported ids, so the table's next row without an id takes a fresh one; MySQL, MariaDB, SQLite and SQL Server keep their counters themselves. If moving the counter fails, the rows stay in and the message says so.
Rows go in as multi-row INSERTs of 250. Where the engine has transactions they all run inside one, so a bad row leaves the table as it was. Databricks commits each batch on its own, and the sheet says so.
Importing waits while the tab has pending grid changes or an open transaction.
Show DDL
Read the CREATE statement of anything in the sidebar, rebuilt from the server's catalog.
Show DDL for a table: the CREATE statement, and its index after it.
How to
Right-click an object and choose Show DDL, or press ⌘K and type ddl and the table's name.
The sheet offers Copy SQL, Save…, and for a table Copy JSON Schema.
The inspector's DDL page shows the same statement for whatever is selected in the sidebar.
The statement is spelled the way the connection reads strings, so it runs there as it stands. MySQL and MariaDB print a definition with backslash escapes even to a connection running NO_BACKSLASH_ESCAPES; there the app shows each backslash once, in Show DDL, in a view or routine opened for editing and in Duplicate…. MySQL and MariaDB record, with every function, procedure, trigger and event, the SQL mode of the connection that made it, and read its text in that mode whoever calls it: whether || joins two texts, whether "…" is a string or a name, whether a backslash escapes, how strict it is. A routine made under another mode than the connection's is therefore shown with its mode: the statement opens with a SET SESSION sql_mode line naming it and shows the routine as that mode reads it, a name typed in double quotes in backticks. Run as it stands, it makes the routine as it was. The same line opens the script a routine is opened for editing with, and Duplicate… shows it and makes its copy under that mode. A tab that runs such a script stays in that mode afterwards, as its first line says; nothing can follow a routine in a script, so no line puts the mode back. A routine made in the connection's own mode is shown as it was typed, with no such line.
Technical notes
Available for tables and views, and for functions, procedures, triggers, events, sequences, types, synonyms, partition functions and schemes, aggregates, conversions, operators, operator classes, extensions, casts and tablespaces.
On PostgreSQL an identity column's definition carries the options its sequence differs from the defaults by, such as GENERATED BY DEFAULT AS IDENTITY (INCREMENT BY -1), so the statement recreates a column that counts the same way. A stock identity reads as plain GENERATED BY DEFAULT AS IDENTITY.
On PostgreSQL the table's statement is followed by every index that no primary key, unique or exclusion constraint owns; an index the server made for such a constraint comes with the constraint's own line. An index that only shares its name with a check or foreign key constraint is written like any other.
On SQL Server an IDENTITY column's definition carries its seed and increment, IDENTITY(1,1), read from the server's catalog, so the statement recreates a column that counts the same way.
Design
Create and change tables, and every other kind of object your engine has, with the SQL in view before it runs.
The table designer
The designer loads a table's columns, indexes and foreign keys as drafts. As you change them, it works out the ALTER statements that turn what the server has into what you drew, and shows them to you.
The table designer: the columns, the selected column's settings under them, and the SQL preview at the bottom.
How to
Right-click a table and choose Edit Table…, or choose New Table… from a Tables folder. The designer opens as a tab, so your drafts survive a look at another tab.
Under Columns, edit Name and Type, tick PK and NN, and drag rows to reorder. Select a column for its Collation, Default, Auto-increment, Generated and Comment settings; the row's Details cell shows them at a glance, the comment in quotes. The table's own Comment is in the header. Add Column is under the rows.
Switch to Indexes or Foreign Keys for Add Index and Add Foreign Key, with On Delete and On Update rules.
Read the SQL Preview. Problems show in red, notes in grey. Click Apply Changes; the designer stays open on the fresh structure.
Technical notes
PostgreSQL and DuckDB retype a column with ALTER COLUMN … TYPE … USING column::type, so existing values are cast. A column's collation rides every retype, named with its schema on PostgreSQL, so a collation of your own in another schema, or one named default, is the one kept; the collation picker lists each beside its schema, and a collation created during the session is listed after the next refresh. A PostgreSQL generated column retypes without the USING clause, which the server refuses there, and keeps its expression; changing the expression itself needs PostgreSQL 17. The designer sends only what you asked for, in one fixed order: generated columns you drop first, then a new column an expression reads, then each column's changes, then the other drops, then the renames. So, in one edit, a column can change type while the generated column that reads it is dropped, a generated column can be pointed away from a column you drop, and an expression typed with a column's old name is rewritten by the server when that column is renamed. Two columns whose names differ only by case, such as a and A, are the two columns PostgreSQL keeps. A change the server refuses shows its message and changes nothing.
MySQL and MariaDB can only change a column by restating all of it. The designer restates it in full, default, collation and comment included, and refuses a column whose extra attributes it could not restate safely, pointing you to SQL. A default is shown as SQL: MySQL reports a text default without its quotes, such as active, and the designer shows and writes 'active'; an empty text is ''. On a connection running NO_BACKSLASH_ESCAPES a backslash in a default is shown once, as that connection reads it. A generated column is read with its expression and restated with it, so the expression can change in place and the column can be retyped, renamed or moved; a stored one can become a plain column holding the values it computed, a virtual one cannot, and neither server switches a column between stored and virtual. MariaDB generated columns are always nullable. The expression is read from the server's two catalogs together, information_schema and SHOW CREATE TABLE, because neither alone hands back text outside ASCII whole: MySQL's information_schema re-encodes it and both servers' SHOW CREATE TABLE or information_schema write an emoji as question marks. Read that way, café, 日本語, an emoji and a column named 基数 come back exactly and are restated exactly. In the one case neither catalog can settle, the column is shown and any change to it is refused in words, pointing you to SQL, so question marks are never written into its values. The statements run in one order on every engine: the columns dropped first, then the new columns an expression reads — a new column before the new column that reads it, and a column whose name a new one takes renamed ahead of that add — then the moves into the order you arranged, each column's changes under the name the column has at that point, the drops that waited for a generated column to be pointed away from them and the renames, each statement judged against the table as it stands at that point, then the other new columns, each where you placed it. So a stored column you make plain is made plain before a reader you drag above it is moved, and a column you rename is renamed before a reader is pointed at its new name. A generated column may read only the generated columns above it on these servers, so the designer refuses in words a reader placed above a generated column it reads, before anything runs. So one edit can drop a column while pointing its reader at another, rename the reader into the dropped column's name, add a column and read it, add new columns that read one another, or give a new column the name of one it renames. MySQL refuses to rename a column a generated column reads, so there the rename carries the readers' definitions in the same statement, and is refused in words when a reader is one the designer cannot restate safely, an invisible column for instance, however that reader is arranged in the same edit; MariaDB rewrites them itself. In an expression you type, a column may be named with the table in front of it, such as orders.amount. On a connection running NO_BACKSLASH_ESCAPES the expression is shown and restated the way that connection reads strings, so restating it leaves the column's values as they were.
Comments are written the way each engine keeps them: COMMENT ON on PostgreSQL, Oracle, Db2 and DuckDB; in the column definition and the table options on MySQL, MariaDB, ClickHouse and Databricks; the MS_Description extended property on SQL Server. SQLite keeps none, so the fields do not appear there.
SQLite cannot alter most things in place. The designer follows the SQLite manual's recipe — new table, copy the rows, drop the old one, rename, restore indexes and triggers — in one transaction. When the designer opens, it reads the table from the file in one read — its columns, indexes and keys together with the stored definitions the rebuild restores — rather than from the sidebar's earlier reading, so a column or an index another connection added since the sidebar last read the file is in the designer and survives the rebuild. The indexes and triggers it restores are the ones it read then, so before the old table is dropped, the table's stored definition, its indexes and its triggers are compared with that reading; if any of them was added, changed or dropped since, say a trigger created from a query tab, the change is refused with the object named and nothing is changed. Close the designer and open it again to apply the change to the table as it stands. SQLite enforces a foreign key only on rows written after it exists, so before the transaction commits, the rebuilt table and every table whose foreign keys point at it are checked, the tables found in the file as it stands then, so a child table made after the designer opened is checked too. If a row points at a row that does not exist, the change is refused with the table and the number of rows named, and nothing is changed. Foreign-key enforcement, when it is on, is switched off for the rebuild and back on afterwards, whether the change went through or not. An AUTOINCREMENT counter crosses the rebuild as it stands when the change is applied, inside the same transaction, so an id handed out and deleted while the designer was open is never handed out again. Generated columns are read from the table's stored definition and restated by the rebuild, which copies only the plain columns and lets SQLite compute the rest again; a Virtual one can be added to an existing table, a Stored one only when the table is created. A generated column whose expression names a column you rename or drop in the same edit is refused until you change its expression in that edit too. Column names in every spelling SQLite accepts — bare, in any script, with a dollar sign, or quoted with double quotes, backticks, square brackets or single quotes — are read the same way, and a column declared without a type keeps none.
The script runs in a transaction on PostgreSQL, SQLite, DuckDB and SQL Server. MySQL, MariaDB and Oracle apply each change at once, so a failure partway leaves the earlier ones in place; a note beside the buttons says so.
What an engine cannot do is stated, not hidden: ClickHouse keys are fixed at CREATE and its columns have no collation; SQL Server defaults are named constraints; MySQL, MariaDB, Oracle and Db2 give a table one auto-increment column; DuckDB cannot add or drop foreign keys, takes generated columns only when a table is created, virtual ones, and changes nothing about one but dropping it — where one generated column reads another, the reader is dropped first; Databricks tables have no conventional indexes. Apply Changes stays off while a red problem stands.
Drop… asks you to type the table's name.
Compare schemas
Two databases of one engine side by side, and the script that makes one like the other.
Staging against the shop: one table changed, one missing, and the script that brings the shop up to date.
How to
Right-click a connection and choose Compare Schemas…, or press ⌘K and type compare. Pick the Source connection and database and the Target ones: both connected, both the same engine.
Click Compare. Every table that differs is listed with what differs: columns to add or change, indexes and keys to add or replace, and what only the target has.
Read the script. Open in Query Tab puts it in a tab on the target, where you run it; Copy Script takes it elsewhere.
Technical notes
Tables, their columns, primary keys, indexes and foreign keys are compared, by name: the same name first, and a name that differs in case alone pairs only when it is the one such name on each side, so value and Value side by side are two columns. An index's or a foreign key's columns, and the table a key points at, are told apart the same way, so an index on Value is not one on value. What the script writes names the target's spellings: a key the source points at ReviewParent lands pointing at the target's reviewparent when the two pair, its columns the same way, and an index or a key added to a table both sides have names that table's columns as the target spells them; a table the target lacks keeps the source's name, which the script creates. A key that points into another schema names a table the compare does not have, so its names go by the engine's own rules, and so does whether it points into another schema at all: on PostgreSQL a key from src into "SRC" names another schema and stays pointed there, while on SQL Server the two are one schema and the key moves to the target. A column is as written on PostgreSQL, Oracle, Db2 and ClickHouse, which tell ID from id, and without regard to case elsewhere; SQLite and DuckDB disregard the case of ASCII letters alone, so É and é are two names there, as they are to those engines, while MySQL, MariaDB and SQL Server read the two as one. A schema or table name is as written on MySQL and MariaDB too: there the server's lower_case_table_names decides, and a Linux server keeps Parent and parent apart. On PostgreSQL a column's collation is compared with its schema, and one in the compared schema points at the target schema's collation of that name, the way a key does. On SQL Server the target database's collation decides what is one name: under a case-sensitive or binary collation A and a are two columns, and under a binary one so are the two spellings of an accent, so each gets its own line and its own statement. Views, routines and other objects are not compared: they are one engine's SQL text, and a text diff is not a migration.
The script comes from the designers' own planners — the table designer's ALTER statements for a table both sides have, the CREATE TABLE the New Table designer writes for one the target lacks — in the target's dialect, one block per table. On PostgreSQL, SQL Server, SQLite and DuckDB the whole script is one transaction, so a statement the server refuses, such as a foreign key the target's rows do not fit, leaves the target as it was; on MySQL, MariaDB, Oracle, Db2 and Databricks each statement lands as it runs. CockroachDB applies a primary-key change in a transaction of its own, in its table's place in the order, so a script that changes one commits in parts, and the tab's notes say so. The blocks come in the order the server needs. The foreign keys to drop come first, in a block of their own per table, so a key another table depended on can go and a key moved on both sides goes through. Then a table's block after the blocks of the tables its new foreign keys point at, whether those tables are created or changed, so a new table follows the block that gives an existing table the unique key its foreign key needs. The drops of what only the target has come last, except that a dropped table goes before the block of a table its foreign keys point at, and before a dropped table it points at. The list on screen reads by name.
What only the target has is reported and kept unless you tick Drop what only the target has: a column is data. A change the engine has no ALTER for, such as a column's type on SQLite, is listed as a problem and that table's block is left out. SQL Server's IDENTITY is one of those: a column the target lacks is added as an IDENTITY(1,1) column, which numbers the rows already there, but the property cannot be added to or removed from an existing column, so that is listed as a problem; and a second identity column beside the target's own is a problem too, the server allowing one per table.
On MySQL and MariaDB a generated column's expression is compared by what it means, not by how each connection spells its strings: the same table read through a connection running NO_BACKSLASH_ESCAPES and one in the default mode is no difference, and an expression written into the target is spelled the way the target connection reads strings. PostgreSQL the same, for a column's default and its generated expression, between a connection with standard_conforming_strings on and one with it off. An expression the source server could not hand back exactly is listed under its table as not compared and as a problem, and left for you to write; the target is never reported as matching on its account.
Nothing runs until you run it: the script lands in a query tab like any other SQL.
Kinds of object
The sidebar shows a folder for each kind of object the engine has, and only those. Eighteen kinds of schema and server object, plus users and roles, make twenty.
Every kind has a listing tab, Show DDL and a Drop… that asks first. Designers open as tabs and preview their SQL.
On MySQL and MariaDB, the trigger and event designers show a body the way the connection reads strings, so a backslash typed once is shown once on a connection running NO_BACKSLASH_ESCAPES too, and saving writes it back unchanged. A trigger or an event made under another SQL mode than the connection's keeps that mode: the designer shows its body as that mode reads it, its script opens with the SET SESSION sql_mode line that puts the mode on, and Save runs under it and puts the connection's own mode back afterwards, also when the save fails. The server then still records the mode the routine was made under, and reads its ||, its quotes and its backslashes as before. An event's comment is kept exactly, backslashes included, and a comment you clear is removed.
Kinds that belong to the server rather than to a schema — partition functions and schemes, extensions, casts, tablespaces, accounts — hang from the connection, not from a schema.
On SQL Server a partition function's boundaries over a text type, and filegroup names, are told apart as the database's collation tells text apart: 'A' and 'a' are one boundary in an ordinary database and two in a case-sensitive one, where a filegroup of your own may also be called primary beside the server's PRIMARY.
The database overview
Click a database in the sidebar for a one-page summary: what it holds, with a door to everything you can create in it. Click a connected connection for the connection's own page: its schemas or databases, each a click from its overview, and the Server section — the server-level kinds, the accounts, the backups, the console and a card to create a database or schema. On PostgreSQL, SQL Server and Databricks the connection's page lists the server's databases, each a card that opens it, with a card to create a new one, and a database's own page lists its schemas with what belongs to that database.
The overview of a database: a row per kind of object, with its count and a + to make one.
The heading shows the connection, a live dot, and the server's version.
Objects has a card per kind with its count and a + to make a new one, plus Queries, Diagram and Console, which opens the engine's own client with that database as the current one.
Server, on the connection's page only, has the server-level kinds, the accounts card with New User…, Grant Access… and New Role…, a Backups card whose + starts a dump, a Console card for the connection, and a card to create a database or schema. A database's overview has no Server section.
Technical notes
A kind the engine supports shows even when there are none of it yet, with a count of 0, so the door to the first one is always there. The sidebar does the opposite and hides empty folders.
Opening the overview reads what the sidebar has already loaded. It sends nothing to the server.
While the overview's tab title is in italics, a card opens in the overview's own tab: a database's card shows that database's overview there, a kind's card its list, a + its designer or script. Back returns to the overview, still in italics.
Click the overview itself, anywhere but on a card, or click its tab, and the title turns upright: the overview is kept. From then on what its cards open gets a tab of its own and the overview stays.
On PostgreSQL, SQL Server and Databricks the connection's page holds the server's own: a card per database, which shows how many schemas it has once it is open, the tablespaces and the backups. A database's page holds its schemas and, under Database (Catalog on Databricks), its extensions, casts and partition objects, the accounts, a Backups card whose + dumps that database, its console and a card to create a schema.
There is one overview tab per database, and one for the connection; clicking the row again brings it forward. A connection that is not connected opens nothing on a single click, as before: double-click it, or choose Connect, and its page shows once it is connected. Unfolding it with the caret only connects it, without switching to it.
Switching to a connection with no tab open, or only blank query tabs, shows its page once connected. If it already holds a query, a blank tab moved there stays an editor beside that query. Disconnecting closes the connection's page; the database overviews stay.
Users and roles
On engines with accounts, the sidebar lists them under Users & Roles — Users on MongoDB, ACL Users on Redis, Users, Groups & Roles on Db2, Principals & Permissions on Databricks.
Users & Roles on a PostgreSQL server.
How to
Open the accounts folder and double-click an account, or click New User…, New Role… or Grant Access…
Set the Name, Password, Abilities, Member of and Grants the engine offers.
Read the SQL preview, then click Create or Save. Edit as SQL hands you the script in a query tab instead.
To read the accounts again, after another administrator has changed them, press ⌘R in the tab, or right-click the list and choose Refresh; the Users & Roles row in the sidebar has the same Refresh in its menu. Only the accounts are read again, not the tables. Whichever side you ask from, both show it, for half a second at the least: a spinner beside the count in the tab, and in the sidebar the connection's icon turns into a spinner while the Users & Roles rows fade.
Technical notes
PostgreSQL has the most to set: can log in, superuser, create databases, create roles, inherit, replication, bypass row security, a connection limit and an expiry date. Grants at database, schema and table level.
MySQL and MariaDB accounts are name@host, with a connection limit and grants at global, database and table level. The accounts and role memberships are read from the catalog of the server that answered, not of the type the connection was saved as: MariaDB's mysql.user marks its roles and files memberships in roles_mapping, MySQL's in role_edges, so a MariaDB behind a connection saved as MySQL is read as MariaDB. ClickHouse grants at the same three levels.
SQL Server has three states for a permission: granted, denied, and not set. A DENY wins even where a role would allow, and the editor keeps it apart from a missing grant.
Oracle grants at system and table level. MongoDB grants are its built-in roles, such as read, readWrite and dbAdmin. Db2 and Databricks accounts come from outside the database, so they can be granted to but not created.
Redis shows each ACL user's rules read-only; change them with ACL SETUSER in a query tab or the console. The pane needs Redis 6.0.
SQLite, DuckDB and data files have no accounts, so no folder.
Understand
See how the tables fit together, turn a result into a picture, and ask questions in plain words.
The schema diagram
Every SQL database gets a diagram drawn from its real foreign keys: tables that refer to nothing at the top, the tables that depend on them below, unconnected groups set apart.
A schema of nine tables, drawn from its foreign keys.
How to
Click Diagram under a database in the sidebar, or the Diagram card on its overview, or right-click a table and choose Show in Diagram.
Drag the background or scroll to move around. Hold ⌘ and scroll to zoom about the pointer, from 50% to 200%.
Click a table to pick it out: every line that touches it lights up in the connection's colour, the tables at the other ends are outlined, and the sidebar moves to the table. Click a line to pick out that one key, the two tables it joins and the columns it is made of. Click the background to let go.
Drag a table to put it where you want it; the rest stay put. Reset Layout undoes your placements.
Type in the filter (⌘F) to show only tables whose names match.
Double-click a table to open it. Double-click a line to edit that foreign key.
Technical notes
A line ends in a crow's foot for one-to-many and a bar for one-to-one, which is when the key's columns are also a primary key or a unique index.
A table that refers to itself gets a loop. Several keys between the same two tables are drawn as separate lines.
SQLite's keys that point at a table without naming a column are resolved to that table's primary key.
Views are left out. References into another schema are counted under the diagram rather than drawn.
The layout is worked out from the schema, so the same schema always draws the same way. Your placements last as long as the tab does.
MongoDB and Redis have no foreign keys, so no diagram.
Charts
Any result with a number in it can be a chart. The chart is another view of the same result, so the grid is one click away and a re-run redraws it.
A bar chart over a GROUP BY result.
How to
Click the chart button in the result bar, or press ⌘K and choose Show Result as Chart.
Pick the Chart type: bar, line, area, pie or scatter.
Pick X, one or more Y columns, a Series column to split by, and an Aggregate: None, Sum, Average, Count, Min or Max.
Click the copy button to put the chart on the clipboard as an image.
Technical notes
The first chart is a guess from your columns: dates on X give a line, categories a bar, two plain numbers a scatter. Columns that look like ids are not offered as Y.
Limits keep a chart readable: 8 series, 50 categories, 4,000 points, and 6 pie slices with the rest folded into Other. When a limit cuts something, a note under the chart says what.
A chart goes by what a label reads. Two values, or two column names, that read the same are one bar, one slice or one series, and the aggregate folds their numbers together. The grid keeps them apart.
The eight colours are fixed and checked for colour-blind readers in both appearances. They are never recycled, which is why series stop at eight.
The AI assistant
Ask about your data or terminal output in plain words. The assistant can check answers with read-only queries and suggest SQL or shell commands for you to run.
An answer from the assistant: the read-only query it ran, a table, and SQL to put in the editor.
How to
Open Settings ▸ AI. Choose a Provider — Claude, OpenAI, Gemini, Grok, DeepSeek or Mistral — paste your API key and click Save. Your saved key stays hidden. Click the eye beside it and confirm with Touch ID or your Mac password to see it. Pick a Model from the provider's list. Switching providers keeps each provider's saved model. Use Thinking to choose how much the model reasons before answering, or leave it on Model default.
Or choose Local server for a model on your own Mac. Ollama's address, http://localhost:11434/v1, is already there; LM Studio listens at http://localhost:1234/v1, and any server that speaks the OpenAI dialect works, on this Mac or elsewhere. Type the address, press Return, and pick a model. No key is needed unless the server asks for one. With Ollama, Thinking offers the levels the server reports for the model.
Click AI Assist in the toolbar, or press ⌥⌘A, and ask. The button is in the toolbar before any key is saved: until a key and a model are set, clicking it opens this Settings pane.
The line under the panel's title names the provider, the model and the thinking level that answer you. Click any of the three to change it there: the next question uses the new choice, and so do the editor's suggestions, since it is the same choice Settings holds. The provider menu lists the providers already set up in Settings, a key and a model each, and its last item opens Settings to set up more. A model offered no thinking levels leaves that menu at Model default, greyed.
Click Insert into the editor on a SQL reply, then press ⌘Return to run it. In a console or terminal tab, click Insert into the terminal, then press Return. Insert moves the keyboard focus there. Use Copy to put the code on the clipboard instead.
Some terminal programs accept only one line at a time. For these, each click inserts one line and shows your progress. Press Return, then click Insert for the next line. Blank lines count too. Programs that support pasting several lines receive the whole block at once.
Use the assistant in a database console or a terminal on This Mac or an SSH host. It can read the current screen and earlier output, explain errors, and suggest commands for that machine. In database consoles, it can also run supported read-only queries. Shell commands run only when you press Return.
Suggest completions while typing SQL offers whole-line suggestions in the editor. Turn it off in the same pane if you prefer the editor quiet.
Technical notes
What is sent, and only when you ask something: your question and the conversation, the engine and server version, the current database, table and column names with their types, up to 2,000 characters of the editor's text, and your custom instructions. Rows are sent only as the result of a query the assistant ran to answer you, at most 50 rows with long cells clipped. In front of a terminal tab, the terminal's screen as it stands when you send, up to 12,000 characters of its newest lines, goes in place of the editor's text, with the name of the program at the prompt, the folder the shell reports, and what the machine is: this Mac's macOS version, or the line an SSH host answered when it connected. The assistant also has a tool that reads the screen again at any moment, and with it the output that has scrolled off the screen: the app keeps its own plain-text record of everything a console printed, the last 400,000 characters, and the tool reads that record a page at a time. Output of full-screen programs such as less or htop reads muddled there; command output and logs read cleanly. The tool reads and nothing more: it cannot type into the terminal. The app knows whether the program at the prompt keeps a pasted block whole from the program's own signal to the terminal (bracketed paste, which readline and zsh turn on at every prompt, and which a full reset of the terminal turns off again); without it, Insert never hands the program a line break, so nothing runs before you press Return.
On a host the assistant's one tool reads the terminal. There is no database to read, and a shell command cannot be checked for safety the way a query can, so the assistant writes commands and runs none of them; a command runs when you press Return. When an SSH host connects, one command runs over its connection once, for the assistant: uname -srm, the account's SHELL, and /etc/os-release where there is one, so the commands it writes fit that system. A host that does not answer leaves the assistant to read the screen. When the shell is zsh, the assistant is also reminded of zsh's history expansion and its rule for a pattern that matches nothing, two places where a command written for bash goes wrong.
The read-only guard is code, not a request to the model. A query the assistant wants to run must start with a reading word such as SELECT, WITH, SHOW or EXPLAIN, be a single statement, and contain no word that writes, grants, calls a procedure or starts a transaction. Functions with side effects are refused as well. The query is read the way the connection's engine reads SQL, so a write cannot sit behind a quote or a comment that the engine reads differently. Where a backslash in a string means what the connection's own setting says, on MySQL, MariaDB and in a plain string on PostgreSQL, a query that holds one is refused and the assistant is told why, so it can write the string a way that reads the same on every connection.
Then the engine enforces it again: the query runs on a separate connection in the engine's own read-only mode, such as BEGIN READ ONLY on PostgreSQL or PRAGMA query_only on SQLite. On SQL Server, Db2, Databricks and DuckDB, where no such mode is available, the assistant runs no queries at all; it still sees the schema and writes SQL.
A statement that would change data is handed back to you as text.
A suggestion and the completion list take turns in the editor, since ⇥ accepts either. While the list is open under the word you are typing, no suggestion is asked for; it is asked for when the list closes — you type a space, pick an entry, or press esc — and shows then.
A model that thinks before it answers has that thinking counted against the size limit of its reply. A suggestion's limit leaves room for it, on every provider, so the thinking cannot use up the room the suggestion needs. How much a model thinks is left to the model.
The Thinking levels come from the provider, never from a list of the app's own. Claude's model list reports which levels each model takes. Gemini's own catalog says which models think, and those take minimal, low, medium and high. Mistral's model cards say which models reason, and those take none or high. A local Ollama server reports each model's levels. OpenAI, Grok and DeepSeek say nothing about levels in their model lists, so the levels their documentation names are offered whole: OpenAI's none, minimal, low, medium, high, xhigh and max; Grok's low, medium, high and xhigh; DeepSeek's none, low, high and max. A provider that offers no levels for a model leaves the picker at Model default, disabled.
A level a model refuses is taken off that model's list, and the pick goes back to Model default. The refusal is shown in the chat in the provider's own words; when it names the levels the model does take, as OpenAI's does, those are the ones kept. The list stays cut until the provider's offer changes.
Your key is kept in the Keychain and goes only to the provider you chose. With a local server, everything goes to the address you typed and nowhere else, and no key is needed. With nothing set up, nothing is sent anywhere.
Drag the panel's left edge to size it. It can be as wide as the window allows; the editor and results keep a minimum width. With the inspector and the assistant both open, dragging one never resizes the other.
Move data
Copy tables from one server to another, even when the two do not speak the same dialect.
Copy objects between engines
Drag a table from one connection onto another connection's database, and the app writes the CREATE in the target's dialect and copies the rows.
Dragging a table from PostgreSQL onto a SQLite file.
How to
Connect to both servers. Drag a table — from the sidebar, or several at once from a Tables listing — onto a database of the other connection in the sidebar, or onto one of its listings open on the right: the Tables list, or any other object list of that database, whether or not it has rows yet. The list lights up while the table is over it. Or right-click the table and choose Copy to Database… Views, functions, procedures, triggers, events and the other objects drag and copy the same way, but only onto a server of the same dialect: a PostgreSQL view goes to another PostgreSQL server, not to MySQL or SQLite. A table is the one object that crosses engines.
In the sheet, the To list offers every connection that can take the objects, each beside its engine's or service's mark, and the database to copy into. Choose Structure and data, Structure only or Data only, and tick Replace existing if a table of that name is already there.
Read the script and any warnings, such as a column type that had to change. Click Copy. Stop ends it early.
Technical notes
Tables move between any two of the ten SQL engines: PostgreSQL, MySQL, MariaDB, SQLite, SQL Server, Oracle, IBM Db2, DuckDB, ClickHouse and Databricks. Column types are translated, and the sheet lists every one that changed, along with defaults or indexes that could not travel. A generated column lands as a plain column holding the values copied, since its expression is written in the source engine's own SQL, and the sheet names it; a copy between two databases of the same engine keeps it generated. Rows copied into a table that already exists (Data only) are written under that table's own spelling of its name and columns, so a target that calls the table Orders, or a column Doubled, takes them. A text default travels as its value. The app reads it the way the source engine writes it, such as a quote that ClickHouse writes with a backslash, a backslash that MariaDB doubles or that PostgreSQL doubles for a connection with standard_conforming_strings off, or a value that MySQL reports without its quotes, and writes it out the target's way. A default it cannot read exactly is left out and listed. Between two connections of the same engine that read a backslash differently (NO_BACKSLASH_ESCAPES on MySQL and MariaDB, standard_conforming_strings on PostgreSQL), a copied table or view, and a PostgreSQL function, keeps its meaning: the strings of its definition are spelled for the connection that runs the copy. A table or view that a MySQL or MariaDB server printed with its names in double quotes, as it does for a connection running ANSI_QUOTES, is copied with them in backticks. A backslash inside such a name is a character, so a table called ends\, or one with a column called tail\, is copied under its one name. A MySQL or MariaDB function, procedure, trigger or event is kept by the server as it was typed and read in the SQL mode it was made under, so its copy is made under that mode: where the connection that runs the copy is in another, the sheet's script sets the connection's mode aside, puts the routine's on with a SET SESSION sql_mode line, creates the routine spelled for it, and puts the connection's own mode back, also when the copy fails. The copy then reads ||, text in double quotes and backslashes as its original does, and is as strict. A mode the receiving server does not have, such as MariaDB's NO_AUTO_CREATE_USER on MySQL, is left out, and the sheet names it. MySQL itself reads a generated column or a CHECK that holds a backslash again in the mode of the session at hand, so one created while NO_BACKSLASH_ESCAPES is on behaves as that server makes it; MariaDB keeps it as written.
A copy is planned from the tables as the server has them when the sheet opens, not as the sidebar last read them: a column added on another connection since then is copied with its values, and the sidebar is refreshed to match. If a table changes again between the preview and Copy, the copy stops before writing anything and asks for a fresh drag; a preview rebuilt after that, by a change of mode or destination, reads the table's definition again, so an index added in between is in it. A Data only copy reads the table the rows land in the same way, from the target as it stands when the sheet opens rather than from the sidebar, so a generated column made plain there since takes the source's values, and a target table changed between the preview and Copy stops the copy before it writes. On Databricks, whose catalog does not say which columns are generated, both readings take in each table's full definition, when the sheet opens and again before Copy, so a generated column made plain there, on the source or on the target, is caught the same way. A Data only copy whose source column the target spells in more than one way but for letter case, VALUE beside Value, is refused, naming both, since no one of them is the column meant; a single spelling apart in case alone still takes the values. On PostgreSQL a column's own collation travels with the copy, named with its schema, so a case-insensitive column compares the same way on the copy, a collation of your own named default included: only the built-in default is left off, told apart by what it is rather than by its name.
Only names move. A copy to another database of the same engine reads the definition as that engine's own SQL and swaps the source schema's name for the target's where it names an object: in the table's own name, a foreign key, an index, a view's or trigger's body, a serial column's 'sales.seq'::regclass, a 'sales.f(sales.mood)'::regprocedure with the types inside its parentheses, and the column types a query declares for a function it reads from, such as json_to_record(…) AS r(state sales.mood), whatever the alias is called, even settings, loop, format, qualify, begin or declare, and whether it is written with AS or without. A table written as UPDATE ONLY (sales.items), with its parentheses, moves like one written without them. A text default, a check or a comment that mentions the old schema, such as 'https://sales.example.com', keeps its words. A PostgreSQL function's or procedure's argument and result types that live in the source schema move too, whichever schema is on the search path, so copy the type first; its body follows the move the same way, and so does the SQL an EXECUTE inside it runs, whether it stands in parentheses, is written as an E'…' string with backslash escapes, or is joined from pieces with ||: the pieces are read in order, the way the server reads them, so a piece that falls inside a quoted value, such as the middle of 'SELECT ''' || 'sales.value' || '''', keeps its words. Every other piece of text in the body stays as written, whatever quotes it wears: a message, a value it assigns, the text it returns, such as $t$https://sales.example.com$t$. Where a string ends is read the way the server runs the body: by the function's own SET standard_conforming_strings where its definition has one, and by the source connection's setting otherwise, so 'it\'s in sales.items' in an older function is one string and keeps its words. A name is read where it stands: sales.id beside FROM sales.items AS sales is the alias's column and keeps its spelling, while the table moves; so do a record's fields and NEW.column. An alias, a table or a column named begin or declare is read as the name it is, not as the start of a block, so DELETE FROM sales.items begin USING sales.keys AS k moves both tables. A function's or procedure's own SET search_path, and a SET search_path or set_config('search_path', …) in its body, name the target schema in place of the source schema's, the other entries left alone; a column that happens to be named search_path is data, whatever its table or the table's alias is called, and what a function stores in it or compares it with stays as written. A table's columns keep their types from other schemas, public.mood staying public's beside a mood of the target schema's own, and its checks, defaults, foreign keys and indexes name every type and table with its schema, whatever the connection's search path holds.
Views, routines and other objects are written in one engine's SQL, so they copy only to a server of the same dialect — PostgreSQL to PostgreSQL, MySQL to MariaDB. A drop on any other engine is refused, and the sheet's To list leaves those connections out. A data file opened as a connection receives nothing, since its database is in memory and gone at disconnect; the view it opens over the file copies to a DuckDB database.
MySQL and MariaDB each have collations the other lacks, and a table, a view or a routine copied between the two compares text as nearly as the receiving server can. Where the copy will compare text differently, the sheet says so before you press Copy. Before it writes the script, the sheet asks the receiving server whether it has each collation the definition names. One it has stays as written. One it lacks is written as the nearest that server has: MySQL's utf8mb4_0900_as_cs as utf8mb4_uca1400_nopad_as_cs on a MariaDB that does not take MySQL's name, and the other way round on MySQL. The two are near, not the same: MySQL's 0900 collations follow Unicode 9.0 and MariaDB's uca1400 collations follow Unicode 14.0, and several hundred characters, most of them added to Unicode since 9.0, compare or sort differently under the two. Georgian's capital Ა and small ა are one letter to MariaDB and two to MySQL, so a comparison, a unique key or a sort over such text can come out differently in the copy. A recent MariaDB takes MySQL's names, such as utf8mb4_0900_ai_ci, but as names for its own uca1400 collations, so a copy that keeps the name is read by Unicode 14.0 there as well, and the sheet says that too. The binary pair, utf8mb4_0900_bin and utf8mb4_nopad_bin, is one collation, and the collations both products share, such as utf8mb4_general_ci and utf8mb4_unicode_520_ci, compare alike on both: nothing is said of those. A table copied from MySQL keeps MySQL's default, utf8mb4_0900_ai_ci, on a MariaDB that has the name and is not given MariaDB's default; MariaDB then refuses to compare one of its text columns with a column in its own default (“Illegal mix of collations”) until one of the two is converted, with ALTER TABLE … CONVERT TO CHARACTER SET … COLLATE …, or the query names a collation. MariaDB's usual collations leave spaces at the end of text out of a comparison, and MySQL has none of that family that does, so utf8mb4_uca1400_as_cs is written as utf8mb4_0900_as_cs, which counts those spaces, and the sheet says so. A collation that is only a server's default for a character set, such as MariaDB's utf8mb3_uca1400_ai_ci, is written as the receiving server's default for that character set where nothing nearer is there, and the sheet says that too. A collation the receiving server has nothing like, such as MySQL's Japanese utf8mb4_ja_0900_as_cs on MariaDB, stops the copy before anything runs, with Replace existing on as well, so nothing is dropped: create the object there yourself with a collation that server has, and for a table copy its rows with Data only. The words COLLATE … inside a default, a comment or a string are text, and stay. The same holds between two servers of one product, a newer and an older, where a name both have is the same collation.
Rows are read 1,000 at a time and written in INSERTs of 250. Each table's rows are copied in one transaction where the target has them, and rolled back if the copy fails or you stop it.
A copy runs on the connection's main line to the server — the one the sidebar and the designers use — and holds both ends until its transaction has committed or been rolled back. Query tabs have connections of their own, so a run in a tab is never held up by a copy and never lands inside its transaction; the sidebar's own work waits its turn behind the copy.
Creating the structure is not transactional on most engines. If a later step fails after Replace existing dropped the old table, the sheet tells you so.
Replace existing drops only the object spelled exactly like the one being copied. A name that differs in letter case alone, casetwin beside "CaseTwin", is another table on PostgreSQL, Oracle, Db2, ClickHouse, MySQL and MariaDB, and is left alone, so the copy lands beside it; on SQL Server, SQLite, DuckDB and Databricks, which read names without regard to case, it is the same table, and is dropped by its own spelling; SQLite and DuckDB disregard the case of ASCII letters alone, so a café there is left alone by a copy of CAFÉ. MySQL and MariaDB read function, procedure and event names without regard to case, so those are replaced the same way there. A name is not the whole of a routine's identity where its engine tells namesakes apart: on PostgreSQL, where f(integer) and f(text) can stand side by side, Replace drops only the overload with the copy's input argument types (their names aside, and OUT parameters out: p(IN integer, OUT text) and p(IN integer, OUT bigint) are one procedure to PostgreSQL, and p(IN integer, IN text) another) and leaves the others, a type from the source schema, or an array of one, counting as the target schema's type of that name, since that is the type the copy names once moved; a PostgreSQL trigger is replaced only on the table the copied trigger belongs to, and a trigger of the same name on another table stays; an operator is matched by its operand types and an operator class by its access method. Db2 overloads a function by its argument types and a procedure by its number of parameters, and Replace matches them the same way there. Rows copied with Data only still land in the one table whose name differs in case alone, since nothing is dropped for them.
Two saved connections that open the same database count as one place: the same file, or the same server, port and tunnel, plus the same database on PostgreSQL, SQL Server, Oracle, Db2 and Databricks. A PostgreSQL connection saved with a blank database opens the user's own database, and is compared that way; a SQL Server connection is compared by the database it works in, the one chosen in its picker, since that is where the copy runs. The sheet refuses to copy a table onto itself through the other connection, since Replace existing would drop the source before its rows were read. Two different hostnames for one server are not told apart.
Binary columns travel whole: the rows are read with each value as hex, and written as the target's own literal, such as decode('…', 'hex'), X'…' or 0x…. On Oracle the app's helper reads BLOB and RAW values itself, and a value past 2,000 bytes goes into an Oracle table as a PL/SQL block. On SQLite every value travels as SQLite holds it, whatever its column is declared as: a blob lands as bytes in any column of another SQLite file and in a binary column elsewhere, while a blob from a column declared TEXT bound for a text column arrives as NULL; text or a number from a column declared BLOB stays text or a number in another SQLite file, and lands in a binary column elsewhere as the bytes of its text, as SQLite's own CAST to BLOB would. A value that still cannot make the trip, such as a MongoDB target's, arrives as NULL, and the summary counts it.
A composite primary key keeps its order. Each engine's catalog says where a column stands in the key, and the copied key is written in that order, so a key of (name, id) lands as (name, id) and not in the columns' order.
A foreign key comes along when the table it points at will be on the target: dragged in the same batch, or already there. Whether it is there goes by how the target reads a name, since that is the server the key is added on: as written on PostgreSQL, Oracle, Db2, MySQL and MariaDB, so a key into parent finds no Parent there and is left out, with a note saying which table it needed; in any letter case on SQL Server and Databricks, where a key into é finds an É; and in any case of the ASCII letters alone on SQLite and DuckDB, which keep É and é apart. Two names that differ only in how an accent is written, as é typed as one character or as e plus an accent, are two tables everywhere but on SQL Server, where the database's collation decides: under its usual collations the two spellings are one name, so a key into the one spelling finds a table spelled the other way; under a binary collation they are two tables, as everywhere else. The same collation decides letter case there: a database under a case-sensitive or binary collation keeps Parent and parent apart, so a key into one finds no table spelled the other way, and a copy with Replace existing drops only the table spelled exactly as the copied one. The app reads the collation each time it reads the database's tables. A key into another schema is left out, with a note. On SQLite and DuckDB the key is written into the CREATE; elsewhere it is added after the rows, so the order the tables are copied in cannot matter. Where a copy writes a table with its keys, as one PostgreSQL database to another does, tables copied together are made parents first, each key read the way it spells its table: beside cafe and Cafe, a table with a key to cafe is made after cafe.
A PostgreSQL identity column keeps its ids. The copy is written with OVERRIDING SYSTEM VALUE where the column is GENERATED ALWAYS, and each identity column's sequence in the landed table is moved past the copied ids the way it counts, up or down and within its bounds, so its next row takes a fresh one. A sequence that already stands past the rows, a restart you set by hand included, is left where it is. The copy counts the way the original does: an identity's step, start, bounds, cache and cycle travel in its definition.
A SQL Server IDENTITY column keeps its ids too. The server takes a value for such a column only while the connection says SET IDENTITY_INSERT … ON, for one table at a time, so the copy switches it on for each table while that table's rows land and off after them, on the target connection, whatever becomes of the rows. A copy from SQL Server to SQL Server keeps the column's IDENTITY(seed, increment); a copy to another engine makes it that engine's identity or auto-increment column; and a copy of another engine's identity or auto-increment key into SQL Server makes an IDENTITY(1,1) column, its rows landing under the same switch. The server itself counts on past the copied ids. A table with two identity columns, as PostgreSQL allows, lands on SQL Server, MySQL, MariaDB, Oracle, Db2 or SQLite with one, since those give a table one: the key's column keeps it, the other becomes a plain column holding the copied values, and the sheet says so. MySQL and MariaDB give AUTO_INCREMENT only to the column that leads the primary key, and SQLite counts only the single INTEGER PRIMARY KEY, so a generator on any other column lands plain the same way, and is said the same way.
A text column in the key, or in an index, lands with a length the target can index. A PostgreSQL varchar keeps its own length. Text with no length, such as ClickHouse's String or PostgreSQL's text, gets a length the target's key takes with room for the key's other columns, shared between the text columns of one key, and the sheet says so. A value longer than that will not fit.
Backups: dump and restore
A whole database out to a file, or a file back in, by the engine's own tool — pg_dump and psql, mysqldump and mysql, sqlite3, mongodump and mongorestore — run in a console tab that shows the tool's own output and, at its foot, how far the job has got. Every dump that finishes is listed under Backups, where a double-click restores it, and the file stays where you chose to write it.
Dump Database: the file and the scope; Dump runs pg_dump in a console tab.
Backups: every dump that finished, where you wrote it; double-click one to restore it.
How to
Right-click a connection and choose Dump Database…, or on MySQL and MariaDB right-click the database itself. In the sheet, pick Structure and data, Structure only or Data only, and the file. Click Dump.
A tab named for the dump opens with the tool running in it. While it runs, the line at the tab's foot says how far it has got — how much a dump has written so far, or how far a restore has read its file, with a bar — and the tab's chip spins. When the tool ends, the tab's last line slides in with a green check and says the file is done, and Show in Finder finds it; a red warning sign says it didn't. The tab's chip wears the same mark, so a job left running in another tab tells you when it is done, and if DBClient is in the background its Dock icon bounces once.
Right-click the connection and choose Backups…, click the Backups folder under the connection (it appears beside Users & Roles once a dump has finished) or the Backups card on the connection's page, or type backups into ⌘K — for the list: every dump that finished, newest first, each row the file with what it holds, its size and when it was made (hover over a row for the folder it is in). Double-click a row, or right-click it and choose Restore…, to read it back: the Restore sheet opens with the file filled in, and on MySQL and MariaDB you can still point it at another database first. Right-click a row for Show in Finder, Remove from List (the row goes, the file stays) and Move to Trash… (the file goes to the Trash, where you can put it back, and the row goes with it); ⌫ on the highlighted rows asks the same.
Restore Database… — at the top of the Backups list beside Dump Database…, and on the connection menu — takes any dump file, listed or not, and runs the engine's client over it in a tab of its own. The file's statements run as they are, and every change they make stays. When the restore ends, the sidebar reads the database again, so what it brought in is in the tree without a Refresh.
Technical notes
PostgreSQL, MySQL, MariaDB, SQLite and MongoDB: the engines whose own tools dump and restore from a file on a Mac. SQL Server, Oracle, Db2 and ClickHouse back up on the server, with their own statements.
The tool is found the way the console's client is — the same folders, the same Homebrew package: brew install libpq brings pg_dump with psql, brew install mysql-client mysqldump with mysql, and every Mac has sqlite3. MongoDB's tools come in their own package from MongoDB's tap: brew tap mongodb/brew, brew trust mongodb/brew, brew install mongodb-database-tools. Without the tool, the door explains, with the lines to paste.
MongoDB: mongodump writes the connection's database to one archive file, whole — there is no structure or data choice — and mongorestore reads it back with --drop, replacing each collection the archive holds; the password is typed at the tool's own prompt, never put on the command line.
The tool dials with the connection's own host, port, user, database and TLS choice, through its SSH tunnel or proxy, and takes the password the way the client does — from its environment, never on the command line. The file goes on the tool's own option (--file, --result-file, .output): no shell stands between.
pg_dump writes plain SQL, verbosely, with DROP … IF EXISTS before every object in structure and full dumps, so restoring over a database that still holds everything replaces it rather than colliding with it. psql reads the file back in one transaction and stops at the first error: a restore lands whole or leaves the database as it was, and the tab says which. mysqldump runs with --single-transaction --no-tablespaces --verbose --routines --events --triggers (--verbose has it name each table as it goes, in the tab — left quiet, it prints nothing until it ends; events need the account to hold the EVENT privilege, as mysqldump requires; tablespaces are the server's, not the database's, and reading them needs the PROCESS privilege most accounts lack — asked for them, mysqldump prints an error and still exits 0) and adds its own DROP TABLE IF EXISTS; mysql reads the file on its standard input, the way mysql < file does, and stops at the first error with exit code 1 (a source inside --execute carries on past errors and exits 0 with MariaDB's client); an error line the client prints counts as a failure all the same. sqlite3 runs .dump, .schema or .dump --data-only, and .read with -bail: its dumps carry no drops, so a restore over a file that still holds the objects stops at the first one and says so — restore into an empty file, or drop the objects first.
A PostgreSQL dump is of the database it was started from: the database whose row's menu or page you used, or the one the tab in front is in. A connection saved without a database name starts in the one the server put it on.
The line at a job's foot is the app's own reading, the same on every engine, twice a second: a dump's is the size of the file the tool is writing — there is no percentage, since nobody knows how big the file will end up — and a restore's is how far the tool has read its file, against the file's size, read from the file the tool holds open.
PostgreSQL: a dump is the whole database, every schema in it — the schema row you are on plays no part. pg_dump names every object by its schema, so a restore puts each one back into the schema it came from; neither pg_dump nor psql can point a dump at another schema, and the sheet says so. To copy tables from one schema into another, drag them onto the schema in the sidebar (copy objects).
A dump is written beside its file, as name.sql.3f9a2c.part with a tag of its own for each dump, so two dumps to one file never share a part-file, and takes the file's name only when the tool ends with exit code 0 without reporting an error and the file ends with the tool's own closing line: pg_dump's -- PostgreSQL database dump complete, mysqldump's -- Dump completed on with its date, sqlite3's COMMIT; after a full dump. A file that stops before that line is not whole, whatever the tool said, and is discarded. (MongoDB's archive and sqlite3's structure-only and data-only output have no such line; there the exit code stands alone.) A dump that fails or is stopped leaves nothing behind: the part-file is removed, a backup already at that path is untouched, and the tab says nothing was written. A tool that prints an error line of its own (mysqldump: Error: …) yet exits 0 counts as failed all the same.
Homebrew's mariadb formula installs its tools as mysqldump and mysql too. MariaDB's dump tool cannot read a MySQL server's routines: a MySQL database without any is dumped whole with it, and one with routines is refused before anything is written — the tab names brew install mysql-client, which gives MySQL its own tools and which the app prefers once they are there. A data-only dump never needs them.
The list is kept in ~/Library/Application Support/DBClient/backups.json: each dump's path, size and date, its scope and its database — never the dump itself, which is yours to keep, move or delete. Only a dump whose tool ended with exit code 0 is listed; a dump over a listed file replaces its row. A file moved or deleted outside the app keeps its row, marked missing, until you remove it. Move to Trash… is the one thing here that touches a file, and it only ever moves it to the Trash — never straight to nothing; a file whose volume has no Trash is left where it is, and the app says so. There are no schedules: the app backs up when you ask, and nothing runs while it is closed.
Specifications
The numbers and the fine print: what the app needs, what it keeps, what it talks to, and every key it answers to.
System requirements
macOS
26 Tahoe or newer. Version 0.3.8 was the last release for macOS 15 Sequoia.
Mac
Apple silicon, M1 and later. There is no Intel build: the SQL Server driver's library ships for Apple silicon only.
Distribution
A disk image signed with a Developer ID certificate under the hardened runtime, notarized and stapled; or the Homebrew cask az-code-lab/taps/dbclient.
Account
None. The app never asks you to sign in.
Download
About 25 MB. Oracle's client adds about 140 MB and IBM's about 20 MB, only if you use those engines.
Built into the app: DuckDB 1.1.3, FreeTDS 1.5 for SQL Server, OpenSSL 4, and Ghostty's terminal for consoles. SSH and SQLite are provided by macOS.
Limits and defaults
What
Value
Rows in one result
5,000; 10,000 on SQL Server, Oracle, IBM Db2 and Databricks; 1,000 documents on MongoDB. A single SELECT is paged, so all of it can be reached.
Rows per page
100, 200, 500, 1,000, 2,000 or 5,000. Starts at 1,000.
Watch interval
1, 2, 5, 10 or 30 seconds, 1 or 5 minutes. Starts at 5 seconds.
Keepalive
A ping every 15 seconds, with 10 seconds to answer. On the socket, for PostgreSQL, MySQL, MariaDB, Redis and the connection to a proxy: a probe after 15 seconds of silence, then every 5 seconds, three misses; bytes unacknowledged for 30 seconds.
Tunnel and proxy connect
10 seconds.
PostgreSQL, MySQL, MariaDB, Redis and ClickHouse connect
10 seconds, the sign-in included. A port that refuses fails at once. A ClickHouse Cloud service, which may be asleep, gets 2 minutes.
Statement timeouts
Oracle and IBM Db2: 60 seconds unless you change it on the connection. ClickHouse requests: 300 seconds. Databricks requests: 60 seconds.
Foreign-key picker
The first 500 rows of the referenced table, in key order; other keys can be typed.
CSV import and table copy
INSERTs of 250 rows; a copy reads 1,000 rows at a time.
Charts
8 series, 50 categories, 4,000 points, 6 pie slices and Other.
Assistant
Sees at most 50 rows of a query it ran, and 2,000 characters of your editor.
Script files
A .sql file of up to 16 MB opens in the editor.
Window zoom
80% to 200%, in eight steps.
Where things are stored
Everything stays on your Mac. There is no cloud account behind the app, so there is nothing to sync and nothing to leak from a server of ours.
What
Where
Connections and folders
~/Library/Application Support/DBClient/connections.json — names, hosts, ports, users and options. Never a password. A file that cannot be read, or whose folder cannot be opened, is reported when the app opens and kept as it is: nothing is saved over it until it reads. A damaged one is set aside under a .corrupt- name beside it, and the list starts empty. The saved queries, the query history and the backups list are kept the same way.
~/Library/Application Support/DBClient/query-history.json — the statements you ran, as typed. Settings ▸ Browsing clears it.
Backups
~/Library/Application Support/DBClient/backups.json — where each dump went, its size and its date. Never the dump itself.
SSH servers you trusted
~/.ssh/known_hosts, the file ssh uses in Terminal. OpenSSH adds one line when you click Trust and Connect; DBClient keeps no list of its own.
Oracle and Db2 clients
~/Library/Application Support/DBClient/Oracle and …/Db2, only if you downloaded them.
Passwords and API keys
The macOS Keychain, service dev.azcode.dbclient.connections.
Settings
~/Library/Preferences/dev.azcode.DBClient.plist
If one of these files cannot be written when you change something, an alert names the file. The change stays on screen until the app quits and is gone the next time it opens, so fix the folder and make the change again.
Technical notes
brew uninstall --zap dbclient removes all of these except Keychain items, which macOS leaves to you.
The app has no telemetry, no crash reporter and no analytics. It opens a connection in these cases, and this is the whole list. The privacy page says the same in full sentences.
When
Where
Always
Your own database servers, through the tunnels and proxies you set up.
For updates
raw.githubusercontent.com for the published Homebrew cask, and github.com for the disk image when you install one.
For the license
azcode.dev, the license server: when you register or deregister, about once a day to check the registration, and each time you open Settings ▸ License. A copy that is not registered asks it one thing only — how many Macs a key registers, from the store's public product list, when the license sheet or Settings ▸ License opens — and sends nothing about this Mac, until you ask for a free trial: that sends your name, your email address, this Mac's serial number and the app's version, and the trial key comes back to you by email, never to the app. A copy that had a trial and no longer knows when it ends asks the license server for the day, sending the email address and this Mac's serial number, when the app starts and when Settings ▸ License opens.
Only with an Oracle or Db2 connection
download.oracle.com or public.dhe.ibm.com, when you click Download or Update in Client Setup.
Only with an AI key saved
The provider you chose: api.anthropic.com, api.openai.com, generativelanguage.googleapis.com, api.x.ai, api.deepseek.com or api.mistral.ai.
Only with Local server chosen as the AI provider
The address you typed in Settings ▸ AI: this Mac, for Ollama's or LM Studio's, unless you pointed it elsewhere.
Only with ClickHouse Cloud sign-in
ClickHouse's own sign-in pages, in your browser.
Updates
The app reads the same Homebrew cask that brew upgrade does, so a DMG install and a Homebrew install learn about a release at the same moment.
It checks a minute after the app starts and then about once a day. A check that fails says nothing.
When a newer build exists, an Update button appears in the toolbar, and Settings ▸ General says which version is available. Update & Relaunch, in either place, installs it. Nothing is downloaded without your say.
To check now, open Settings ▸ General and click Check for Updates. An update it finds installs from the same row, which shows the download as it runs and says why if the update is refused. Cancel stops the download and keeps the offer, and Update & Relaunch starts it again at once.
Before the new app replaces the old one, the downloaded disk image's SHA-256 must match the cask's, and the app inside must pass codesign --verify --deep --strict and carry the same Developer ID team.
Each download goes into a folder of its own under the temporary directory and is removed when that attempt ends, so a download that is still stopping never touches the files of one started after it.
Languages, appearance and zoom
Twelve languages: English, Chinese (Simplified and Traditional), Japanese, Korean, German, French, Spanish, Italian, Portuguese (Brazil), Russian and Indonesian. The app follows macOS; Settings ▸ General ▸ Language picks another, from the next launch.
Appearance: light or dark, following macOS.
Zoom:⌘+ and ⌘− scale the whole window, text and controls together; ⌘0 returns to actual size.
Keyboard shortcuts
Keys
What it does
⌘↩
Run the statement under the cursor, or the selection
⇧⌘↩
Run everything in the tab, or the selection
⌘.
Stop the running query, and any watch
⌘R
Run the last statement again; in a Users & Roles tab, read the accounts again; in a Files tab, read the folder again; with the sidebar focused, read the highlighted connection's tree again (never connects)
⇧⌘E
Explain the statement under the cursor
⇧⌘F
Format the SQL, or the selection
⌘/
Comment or uncomment lines
⌘D · ⇧⌘D
Delete the line · duplicate the line
⌘F
Find in the editor or the pane in front; in a listing or a diagram, the filter
⌘A · ⌫
In a listing: select every row · drop the selected objects (asks first)
⌘C
In the results grid: copy the highlighted cell, cells, rows or columns, tab-separated; the copied cells flash for a moment
↑↓←→
In the results grid: move the selected cell one step; the grid scrolls to keep it in view
⇧↑⇧↓ · ⇧←⇧→
In the results grid: select rows · select cells along the row, from the selected cell outward, one more with each press
⌘↑⌘↓ · ⌘←⌘→
In the results grid: jump to the first or last row · the first or last column
Home · End
In the results grid: the row's first · last column; with ⌘, the first · last row
Page Up · Page Down
In the results grid: move the selected cell a page up · down
⇧ with any of the three above
In the results grid: select from the selected cell all the way to there, the cells of its row sideways, whole rows up and down
↩
In the results grid: edit the selected cell; in the editor, keep the change (the cell stays selected)
esc
In the results grid: clear the selection; in the editor, drop the change (the cell stays selected)
⌘G · ⇧⌘G
Next match · previous match
⌘S
Review and commit pending grid changes; otherwise save the query
⌘L
Show or hide the result log
⌘K
Command palette
⌘T · ⌘W
New query tab · close the tab
⇧⌘T
Reopen the last closed tab
⌃⇥ · ⌃⇧⇥
Next tab · previous tab
⌘1 – ⌘9
Go to a tab by position; ⌘9 is the last
⌥⌘T
Auto-commit on or off
⌥⌘I
Show or hide the inspector
⌥⌘A
Show or hide the AI assistant
⌥⌘S
Show or hide the sidebar
⌘O
Open a database file or a script
⌘+ · ⌘− · ⌘0
Zoom in · zoom out · actual size
⌘,
Settings
Licenses and the free trial
DBClient needs a registered copy to connect: a free month's trial, asked for in the app, or a bought license. Prices are on the pricing page, and so is the form that buys one.
A license key registers up to … Macs at once. A Team & Business order starts at five.
A license runs for a year, upgrades and support included. From 30 days before it ends, the window's toolbar says how many days are left. When the year ends, the toolbar says so and connections stop until the license is renewed; nothing you saved is touched.
Renewing is done on the renew page, with the license key and the email address it was issued to; there is no sign-in. The term is added to the end of the one you have, or starts today for a license that has lapsed, and the key stays the same.
A promo code, if you have one, goes in the field under the email address on the buy form, or under the price on the renew page. Press Apply and the price with it is shown before anything is paid. A percentage code works on both; a code that sets a price or takes an amount off is for buying only. The receipt and the invoice show what it took off.
Buying is paid through Stripe, PayPal or Square. The keys are shown as soon as the payment is through and mailed to you with a receipt and an invoice; they are kept at azcode.dev too, where your purchase email signs you in without a password.
A free trial is a month of the whole app, asked for in the app with your name and email address. The trial key is emailed to that address and never shown in the app; entering it in the app puts the one Mac you enter it on onto the trial, and confirms the address is yours; one trial per email address and per Mac. A mistyped address costs nothing: ask again with the right one. When it ends, the app stops connecting until a license is bought; nothing you saved is touched.
How to
Open Settings ▸ License. Enter the email address the license was issued to and one of its keys, and press Register. The pane then says to whom the copy is registered and until when. Each time the pane opens it asks the license server for the registration as it stands, so a renewal shows at once; if the server cannot be reached, the pane shows what it last knew. From 30 days before the license ends, the window's toolbar counts the days down, and clicking it opens this pane. When the license has ended, the toolbar says so, and the pane names the day and offers Renew…; once renewed, press Register to put this Mac back on the key.
To make room on the key, press Deregister This Mac on a Mac you no longer need it on, or release a Mac that is gone under My Licenses at our store. Once the key is full, another Mac is refused until you do.To move the key to another Mac, press Deregister This Mac here first — or simply register on the other Mac with the same email and key, and the key moves over; this Mac goes back to unregistered at its next check.
An unregistered copy that is asked to connect says so, and offers Enter License…, Buy a License… and Free Trial…. A new connection can still be filed with Add Anyway.
No license yet? In the same pane, enter your name and your email address and press Start Free Trial: a trial key is emailed to that address. Enter it under License Key, with the same email address, and press Register; this Mac is then on the trial for a month. Until the key is entered, the pane says where it went and the toolbar says the trial is not registered; no email? Check the spam folder, or press Start Free Trial again to have it sent again. On the trial, the pane says so, and Trial Ends names the day and how many days are left; the window's toolbar says the days left too, and clicking it opens the pane. When the trial has ended, both say so, and the pane names the day it ended. The pane offers Buy a License… for when it ends.
Technical notes
Registering sends the email address, the key, this Mac's serial number, the app's version and the macOS version to the license server, which binds the key to that serial number. A registered copy asks the server about once a day whether the registration still holds, and again each time Settings ▸ License opens, without the key. Only a definitive "no" ends it — the key was moved, withdrawn, or its term ran out. Being offline never does.
A copy that is not registered asks the license server for nothing but the store's public product list, to say how many Macs a key holds at once — the same list the pricing page reads, with nothing about this Mac sent along; the number is not written into the app. If the store cannot be reached, the pane sends you to the pricing page for it. A connection already open when a registration ends is left alone; the next remote connect is turned down.
Asking for a free trial sends the name, the email address, this Mac's serial number, the app's name and the app's version to the license server, which issues a key bound to that address, for one Mac and a calendar month, and emails it. The answer to the app carries the trial's terms and never the key, so entering the key proves the address is yours. The app then takes the key through the same steps as a bought one, so the daily check, Deregister This Mac and the end of the term work the same way. The server gives one trial per email address and one per Mac, for good once the key has registered a Mac: asking again is refused, and the refusal says which of the two already had one, or the day the trial ended. A trial whose key never registered a Mac — a mistyped address, say — is replaced by the next request for that address or from that Mac. The same address asking again from the same Mac has the key emailed again, a few times an hour at most. A copy that had a trial and no longer knows the day it ended asks the server for it on its own, with the email address and the serial number, when the app starts and when Settings ▸ License opens.
The registration is kept in the app's preferences, not the Keychain. There is still no account and no sign-in.
How DBClient is tested
A database client that gets a statement wrong can cost someone their data, so nearly everything in the app is pinned by a test that runs before every release.
More than four thousand unit tests cover the parts that decide what SQL is sent: the statement splitter, the editability rules, the ALTER planner for each engine, type translation between engines, the assistant's read-only guard.
End-to-end stages launch the real app and drive its windows the way a person does — clicks, drags, typing — then read the result back off the screen.
Both run against real servers in Docker: PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, IBM Db2, MongoDB, Redis, ClickHouse, TimescaleDB, CockroachDB, YugabyteDB and Valkey, plus an SSH server and a proxy for the tunnels.
A compiler warning fails the build, and every runner fails on any warning left in its build log — the linker's, a package's, a tool's — so none can sit there unread.
This website has its own checks: every link and every guide on it must resolve, and every page is loaded in a browser in both appearances.