How DBClient works.

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

1. Download DBClient.dmg, open it and drag the app to Applications. There is no "unidentified developer" step: the build is notarized by Apple.
2. Or install it with Homebrew: brew tap az-code-lab/taps && brew install --cask dbclient. Later releases arrive with brew upgrade, or through the app.
3. To check what you downloaded, run spctl -a -vv /Applications/DBClient.app. The answer names the Developer ID and says accepted.
4. To remove it, delete the app, or run brew uninstall --zap dbclient to remove its files as well.

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, or fill in the fields.

How to

1. Click Add Connection under the sidebar, or press ⌘K and choose Add Connection…
2. Pick the engine or the hosted service. A service tile sets the port and the SSL mode that service expects.
3. 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.
4. Leave Save Password off to be asked each time you connect, or turn it on to keep the password in your Keychain.
5. 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.
6. Click the connection in the sidebar to connect. Click a database to see its overview, a table to browse its rows, or press ⌘T for a query tab.

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.

• Sidebar. Folders of connections; under a connection its databases and schemas; 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 database and schema pickers, Run, Explain, Watch, Auto-Commit, Inspector, AI Assist and Commands.
• Status bar. The connection's state, what the last run returned, the pager, and any pending changes with Discard and Commit…

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.

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.

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.

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.

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

1. Paste a string such as postgresql://user@host:5432/database, sqlite:///path/to/database.sqlite or duckdb:///path/to/file.duckdb.
2. If the string carries a password, Save Password turns itself on. Turn it off again to keep nothing.
3. 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.

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.

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 use saved passwords asks for Touch ID or your login password before a saved password is used. It is on by default.

SSL modes

Three modes, named for what they check.

SSH tunnels and proxies

Reach a database that only a bastion host can see, or one behind a corporate proxy. The tunnel runs inside the app; there is no ssh process to start first.

How to

1. On the SSH Tunnel page, turn on Connect through an SSH tunnel and fill in SSH Host, SSH Port and SSH User.
2. Choose Password or Private Key, and for a key click Choose Key… The panel opens in ~/.ssh.
3. Pick a Host Key policy: Accept New Hosts records a host's key the first time and trusts it after; Require Known Host connects only to hosts already in known_hosts; Accept Any (insecure) checks nothing.
4. 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.

Production mode and connection colours

Two switches on the editor's Options page make a dangerous server hard to mistake for a safe one.

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.

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

• A SQLite or DuckDB file becomes a saved connection named after the file. 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.
• An exported connections file opens the import sheet.
• A CSV, TSV, Parquet or JSON file is opened from the New Connection picker's Data File tile, with Choose…

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

1. In the connection editor, click Oracle Client Setup… or Db2 Client Setup…
2. Click Download. Oracle's Instant Client is about 140 MB, IBM's CLI driver about 20 MB.
3. The same sheet later offers Update, Remove…, Show in Finder, and Check Oracle for Updates or Check IBM for Updates.

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.
• Anything else is not run again. 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.
• If a transaction was open, the server rolled it back, and the message says that too.

Export and import connections

Move your set-up to another Mac, or hand a colleague the connections for a project, as one readable file.

How to

1. Choose File ▸ Export Connections…, or right-click a connection and choose Export… to start with just that one.
2. 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.
3. On the other Mac, choose File ▸ Import Connections…, or open the file. Each connection gets a choice: Add, Replace, Keep Both or Skip.

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…
• 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…, Edit Table…, Import CSV…, Copy to Database…, Truncate… and Drop…

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.

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.
• ⌘. stops a running query. ⌘R runs the last one again.
• Completion opens by itself after two typed characters; esc opens it at once. ↑ ↓ move, ↩ or ⇥ accepts.
• ⇧⌘F formats the SQL, or only the selection. ⌘/ 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.

Results, pages and the row cap

Each statement gets its own result: a grid when rows came back, the server's own completion line when none did. Results appear as each statement finishes.

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 and how long it took; click one to read its SQL, and the server's error if it failed.
• 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.
• To sort, right-click a column header: Sort Ascending, Sort Descending, Clear Sort. Sorting a second column adds it to the first, and the headers then show the order as ↑1, ↓2.
• ⌘L shows the result log under the grid: what ran, when, and what the server said.

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

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.

How to

1. Click Auto-Commit in the toolbar, or press ⌥⌘T, to switch it off.
2. Run your changes. A dialog asks Commit changes to “connection”? with Commit, Roll Back and Not Yet.
3. After Not Yet, the status bar shows uncommitted transaction with Roll Back and Commit until you choose.

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…

How to

1. Press ⌘K and start typing a table's name.
2. Pick Open schema.table to browse it, or DDL: table for its CREATE statement. Typing ddl or diagram narrows to those rows.
3. ↑ ↓ move, ↩ runs the row, esc closes.

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.

How to

1. Click the terminal button in the tab strip, or right-click a connection and choose Open Console.
2. 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.
3. When the client exits, the tab offers Restart.

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

Tabs and the overview

One strip holds the tabs of every connection, grouped in the sidebar's order. Clicking a tab of another connection takes you to that connection.

How to

• ⌘T opens a query tab, ⌘W closes the one in front, ⇧⌘T brings back the last one you closed.
• ⌃⇥ and ⌃⇧⇥ step through tabs; ⌘1 to ⌘8 jump to a tab by position and ⌘9 to the last.
• 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.

Saved queries

A saved query lives in the sidebar beside the database it was written for.

How to

1. Press ⌘S in a query tab. The Save Query sheet suggests a name from the first line.
2. Find it under that database's Queries folder. Click it to open it in a tab.
3. ⌘S in a tab that came from a saved query saves back to it, without asking.

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.

How to

1. Double-click a cell, or right-click it and choose Edit Cell. ↩ keeps the change, esc drops it.
2. 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.
3. Click + in the status bar to add a row. Right-click a row number for Add Row and Delete Row.
4. Changed cells are washed orange, new rows green, rows marked for deletion red and struck through. The status bar counts them: 3 pending.

Review and commit

Pending changes become SQL you can read before it runs, and they run together or not at all.

How to

1. Click Commit… in the status bar, or press ⌘S. Discard throws the pending changes away instead.
2. The Review Changes sheet shows every UPDATE, DELETE and INSERT, between BEGIN and COMMIT.
3. Click Commit. The grid reloads from the server.

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.

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

Export a result

Take the rows in front of you away as CSV, JSON or SQL inserts.

How to

1. Click the export button in the result bar, or select rows and right-click for Export Rows…
2. In Export Result, choose CSV, JSON or SQL Inserts, and All rows or the Selected ones. The sheet previews what will be written.
3. Click Copy for the clipboard or Save… for a file.

Import a CSV

Load a CSV file into an existing table, with each of its columns mapped to the column it belongs in.

How to

1. Right-click a table and choose Import CSV…, then pick the file.
2. In the Import CSV sheet, check First row is header and Empty fields become NULL.
3. Look over the mapping: each CSV column, with a sample value, beside the table column it will fill. Choose another column, or — skip —.
4. Click Import. When it finishes, the table opens.

Show DDL

Read the CREATE statement of anything in the sidebar, rebuilt from the server's catalog.

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

How to

1. 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.
2. Under Columns, edit Name and Type, tick PK and NN, and drag rows to reorder. Select a column for its Collation, Default, Auto-increment and Generated settings. Add Column is under the rows.
3. Switch to Indexes or Foreign Keys for Add Index and Add Foreign Key, with On Delete and On Update rules.
4. Read the SQL Preview. Problems show in red, notes in grey. Click Apply Changes; the designer stays open on the fresh structure.

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.

The database overview

Click a database in the sidebar for a one-page summary: what it holds, what the server is, and a door to everything you can create.

• 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 and Diagram.
• Server has the server-level kinds, the accounts card with New User…, Grant Access… and New Role…, a Console card, and a card to create a database or schema.

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.

How to

1. Open the accounts folder and double-click an account, or click New User…, New Role… or Grant Access…
2. Set the Name, Password, Abilities, Member of and Grants the engine offers.
3. Read the SQL preview, then click Create or Save. Edit as SQL hands you the script in a query tab instead.

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.

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%.
• 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.

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.

How to

1. Click the chart button in the result bar, or press ⌘K and choose Show Result as Chart.
2. Pick the Chart type: bar, line, area, pie or scatter.
3. Pick X, one or more Y columns, a Series column to split by, and an Aggregate: None, Sum, Average, Count, Min or Max.
4. Click the copy button to put the chart on the clipboard as an image.

The AI assistant

Ask about your data in plain words. The assistant sees your schema, can run read-only queries to check its answer, and writes SQL for you to run. It cannot change your data.

How to

1. Open Settings ▸ AI. Choose a Provider — Claude, OpenAI, Gemini, Grok, DeepSeek or Mistral — paste your API key and click Save. The app fetches that provider's models; pick one under Model.
2. Click AI Assist in the toolbar, or press ⌥⌘A, and ask.
3. On a block of SQL in the reply, click Insert into the editor or Copy. You run it yourself.
4. 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.

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.

How to

1. 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. Or right-click it and choose Copy to Database…
2. In the sheet, choose Structure and data, Structure only or Data only, and tick Replace existing if a table of that name is already there.
3. Read the script and any warnings, such as a column type that had to change. Click Copy. Stop ends it early.

System requirements

Limits and defaults

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 the app connects to

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.

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 five minutes after launch and then about once a day. A check that fails says nothing.
• When a newer build exists, the app tells you, and Update & Relaunch installs it. Nothing is downloaded without your say.
• To check now, open Settings ▸ General and click Check for Updates.

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

Licences and local connections

DBClient is free for local connections. Connecting to a server elsewhere needs a licence. Prices are on the pricing page, and so is the form that buys one.

• Local is a database on the Mac you are using: a SQLite or DuckDB file, a data file, or a server listening on localhost, such as a Homebrew PostgreSQL or a Docker container.
• Remote is everything else: another host, a server reached through an SSH tunnel or a proxy, and every hosted service.
• A licence key registers one Mac at a time, and moves to another whenever you like. A Team & Business order starts at five.
• A licence runs for a year, upgrades and support included. When the year ends, remote connections stop until it is renewed; local ones stay free, and nothing you saved is touched.
• Renewing is done on the renew page, with the licence 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 licence that has lapsed, and the key stays the same.
• 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.

How to

1. Open Settings ▸ License. Enter the email address the licence was issued to and one of its keys, and press Register. The pane then says to whom the copy is registered and until when.
2. To move the key to another Mac, press Deregister This Mac there — or simply register on the other Mac with the same email and key, and the key moves over.
3. An unregistered copy that is asked to connect to another machine says so, and offers Enter License… and Buy a License…. A new remote connection can still be filed with Add Anyway.

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 three 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.
• 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.