diff --git a/docs.json b/docs.json index cbb9098..0dac29f 100644 --- a/docs.json +++ b/docs.json @@ -415,6 +415,23 @@ } ] }, + { + "tab": "Linux", + "icon": "linux", + "groups": [ + { + "group": "TablePro for Linux", + "pages": [ + "linux/install", + "linux/connect", + "linux/sql-editor", + "linux/data-grid", + "linux/keyboard-shortcuts", + "linux/troubleshooting" + ] + } + ] + }, { "tab": "Developers", "icon": "code", diff --git a/faq.mdx b/faq.mdx index b7a2ab0..bb767da 100644 --- a/faq.mdx +++ b/faq.mdx @@ -91,8 +91,8 @@ Through iCloud, with a Pro or Team license. Sync is off by default and each cate Yes, for iPhone and iPad on iOS 18 or later. It reads the same CloudKit data as the Mac app but carries connections, groups, and tags only. See [iPhone and iPad](/ios). - -No, macOS and iOS only. A Linux port is a prototype with nothing to install yet, and there is no Windows build at all. Progress is tracked on [GitHub](https://github.com/TableProApp/TablePro). + +Yes, in beta: packages for Ubuntu 26.04 and 26.10 and Fedora 44 and later, and a Flatpak bundle for other distributions. It is a separate app with its own [engines](/linux/connect#engines), and none of the [paid features](/features/licensing) yet. See [Install on Linux](/linux/install). diff --git a/features/licensing.mdx b/features/licensing.mdx index 4b047d9..4347f43 100644 --- a/features/licensing.mdx +++ b/features/licensing.mdx @@ -22,6 +22,10 @@ There are two tiers, Pro and Team. Team includes everything in Pro. Starter was | [Team Catalog](/features/connection-sharing) | Team | Menu item hidden | | [Team Library](/features/team) | Team | Menu item hidden | +The [Linux beta](/linux/install) follows the same licensing model as the Mac. The paid features listed here are Mac-only for now and come to Linux later. + +The activation instructions on this page apply to the Mac. + **Settings > License** lists these features under **Pro Plan** and **Team Plan** and marks each plan your license includes. On a Pro license, **Upgrade Plan** sits beside **Team Plan**. Everything else in the app works. The **Activate License…** dialog also links to the pricing page. A license you already hold never gets that offer: every gate says what the top of **Settings > License** says for its state, so an expired license offers **Renew License**, a suspended one says so, and one that has not reached the server in 30 days offers **Try Again**. diff --git a/images/linux-connect-dialog-dark.png b/images/linux-connect-dialog-dark.png new file mode 100644 index 0000000..7f3a47b Binary files /dev/null and b/images/linux-connect-dialog-dark.png differ diff --git a/images/linux-connect-dialog.png b/images/linux-connect-dialog.png new file mode 100644 index 0000000..8e39c67 Binary files /dev/null and b/images/linux-connect-dialog.png differ diff --git a/images/linux-data-grid-dark.png b/images/linux-data-grid-dark.png new file mode 100644 index 0000000..15e8b12 Binary files /dev/null and b/images/linux-data-grid-dark.png differ diff --git a/images/linux-data-grid.png b/images/linux-data-grid.png new file mode 100644 index 0000000..5bf082e Binary files /dev/null and b/images/linux-data-grid.png differ diff --git a/images/linux-shortcuts-dialog-dark.png b/images/linux-shortcuts-dialog-dark.png new file mode 100644 index 0000000..ff4ad8e Binary files /dev/null and b/images/linux-shortcuts-dialog-dark.png differ diff --git a/images/linux-shortcuts-dialog.png b/images/linux-shortcuts-dialog.png new file mode 100644 index 0000000..16eb46d Binary files /dev/null and b/images/linux-shortcuts-dialog.png differ diff --git a/images/linux-sql-editor-dark.png b/images/linux-sql-editor-dark.png new file mode 100644 index 0000000..1d59a58 Binary files /dev/null and b/images/linux-sql-editor-dark.png differ diff --git a/images/linux-sql-editor.png b/images/linux-sql-editor.png new file mode 100644 index 0000000..31de58c Binary files /dev/null and b/images/linux-sql-editor.png differ diff --git a/index.mdx b/index.mdx index be3e258..7c6f530 100644 --- a/index.mdx +++ b/index.mdx @@ -1,11 +1,11 @@ --- title: Introduction -description: Native macOS database client for MySQL, PostgreSQL, SQLite, MongoDB, Redis, and 42 more +description: Native database apps for Mac, iPhone, iPad and Linux (beta) --- import DriverCounts from "/snippets/driver-counts.mdx"; -Every engine, the SQL editor, the data grid, import, export, and the AI assistant cost nothing, and there is no trial countdown. Paid tiers cover iCloud sync, encrypted connection export, environment variables in connection fields, Linked Folders, Query Insights, result charts, and team sharing ([Licensing](/features/licensing)). Mac is the full app, [iPhone and iPad](/ios) run a smaller one, and there is no Windows or Linux build. +Every engine, the SQL editor, the data grid, import, export, and the AI assistant cost nothing, and there is no trial countdown. Paid tiers cover iCloud sync, encrypted connection export, environment variables in connection fields, Linked Folders, Query Insights, result charts, and team sharing ([Licensing](/features/licensing)). Use the Mac app, the [iPhone and iPad app](/ios), or the [Linux beta](/linux/install). Paid features are Mac-only for now. TablePro main interface diff --git a/linux/connect.mdx b/linux/connect.mdx new file mode 100644 index 0000000..d057613 --- /dev/null +++ b/linux/connect.mdx @@ -0,0 +1,144 @@ +--- +title: Connect +description: The engines, the connect dialog, TLS, SSH tunnels and SQLite or DuckDB files in TablePro for Linux +tag: "Beta" +--- + +A window holds several connection sessions and their tabs. The selected tab decides the active connection for window actions, banners and the assistant. Check its connection and database labels before running a query or changing data. + +Opening a connection that is already open brings its window and session forward. **New Window** (`Ctrl+Shift+N`) starts another with the connection list. **Open Database…** on a connection's sidebar row opens another database as a session in the same window. + + + The connect dialog with Connection, Authentication, Security, SSH Tunnel and Options groups for a PostgreSQL server + The connect dialog with Connection, Authentication, Security, SSH Tunnel and Options groups for a PostgreSQL server + + +## Engines + +Every driver is compiled into the app. Pick the one in **Driver**: + +| Engine | Driver | Default port | +|---|---|---| +| PostgreSQL | **PostgreSQL** | 5432 | +| MySQL and MariaDB | **MySQL** | 3306 | +| SQL Server | **SQL Server** | 1433 | +| ClickHouse | **ClickHouse** | 8123 | +| Cassandra and ScyllaDB | **Cassandra / ScyllaDB** | 9042 | +| Redis | **Redis** | 6379 | +| MongoDB | **MongoDB** | 27017 | +| SQLite | **SQLite** | No port: a file | +| DuckDB | **DuckDB** | No port: a file | + +The server releases each engine is tested against, and the ones it does not support, are in the app's [supported servers](https://github.com/TableProApp/TablePro/blob/main/linux/README.md#supported-servers) table. + +Redshift, CockroachDB, TiDB, OceanBase and Databend are untested on Linux. Support through the PostgreSQL or MySQL drivers on Mac does not establish Linux compatibility. + +## Limits + +- Binary, array, spatial, composite and variant cells are read-only. Inspect or copy them in the grid; use a query to change them. +- Enter time and timestamp values as text, such as `13:45:00` or `2026-11-05 13:45:00`. Include an offset for types that store one. Invalid values stay in the editor with an error; correct them before saving. +- Redis Cluster and Sentinel are unsupported. Connect to a standalone Redis server instead. + +## Add a connection + + + + Click **Add Connection** in an empty connection list, or choose **New Connection…** from the main menu. + + + Pick the **Driver**, then fill **Host** and **Database**. **Port** starts on the engine's default. + + + Fill **Username** and **Password**. With **Remember Password** on, the password goes to [secret storage](/linux/troubleshooting#passwords); with it off, every connect asks for it. + + + **Test** connects once to check the settings, then disconnects. **Connect** saves the connection and adds its session to the window. + + + +For a MongoDB replica set or cluster behind a `mongodb+srv://` address, turn on **DNS Seed List**. **Authentication Database (optional)** names the database that holds the user. + +## Options + +| Row | Sets | +|---|---| +| **Safe Mode** | What is asked before a write. See the next table | +| **External Clients** | What MCP clients may do on the connection: **Blocked**, **Read Only** (the default) or **Read & Write** | +| **AI Assistant** | Whether the assistant may send anything from the connection: **Ask Each Time** (the default), **Allow** or **Never** | +| **Custom Query Timeout** | An editor timeout for this connection in place of the one in Preferences. 0 turns it off | + +Safe Mode is also in the main menu while connected, and a change there is saved to the connection. + +| Safe Mode | Does | +|---|---| +| **Off**, the default | Asks only before DROP, TRUNCATE, and DELETE or UPDATE without WHERE | +| **Confirm Writes** | Asks before every statement that changes the database, showing the SQL and the connection | +| **Read-Only** | Opens the connection read-only, and refuses every editor statement that does not read | + +Pick **Read-Only** for a production server you only read. Moving to or from it reconnects that connection's sessions. + +## TLS + +**Encryption** under **Security** picks the mode: + +| Mode | Connection | +|---|---| +| **Disable** | Plain, no TLS | +| **Require** | Encrypted. The server certificate is not checked | +| **Verify full**, the default | Encrypted. The certificate must be valid for the server name | +| **Strict** | SQL Server only. TLS before the login, as TDS 8.0 needs. SQL Server 2022 or later on Windows, 2025 or later on Linux | + +Keep **Verify full** unless the server has no certificate this computer can check. For a server signed by your own certificate authority, choose its PEM file in **CA certificate** rather than dropping to **Require**. + +- **Client certificate** and **Client key** log in with a certificate, on every network engine but SQL Server. +- **TLS server name** checks the certificate against another name than the host. MySQL and MongoDB take it only through an SSH tunnel. +- A failed handshake says what went wrong. An unknown issuer takes you to **CA certificate**, a name mismatch to **TLS server name**. + +## SSH tunnels + +Turn on **Use SSH Tunnel** and fill **Host or alias**. Native packages run the system `ssh` client, so empty rows come from `~/.ssh/config`, and `known_hosts` and your SSH agent apply as they do in a terminal. For the bundle, check [Flatpak connections](#flatpak-connections). + +| Authentication | Uses | +|---|---| +| **SSH agent** | Keys from the SSH agent and your SSH configuration | +| **Private key** | A key file, unlocked with **Passphrase** if it has one | +| **Password** | The SSH server's own password | +| **Keyboard-interactive** | The SSH server's own questions, such as a one-time code | + +Use **SSH agent** by default. Choose **Private key** for a specific key file, or **Password** or **Keyboard-interactive** when the server requires it. + +**Jump hosts** takes what `ssh -J` takes: `user@host:port`, several separated by commas. + +An unknown or changed host key shows its SHA256 fingerprint before anything connects, even where `ssh_config` says `StrictHostKeyChecking accept-new` or `no`. [Troubleshooting](/linux/troubleshooting#ssh-tunnels) covers a changed or revoked key. + +## SQLite and DuckDB files + +With **SQLite** or **DuckDB** picked, **Database file** replaces the server rows. **Choose…** opens an existing file, and **New Database…** creates the file when you connect. + +A file also opens straight from Files, through **Open With** on a SQLite database, or from a terminal: + +```bash +tablepro app.sqlite3 sales.duckdb +``` + +The file's own header picks the engine, whatever its name. Each file opens as a session. A file on a network or FUSE filesystem asks whether to open it read-only first, because neither engine's locking holds there. + +## SQL Server with Kerberos + +Set **Method** to **Windows (Kerberos)**. There is no username or password: the driver uses the ticket `klist` shows, so get one first. + +```bash +kinit you@EXAMPLE.COM +``` + +The driver asks for `MSSQLSvc/:` from the host and port you typed. Native packages use the default realm of the host's `/etc/krb5.conf`. Type the host name the SPN is registered for, not an IP address or a CNAME. A server in another realm works only when your KDC answers with a referral, as Active Directory does inside a forest. + +## Flatpak connections + +The bundle runs inside a sandbox. Check these differences before copying a native connection setup: + +- Secrets use the Secret portal and an encrypted file inside the sandbox. Follow [keyring recovery](/linux/troubleshooting#passwords) if a password, MCP token or AI key cannot be stored. +- Kerberos uses the host's KCM ticket cache. The sandbox selects `/app/etc/krb5.conf`, with DNS realm and KDC lookup, instead of the host's `/etc/krb5.conf`. Obtain a ticket in KCM on the host; a file-backed ticket cache is not enough. +- SSH reads `~/.ssh/config`, keys and `known_hosts`, but not the host's `/etc/ssh` configuration. `ProxyCommand` and `Match exec` cannot run host-only helpers. Use a setup supported inside the sandbox or install a native package. +- File-backed FIDO keys cannot sign inside the sandbox. Load the key into the host SSH agent and choose **SSH agent**. +- A CA installed only on the host is absent from the runtime's trust store. Select its PEM file in **CA certificate** and keep **Verify full**. diff --git a/linux/data-grid.mdx b/linux/data-grid.mdx new file mode 100644 index 0000000..42c2606 --- /dev/null +++ b/linux/data-grid.mdx @@ -0,0 +1,68 @@ +--- +title: Data grid +description: Page through a table, filter and sort it on the server, edit rows and save them together in TablePro for Linux +tag: "Beta" +--- + +A table opened from the sidebar fills a table tab one page at a time, 1,000 rows by default. The bottom bar switches the tab between 100 and 10,000 rows per page, and **Preferences > General > Default page size** sets where new tabs start. + + + A table tab with a filter rule above the grid, one modified cell, one new row and the pending changes bar with Discard and Save + A table tab with a filter rule above the grid, one modified cell, one new row and the pending changes bar with Discard and Save + + +## Pages and row counts + +`Alt+Page Down` and `Alt+Page Up` move between pages. A table of about 100,000 rows or fewer is counted on its own; a larger one shows an estimate and offers **Count Rows** for the exact number. + +A MongoDB collection opens in a table tab too: its top-level fields are the columns, `_id` first, and nested documents and arrays show as JSON. + +## Sort and filter + +Click a column header to sort by it, one column at a time. In a table tab the server sorts the whole table; in query results the grid sorts the rows it holds. A Cassandra or ScyllaDB table keeps the server's order. + +`Ctrl+F`, or **Filter Rows**, opens the filter bar over the grid: + +- Each rule is a column, an operator and a value. **Match** chooses whether any or all of them have to hold. +- In place of rules, type a WHERE fragment such as `created_at > now() - interval '1 day'`. It is checked as one expression before it runs. On MongoDB it is a query document instead. +- **Filter by Value** and **Exclude Value** in a cell's menu add a rule from that cell. +- On Cassandra and ScyllaDB the filter offers only the operators the server evaluates, all of them matched, with `ALLOW FILTERING`. + +A table's filter is kept, and so is each tab's across a restart. + +## Edit rows + +Editing works in a table tab on a table with a primary key. Rows a query returns in the SQL editor are read-only, and so are key, generated and auto-increment columns. Check the [cell type limits](/linux/connect#limits) before editing other columns. + +| To | Press | +|---|---| +| Edit the focused cell | `F2` or `Enter` | +| Toggle a boolean cell | `Space` | +| Set the cell to NULL | `Ctrl+Backspace` | +| Insert a row | `Ctrl+N` | +| Mark the selected rows for deletion | `Delete` | +| Edit a long value, or the whole row | `Alt+Enter` for **Row Details** | +| Undo or redo a change | `Ctrl+Z`, `Ctrl+Shift+Z` | + +Dates get a calendar, and JSON is checked before it is kept. A date, time or timestamp cell also takes the engine's own `NOW()`, `CURRENT_TIMESTAMP` and the like, typed in or picked from the cell's menu. + +`Ctrl+V` with tab-separated rows on the clipboard adds them as new rows, filling the columns from the focused one, or by name when the first line holds the headers. More than 1,000 rows asks first, and 100,000 is the most one paste takes. + +## Save or discard + +Every change waits in the pending changes bar. **Save** (`Ctrl+S`) writes them together, in one transaction where the engine has them, and **Discard** drops them. Deleting 10 rows or more asks first, unless **Confirm Before Deleting Rows** is off under **Preferences > General**. + +On ClickHouse, Cassandra and ScyllaDB a save is a series of statements, each landing on its own. **Stop Saving** there takes effect between statements. + +## Copy and export + +`Ctrl+C` copies the focused cell or the selected rows. **Copy As** in the cell's menu writes them as CSV, JSON, JSON Lines, Markdown, a text table or an `IN` clause, and in a table tab as `INSERT` statements. + +**Export Rows…** writes CSV, JSON, Markdown, HTML, XML, Excel or SQL `INSERT` to a file, from the current page with its pending edits or from every saved row under the filter and sort. + +## Columns and foreign keys + +- `Alt+Left` and `Alt+Right` move the focused column, and `Shift+Alt+Left` and `Shift+Alt+Right` narrow and widen it. Dragging a header moves the column, and dragging its edge resizes it. +- **Columns…** hides and shows columns. **Reset Columns** there goes back to the table's own order. +- Order, hidden columns and widths are kept per table. +- `Ctrl+J` on a foreign key cell opens the row it points at in a new tab. **Show Referencing Rows** on a saved row opens the rows that point at it. diff --git a/linux/install.mdx b/linux/install.mdx new file mode 100644 index 0000000..a483a16 --- /dev/null +++ b/linux/install.mdx @@ -0,0 +1,184 @@ +--- +title: Install on Linux +description: Ubuntu and Fedora packages from the beta and stable repositories, and the .deb, .rpm and Flatpak bundle on GitHub Releases +tag: "Beta" +--- + +The Linux app is in beta: only `0.1.0-beta.N` builds exist until 0.1.0 ships. It runs on amd64 and arm64, as an app of its own beside the Mac one, with the engines on [Connect](/linux/connect). + +Use the repository for your distribution: apt or dnf then installs every update, and so do Software Updater and GNOME Software. Take a file from GitHub Releases for another distribution, through the Flatpak bundle, or to try one exact build. + +## Install the beta + +Enable both the stable and beta repositories, then install `tablepro`: + + + +```bash Ubuntu 26.04 and 26.10 +sudo add-apt-repository ppa:tablepro/tablepro +sudo add-apt-repository ppa:tablepro/tablepro-beta +sudo apt install tablepro +``` + +```bash Fedora 44 and later +sudo dnf copr enable @tablepro/tablepro +sudo dnf copr enable @tablepro/tablepro-beta +sudo dnf install tablepro +``` + + + +apt and dnf install the highest version the two hold, so a release replaces its betas and the next beta replaces that release. Without the stable repository, the last beta stays installed until the next beta. + +## Install a stable release + +From 0.1.0 on, the stable repository alone gets releases and no betas: + + + +```bash Ubuntu 26.04 and 26.10 +sudo add-apt-repository ppa:tablepro/tablepro +sudo apt install tablepro +``` + +```bash Fedora 44 and later +sudo dnf copr enable @tablepro/tablepro +sudo dnf install tablepro +``` + + + +To stop testing betas, remove the beta repository. The installed beta stays until the stable repository has a newer version. + + + +```bash Ubuntu +sudo add-apt-repository --remove ppa:tablepro/tablepro-beta +``` + +```bash Fedora +sudo dnf copr disable @tablepro/tablepro-beta +``` + + + +## Packages on GitHub Releases + +Each release and beta on [GitHub Releases](https://github.com/TableProApp/TablePro/releases) carries packages and their `SHA256SUMS`. A beta is a pre-release there. A standalone .deb, .rpm or .flatpak bundle gets no app updates unless you install the next file or enable the PPA or COPR for native packages. + +New Linux betas and their fixes are announced on that releases page. Subscribe to its [Atom feed](https://github.com/TableProApp/TablePro/releases.atom) and filter entries for tags starting with `linux-v`. The feed also includes other platforms. PPA and COPR installs get updates through apt or dnf. + +| File | For | +|---|---| +| `tablepro--ubuntu--.deb` | Ubuntu 26.04 or 26.10, `amd64` or `arm64` | +| `tablepro--fedora--.rpm` | The Fedora release it names, `x86_64` or `aarch64` | +| `tablepro--.flatpak` | Any distribution with Flatpak, `x86_64` or `aarch64` | + +Check the download, then install the file for your system: + +```bash +sha256sum --check --ignore-missing SHA256SUMS +sudo apt install ./tablepro-0.1.0-beta.1-ubuntu-26.04-amd64.deb +sudo dnf install ./tablepro-0.1.0-beta.1-fedora-44-x86_64.rpm +flatpak install --user ./tablepro-0.1.0-beta.1-x86_64.flatpak +``` + +The Flatpak bundle fetches the GNOME 51 runtime from Flathub, and the next bundle installs over it. Flathub does not carry TablePro itself. The bundle keeps its files under `~/.var/app/app.tablepro.TablePro/`; [Troubleshooting](/linux/troubleshooting#where-the-files-are) lists them. + +Other distributions build from source with the [Quickstart](https://github.com/TableProApp/TablePro/blob/main/linux/README.md#quickstart) in the app repository. + +## Move between native packages and Flatpak + +The two formats use different [data folders](/linux/troubleshooting#where-the-files-are) and [secret storage](/linux/troubleshooting#passwords). An empty connection list after switching does not mean the old data was deleted. + + + + Quit the app and [back up its files](/linux/troubleshooting#back-up-saved-work), including query history, saved queries and drafts, before changing formats. + + + Reopen the current installation. Choose **Export Connections…** from the main menu and save the file outside its app data folder. Quit it before starting the other installation. + + + Install the other format and choose **Import Connections…** from its main menu. Select the exported file and review the import. This transfers connection settings, not history, drafts or passwords. + + + Re-enter database and SSH passwords and key passphrases. Set up cloud AI keys and MCP clients again if you use them. Keep the backup until you have checked your connections and saved work. + + + +## Uninstall + +Quit the app first. Package removal keeps your connections, history, drafts, preferences and saved secrets. Use the command for your installation: + + + +```bash Ubuntu +sudo apt remove tablepro +``` + +```bash Fedora +sudo dnf remove tablepro +``` + +```bash Flatpak +flatpak uninstall --user app.tablepro.TablePro +``` + + + +The Flatpak commands here assume the `--user` installation in this guide. Use `--system` for a system-wide installation. For a full reset, follow the optional steps next while the app is still installed. + +## Optional full reset + +Resetting deletes saved work and credentials. [Back up saved work](/linux/troubleshooting#back-up-saved-work) first. The steps affect this desktop account, not your server databases or SQLite and DuckDB files stored elsewhere. + + + + Quit the app. Reset GSettings while the installed package still provides its schema: + + + ```bash Native package + gsettings reset-recursively app.tablepro.TablePro + ``` + ```bash Flatpak + flatpak run --command=gsettings app.tablepro.TablePro reset-recursively app.tablepro.TablePro + ``` + + + + For native packages, remove these folders. The commands respect custom XDG locations and delete connections, history, saved queries, tabs, drafts, snippets and crash reports: + + ```bash + rm -rf -- "${XDG_CONFIG_HOME:-$HOME/.config}/tablepro" \ + "${XDG_STATE_HOME:-$HOME/.local/state}/tablepro" \ + "${XDG_DATA_HOME:-$HOME/.local/share}/tablepro" \ + "${XDG_CACHE_HOME:-$HOME/.cache}/tablepro" + ``` + + In Passwords and Keys (Seahorse) or KWallet Manager, delete only the [TablePro secret entries](/linux/troubleshooting#saved-secret-entries). Removing the folders does not remove those keyring items. Then remove the native package with the uninstall command. + + For Flatpak, use this instead of the keep-data uninstall command: + + ```bash + flatpak uninstall --user --delete-data app.tablepro.TablePro + ``` + + [The delete-data option](https://docs.flatpak.org/en/latest/flatpak-command-reference.html#flatpak-uninstall) removes the sandbox's data and permissions, including its encrypted secret file. If the desktop keyring still lists a Secret portal item for this app, remove that item too. Native-installation keyring entries remain separate. + + + For native packages, remove both repositories if you enabled both: + + + ```bash Ubuntu + sudo add-apt-repository --remove ppa:tablepro/tablepro-beta + sudo add-apt-repository --remove ppa:tablepro/tablepro + ``` + ```bash Fedora + sudo dnf copr remove @tablepro/tablepro-beta + sudo dnf copr remove @tablepro/tablepro + ``` + + + For Flatpak, run `flatpak remotes --user`. Remove an unused bundle-origin remote with `flatpak remote-delete --user REPOSITORY`, replacing `REPOSITORY` with its listed name. Keep Flathub if other apps or runtimes use it. + + diff --git a/linux/keyboard-shortcuts.mdx b/linux/keyboard-shortcuts.mdx new file mode 100644 index 0000000..cefae4a --- /dev/null +++ b/linux/keyboard-shortcuts.mdx @@ -0,0 +1,138 @@ +--- +title: Keyboard shortcuts +description: Every key the Linux app binds, by where the focus is +tag: "Beta" +--- + +`Ctrl+?` opens the same list inside the app, as does **Keyboard Shortcuts** in the main menu. The keys are fixed; none can be rebound yet. + +Focus decides what some keys do. `Ctrl+F` searches the connection list, filters a table tab, finds in query results or finds in the editor, by where the focus is. `Escape` closes a dialog, stops a running query, or drops a selection or extra cursors. + + + The Keyboard Shortcuts dialog open on its General and Tabs sections + The Keyboard Shortcuts dialog open on its General and Tabs sections + + +## General + +| Action | Shortcut | +|---|---| +| New window | `Ctrl+Shift+N` | +| Preferences | `Ctrl+,` | +| Search connections | `Ctrl+F` | +| Query history | `Ctrl+Shift+H` | +| Show or hide the sidebar | `F9` | +| Show or hide the assistant | `Ctrl+Alt+A` | +| Keyboard shortcuts | `Ctrl+?` | +| Close a dialog | `Escape` | +| Quit | `Ctrl+Q` | + +## Tabs + +| Action | Shortcut | +|---|---| +| New SQL editor tab | `Ctrl+T` | +| Close the tab, or an empty window | `Ctrl+W` | +| Reopen the last closed tab | `Ctrl+Shift+T` | +| Switch to the recent tab. Hold `Ctrl` and press `E` again to go further back | `Ctrl+E` | +| View open tabs | `Ctrl+Shift+O` | +| Next tab | `Ctrl+Tab` or `Ctrl+Page Down` | +| Previous tab | `Ctrl+Shift+Tab` or `Ctrl+Page Up` | +| Move the tab right | `Ctrl+Shift+Page Down` | +| Move the tab left | `Ctrl+Shift+Page Up` | + +## Table tab + +| Action | Shortcut | +|---|---| +| Filter rows | `Ctrl+F` | +| Read the table again | `F5` or `Ctrl+R` | +| Save pending changes | `Ctrl+S` | +| Undo the last change | `Ctrl+Z` | +| Redo the last change | `Ctrl+Shift+Z` or `Ctrl+Y` | +| Previous page | `Alt+Page Up` | +| Next page | `Alt+Page Down` | +| Select all rows | `Ctrl+A` | +| Clear the selection | `Ctrl+Shift+A` | +| First row of the page | `Ctrl+Home` | +| Last row of the page | `Ctrl+End` | +| Extend the selection to the clicked row | `Shift+click` | +| Add or remove the clicked row | `Ctrl+click` | + +## Data grid + +| Action | Shortcut | +|---|---| +| Move between cells | Arrow keys | +| Edit a cell | `F2` or `Enter` | +| Toggle a boolean cell | `Space` | +| Show the cell menu | `Menu` or `Shift+F10` | +| Set the cell to NULL | `Ctrl+Backspace` | +| Open the referenced row | `Ctrl+J` | +| Widen the column | `Shift+Alt+Right` | +| Narrow the column | `Shift+Alt+Left` | +| Move the column left | `Alt+Left` | +| Move the column right | `Alt+Right` | +| Insert a row | `Ctrl+N` | +| Mark rows for deletion | `Delete` | +| Copy the cell or the selected rows | `Ctrl+C` | +| Paste | `Ctrl+V` | +| Clear the multi-row selection | `Escape` | +| Show or hide Row Details | `Alt+Enter` | +| Find in rows | `Ctrl+F` | +| Next match | `Ctrl+G` | +| Previous match | `Ctrl+Shift+G` | + +While a cell is being edited: + +| Action | Shortcut | +|---|---| +| Finish editing | `Enter` | +| Cancel editing | `Escape` | +| Finish and edit the next cell | `Tab` | +| Finish and edit the previous cell | `Shift+Tab` | +| Save the value in Row Details | `Ctrl+Enter` | + +## SQL editor + +| Action | Shortcut | +|---|---| +| Run the query or the selected text | `Ctrl+Enter` | +| Run the statement at the cursor | `Ctrl+Shift+Enter` | +| Cancel the running query | `Escape` | +| Move between the editor and the results | `F6` | +| Format SQL | `Ctrl+Shift+F` | +| Toggle line comment | `Ctrl+/` | +| Add a cursor at the next match | `Ctrl+D` | +| Add a cursor at every match | `Ctrl+Shift+L` | +| Add a cursor on the line above | `Shift+Alt+Up` | +| Add a cursor on the next line | `Shift+Alt+Down` | +| Add or remove a cursor | `Ctrl+click` | +| Return to one cursor | `Escape` | +| Open a SQL file | `Ctrl+O` | +| Save to the SQL file | `Ctrl+S` | +| Save to another SQL file | `Ctrl+Shift+S` | +| Find | `Ctrl+F` | +| Find and replace | `Ctrl+H` | +| Next match | `Ctrl+G` | +| Previous match | `Ctrl+Shift+G` | +| Accept the assistant's suggestion | `Tab` | +| Dismiss the assistant's suggestion | `Escape` | + +## Table structure + +| Action | Shortcut | +|---|---| +| Save pending changes | `Ctrl+S` | + +## ER diagram + +| Action | Shortcut | +|---|---| +| Zoom in | `Ctrl+Plus` or `Ctrl+=` | +| Zoom out | `Ctrl+Minus` | +| Reset zoom | `Ctrl+0` | +| Best fit | `F` | +| Read the tables again | `F5` or `Ctrl+R` | +| Open the selected table | `Enter` | +| Move the selected table | `Alt+Left`, `Alt+Right`, `Alt+Up`, `Alt+Down` | diff --git a/linux/sql-editor.mdx b/linux/sql-editor.mdx new file mode 100644 index 0000000..f6da3ab --- /dev/null +++ b/linux/sql-editor.mdx @@ -0,0 +1,87 @@ +--- +title: SQL editor +description: Run statements and scripts, read several result sets, and write with completion, snippets, multiple cursors and Vim mode in TablePro for Linux +tag: "Beta" +--- + +`Ctrl+T` opens an editor tab on the window's connection. In a window with no tab open, **Open SQL Editor** does the same. + + + A SQL editor tab with two SELECT statements above a results pane showing rows from the first one + A SQL editor tab with two SELECT statements above a results pane showing rows from the first one + + +## Run + +| Keys | Runs | +|---|---| +| `Ctrl+Enter` | The selection, or the whole text as a script | +| `Ctrl+Shift+Enter` | The statement at the cursor | +| `Escape`, or **Stop** | Stops the running query on the server | + +A script is split the way its engine reads it, `DELIMITER` on MySQL and `GO` on SQL Server included, and sent one statement at a time, or one batch at a time on SQL Server. A failed statement stops the script, except on SQL Server, where the next batch runs. + +Stopping cancels the statement on the server. Cassandra and ScyllaDB have no cancel, so the app stops waiting and the server runs the statement to its own timeout. + +The editor gives up on a query after 60 seconds. Change that under **Preferences > Editor > Query timeout (seconds)**, or per connection with **Custom Query Timeout** in its [Options](/linux/connect#options). 0 turns the timeout off. + +## Results + +Each result set, row count, notice and error of a run is its own entry in the results list. A result keeps 10,000 rows and a run 100,000; past that a banner offers **Export All…**, which runs the statement again on a separate read-only connection and writes every row to a file. After a failed statement, **Go to Error** puts the cursor where the server places the error. + +A statement that opens a transaction leaves **Commit** and **Roll Back** in the results pane until you pick one. Closing the window asks first while the transaction is open. + +## Completion and snippets + +Completion offers tables, views, columns, schemas, functions and keywords, and resolves aliases. Type a snippet's trigger, pick it in the list, then press `Tab` to move between its stops and `Shift+Tab` to go back. + +| Trigger | Writes | +|---|---| +| `sel` | `SELECT … FROM … WHERE` | +| `ins` | `INSERT INTO … VALUES` | +| `upd` | `UPDATE … SET … WHERE`, and `ALTER TABLE … UPDATE … WHERE` on ClickHouse | +| `del` | `DELETE FROM … WHERE` | +| `selj` | `SELECT … JOIN … ON`, except on Cassandra and ScyllaDB | +| `ctab` | `CREATE TABLE` with an `id` key column | +| `cidx` | `CREATE INDEX` | + +Your own snippets are `.snippets` files in GtkSourceView's snippet format, in the folder **Preferences > Editor > Snippets folder** shows. **Open Folder** creates it. A file added or changed takes effect without a restart, and a snippet with the same trigger replaces the built-in one. The format and the per-engine `languages` values are in the app's [README](https://github.com/TableProApp/TablePro/blob/main/linux/README.md#snippets). + +## Files and drafts + +`Ctrl+O` opens a `.sql` file into the tab, and so does dropping one on the editor. `Ctrl+S` saves back to it and `Ctrl+Shift+S` saves to another file. + +The text of every editor tab is kept as you type. A connection's tabs, editor tabs with their text and table tabs with their page and sort, reopen when the connection opens. + +## Multiple cursors + +| Keys | Does | +|---|---| +| `Ctrl+D` | Selects the word at the cursor, then adds a cursor at its next match | +| `Ctrl+Shift+L` | Adds a cursor at every match of the selection or the word | +| `Shift+Alt+Up`, `Shift+Alt+Down` | Adds a cursor on the line above or under the cursor, in the same column | +| `Ctrl+click` | Adds a cursor, or removes the one you click | +| `Escape` | Returns to one cursor, keeping its selection | + +Typing, deleting, pasting and moving work at every cursor, and one `Ctrl+Z` takes the edit back at all of them. A click, a find, **Format** or `Page Up` returns to one cursor. + +## Vim mode + +Turn on **Preferences > Editor > Vim Keybindings**. The line under the text shows the mode and the command you are typing, and the editor's own `Ctrl` shortcuts keep working in every mode. Every other key goes to Vim, `Escape` too, so use **Stop** to stop a running query. + +| Command | Does | +|---|---| +| `:w` | Saves the tab's file, asking for one when the tab has none | +| `:e` | Reads the tab's file again, asking first when that loses changes | +| `:q` | Closes the tab, asking first about unsaved changes or an open transaction | +| `:wq`, `:x` | Saves, then closes the tab | + +## Redis and MongoDB + +On a Redis connection the editor takes Redis commands, one per line, and shows each reply as `redis-cli` does. On MongoDB it takes mongosh statements such as `db.orders.find()`, `aggregate`, `runCommand`, `use` and `show`, and shows one document per row. + +## History and saved queries + +`Ctrl+Shift+H` opens **Query History**: every run from the editor, with full-text search, filters by connection, time and status, and export as SQL or CSV. A run that can carry a password is left out. + +**Save Query…** in the editor's menu keeps the text against the connection. **Saved Queries** in the main menu lists them, the window's connection first. diff --git a/linux/troubleshooting.mdx b/linux/troubleshooting.mdx new file mode 100644 index 0000000..3d0187e --- /dev/null +++ b/linux/troubleshooting.mdx @@ -0,0 +1,199 @@ +--- +title: Troubleshooting on Linux +description: Saved passwords, SSH tunnels, Kerberos, logs, crash reports and bug reports for TablePro on Linux +tag: "Beta" +--- + +Paths here are for the .deb and .rpm packages. The Flatpak bundle keeps the same files under `~/.var/app/app.tablepro.TablePro/`, mapped in [Where the files are](#where-the-files-are). + +## Passwords + +Native packages keep saved passwords, the MCP server access token and cloud AI API keys in the Secret Service. GNOME Keyring, KWallet and KeePassXC provide this desktop service. + +For the bundle, see [Flatpak secret storage](/linux/connect#flatpak-connections). It needs a working desktop portal and keyring. There is no plain-text fallback when secret storage fails. + +### Every connect asks for the password + +When the Secret Service or Flatpak's Secret portal is unavailable, the password prompt has no **Remember Password** switch. Check for a desktop keyring: + +```bash +busctl --user list | grep org.freedesktop.secrets +``` + +No line means none is installed or none can start. Install one, then log in again: + +- GNOME and most other desktops: `gnome-keyring` (`sudo apt install gnome-keyring`, `sudo dnf install gnome-keyring`). +- KDE Plasma: KWallet (`kwallet6` on Ubuntu, `kf6-kwallet` on Fedora), which Plasma installs by default. +- KeePassXC: turn on Secret Service Integration in its settings, and leave it running. + +The packages recommend one of these, so a normal install has one. A minimal install or a window manager session may not. + +### A saved password is asked for again + +The keyring is locked. The desktop asks to unlock it when a saved password is read; dismiss that prompt and the app asks for the password instead. A keyring that never unlocks at login usually has a different password from the account, after a password change or with automatic login. Passwords and Keys (Seahorse) or KWallet Manager changes the keyring password to the login password. + +After unlocking the keyring, retry the connection and accept the unlock prompt. If saving a newly entered password failed, enter it again with **Remember Password** on. + +### MCP and cloud AI cannot read or save a secret + +**Preferences > MCP** reports that the access token cannot be read or kept. **Preferences > AI** or the assistant reports the same problem for an API key. Entering a database password at each connect does not restore these features. + + + + If no keyring is running, install or start one as described in [Every connect asks for the password](#every-connect-asks-for-the-password). For Flatpak, also check that `xdg-desktop-portal` and your desktop's portal backend are installed and running, then log in again. + + + Unlock it in Passwords and Keys or KWallet Manager. If you dismissed an unlock prompt, retry the operation and accept the prompt. + + + In **Preferences > MCP**, click **Try Again**. In **Preferences > AI**, re-enter and apply an API key whose save failed, then retry the request. A key or token already stored does not need replacing after an unlock. + + + +### Saved secret entries + +Native-installation entries have these labels in the desktop keyring: + +- `TablePro database password for …` +- `TablePro SSH password for …` +- `TablePro SSH key passphrase for …` +- `TablePro MCP access token` +- `TablePro API key for …` + +Use these labels when removing saved credentials during a [full reset](/linux/install#optional-full-reset), which also covers removing Flatpak secrets. + +## SSH tunnels + +Native packages run the system `ssh` and read `~/.ssh/config`, `~/.ssh/known_hosts` and the SSH agent as a terminal does. For the bundle, check the [Flatpak connection limits](/linux/connect#flatpak-connections). When a tunnel fails, try the same hop in a terminal first: + +```bash +ssh -v -J jump.example.com user@bastion.example.com true +``` + +### Agent sign-in fails + +The app uses the agent that `SSH_AUTH_SOCK` names in the desktop session, and `ssh-add -l` lists the keys it holds. When the key works in a terminal and not in the app, the desktop session has a different agent or none: `systemctl --user show-environment | grep SSH_AUTH_SOCK` shows what apps started from the desktop get. + +### Unknown host key + +The server's SHA256 fingerprint shows before anything connects, even where `ssh_config` says `StrictHostKeyChecking accept-new` or `no`. Compare it with `ssh-keygen -lf` on the server's key, or with what the server's administrator gives you. + +### Changed host key + +**Review Key** in the connection's banner replaces the entry in `known_hosts`. Under `StrictHostKeyChecking yes` it cannot: run `ssh-keygen -R host`, then click **Retry**. A revoked key is refused, with no way past it in the app. + +## SQL Server with Kerberos + +**Windows (Kerberos)** uses an existing ticket. `kinit` and `klist` come in `krb5-user` on Ubuntu and `krb5-workstation` on Fedora. For Flatpak, check the [KCM cache and sandbox configuration](/linux/connect#flatpak-connections) too. + +```bash +kinit you@EXAMPLE.COM +klist +``` + +### KRB5KDC_ERR_S_PRINCIPAL_UNKNOWN + +The server's service principal, `MSSQLSvc/:`, is not in the realm the lookup used. It is built from the host and port you typed and looked up in the default realm only. For native packages, check `default_realm` in `/etc/krb5.conf`; Flatpak uses its sandbox configuration. Type the host name the SPN is registered for, not an IP address or a CNAME. A server in another realm works only when your KDC answers with a referral, as Active Directory does inside a forest. + +A missing or expired ticket fails the same login: run `kinit` again, then retry. + +## Logs and crash reports + +Started from the desktop, the app writes its log to the journal: + +```bash +journalctl --user --boot | grep -i tablepro +``` + +For a detailed log, quit the app first, since a second launch hands over to the running one and exits. Then start it from a terminal: + +```bash +RUST_LOG=debug tablepro 2> tablepro.log +``` + +Before attaching any log, crash report or diagnostic text to a public issue, read it and remove private data. Logs name hosts, databases and tables. Panic messages may include SQL, values or file paths. Keep an unedited copy privately if needed. + +Rust panics on the main UI thread write a text report in the [crash report folder](#where-the-files-are). The next launch offers **Show Report**. Nothing is uploaded. These reports do not cover native segmentation faults, native aborts, out-of-memory kills or every worker-thread panic. + +### Native crashes + + + + Start with the user journal command in [Logs and crash reports](#logs-and-crash-reports). For a native crash or an out-of-memory kill, also inspect system messages: + + ```bash + journalctl --boot --since "10 minutes ago" | grep -iE 'tablepro|segfault|out of memory|killed process' + ``` + + Adjust the time to include the crash. If system journal access is denied, ask the system administrator for those messages. + + + On distributions running `systemd-coredump`, use [coredumpctl](https://www.freedesktop.org/software/systemd/man/latest/coredumpctl.html): + + ```bash + coredumpctl list tablepro + coredumpctl info PID + ``` + + Replace `PID` with the process ID from the row at the crash time. Read and redact the output before sharing it. If no entry exists or `coredumpctl` is unavailable, use your distribution's crash reporter and send the journal, app version and reproduction steps. + + + +A core dump holds process memory and may contain passwords, tokens, SQL and result rows. Never attach one publicly. Send redacted metadata first. If maintainers need a dump, email [hello@tablepro.app](mailto:hello@tablepro.app) to arrange a private transfer, as listed in [the security policy](https://github.com/TableProApp/TablePro/blob/main/SECURITY.md#reporting-a-vulnerability). + +## Reporting a bug + +Open an issue at [github.com/TableProApp/TablePro/issues](https://github.com/TableProApp/TablePro/issues) with: + +- The text from **About TablePro > Troubleshooting > Debugging Information**. **Copy Text** puts it on the clipboard. It holds versions and no connection details. +- Where the app came from (the PPA, COPR, a .deb, .rpm or Flatpak bundle from GitHub Releases, or a source build), the distribution and its version, and the desktop and session: `echo $XDG_CURRENT_DESKTOP $XDG_SESSION_TYPE`. +- The log and newest crash report from the same time, or native crash metadata, after the [privacy review](#logs-and-crash-reports). + +## After a downgrade + +An app refuses a saved file or history database whose storage format is newer than it understands. This checks the storage format, not the app's version number. An older app may read and change files from a newer app when both use the same format. + +[Back up saved work](#back-up-saved-work) before changing versions. When a storage format is too new: + +- The connection list shows "Saved connections were created by a newer version of TablePro". **Reset…** moves the file aside, under a name the toast shows, and starts an empty list. +- A connection's saved tabs do not reopen, and a toast says "Saved tabs could not be read", with **Reset**. +- The query history says it could not be read. + +Reinstall a version that supports that storage format to reopen the files. Avoid **Reset** if you need the saved work; it starts an empty replacement instead of converting the newer format. + +## Back up saved work + + + + Close every app window and wait for the process to exit. This stops history and draft writes during the copy. + + + Copy the config, state and data folders in [Where the files are](#where-the-files-are) to a private backup location. Keep the entire state folder, including `history.db` and any `history.db-wal` or `history.db-shm` files beside it. For Flatpak, copy the entire app folder. + + + Save the output of the GSettings command in [Where the files are](#where-the-files-are) with the backup as a reference for your settings. Native keyring items are separate; an export of connections does not include their secrets. + + + +## Where the files are + +| Path | Holds | +|---|---| +| `~/.config/tablepro/connections.json` | Saved connections, without passwords | +| `~/.config/tablepro/column_widths.json`, `filter_settings.json` | Column widths and filters per table | +| `~/.local/state/tablepro/history.db` | Query history and saved queries | +| `~/.local/state/tablepro/workspaces/` | Each connection's tabs, and the connections open at the last quit | +| `~/.local/share/tablepro/drafts/` | The text of each SQL editor tab | +| `~/.local/share/tablepro/snippets/` | Custom SQL editor snippets | +| `~/.local/state/tablepro/crashes/` | Crash reports | + +These are the default paths. If you set `XDG_CONFIG_HOME`, `XDG_STATE_HOME` or `XDG_DATA_HOME`, use the `tablepro` folder under that location instead. + +Preferences are in GSettings: `gsettings list-recursively app.tablepro.TablePro` lists them, and `man tablepro` has the same list. + +The Flatpak bundle uses `~/.var/app/app.tablepro.TablePro/config/tablepro/`, `.local/state/tablepro/` and `data/tablepro/` in place of `~/.config/tablepro/`, `~/.local/state/tablepro/` and `~/.local/share/tablepro/`. There, the preferences and a detailed log come from: + +```bash +flatpak run --command=gsettings app.tablepro.TablePro list-recursively app.tablepro.TablePro +flatpak run --env=RUST_LOG=debug app.tablepro.TablePro 2> tablepro.log +```