From first connection
to final commit.

Getting started

Download a release for macOS, Linux, or Windows (beta), or build from source. On macOS, use brew install --cask wess/packages/tables. All downloads →

cargo run -p appCopy

Create a connection

1. Select New connection.
2. Choose PostgreSQL, MySQL, or SQLite.
3. Enter server details or a SQLite path.
4. Select Test, verify the version, then save.

Connections

Server connections use host, port, database, username, and password. SQLite uses a local file. Names, colors, groups, and tags distinguish environments.

SSH and safe modes

SSH tunnels use the system ssh command; key or agent authentication must already work. Safe modes are useful guardrails, but database permissions remain the real production boundary.

Data grid

Rows page, sort, and filter on the server. Resize columns, inspect complete values, and stage inline edits and deletes for SQL review.

Table tabs share the titlebar and keep their page, filters, selection, and staged edits. Data/Structure and action icons sit in the row below. Hover icons for labels. Pending changes have a separate review strip.

Move data

Import CSV or TSV and export CSV, JSON, or SQL. Table exports stream to a temporary file and replace the destination only after success. Query exports contain the bounded results already returned. Imports remain sequential; use engine-native bulk loaders for large imports.

SQL editor

Press ⌘↵ to run SQL. Multiple statements produce independent results. Use the toolbar to open history, favorites, explain, transaction execution, charts, export, and Markdown copy. Read results are limited to 10,000 rows / 16 MiB.

Schema tools

Inspect columns, types, defaults, indexes, foreign keys, and DDL. Profile columns, compare two connections, or map declared relationships. Generated comparison SQL is a review aid, not a migration system.

Keyboard reference

MCP server

Release packages include tablesmcp, a standalone stdio server. Save a connection in Tables first, then configure your client with its executable path. The desktop app does not need to be open.

{
  "mcpServers": {
    "tables": {
      "command": "/Applications/Tables.app/Contents/MacOS/tablesmcp",
      "args": []
    }
  }
}Copy

On Linux use the installed tablesmcp path; on Windows use tablesmcp.exe. AppImage users can extract usr/bin/tablesmcp or build it separately.

• list_connections lists saved IDs, names, and engines.
• list_tables lists tables and views for a connection.
• table_schema returns columns, indexes, and foreign keys.
• table_rows returns a bounded page, up to 200 rows.

Connections are read-only and skip startup SQL. There is no SQL execution or write tool. Use TABLES_DIR to select a separate connection profile. Full setup, limits, and access details →

Optional assistant

Configure credentials in Settings → Assistant, then open the sparkle icon in the titlebar. Requests include the conversation, schema context, and optionally query results. Credentials use the OS credential store.

Review generated SQL before Run or Insert. Stop, close, clear, or leaving the workspace cancels the active stream. Conversation and stream buffers are bounded.

Updates

Tables checks releases at launch and hourly when enabled. Settings → Updates applies immediately. Use the download icon or Check for Updates to check manually; installation always requires confirmation.

macOS upgrades verify the checksum and signing identity. Linux AppImages verify the checksum. Other installs open the release page; package-manager installs can be updated through their package manager. Windows builds remain beta and unsigned.

Data and privacy

Tables includes no telemetry. Metadata is plain JSON under ~/.tables/; TABLES_DIR relocates it. Connection passwords use the OS credential store when available; they can remain in JSON if credential storage fails. Network traffic includes configured databases and SSH, enabled update checks, and assistant requests you initiate. MCP clients can read data from the saved connections they are given access to.

Troubleshooting

Connection fails

Verify DNS, port, database, credentials, TLS, grants, and firewall. Validate SSH independently in a terminal.

No tables appear

Check the selected database, current schema, and metadata grants.

Stale data

Use Refresh rows after external writes and Refresh tables after schema changes.

Architecture

app / tablesmcp  →  host  →  db  →  model
          ↓       ↓
        store  →  model

Core crates stay gpui-free. UI database requests cross one bridge onto Tokio and return to the gpui thread through a oneshot channel.

Development

cargo build
cargo test
cargo test -p db
cargo clippy --all-targetsCopy

Put pure behavior in the lowest sensible crate and cover missing, corrupt, null, quoting, and engine-specific cases.