From 001d2627c3662a6379b982897f48d31aa9a6502e Mon Sep 17 00:00:00 2001 From: Ngo Quoc Dat Date: Fri, 13 Nov 2026 21:48:03 +0700 Subject: [PATCH] docs(roadmap): one roadmap for Linux, Windows and the core, with Linux and Windows drivers linked for good --- ROADMAP.md | 682 ++++++++++++++++++ core/AGENTS.md | 2 +- core/docs/decisions/0004-driver-plugin-abi.md | 2 +- ...25-linux-and-windows-link-their-drivers.md | 32 + core/docs/decisions/README.md | 3 +- linux/AGENTS.md | 2 +- linux/README.md | 6 +- linux/ROADMAP.md | 257 +------ linux/docs/README.md | 5 +- linux/docs/decisions/0001-no-plugin-system.md | 2 +- linux/docs/decisions/README.md | 2 +- linux/docs/features.md | 181 +++++ linux/docs/releasing.md | 20 + 13 files changed, 930 insertions(+), 266 deletions(-) create mode 100644 ROADMAP.md create mode 100644 core/docs/decisions/0025-linux-and-windows-link-their-drivers.md create mode 100644 linux/docs/features.md diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000000..55a4831458 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,682 @@ +# Roadmap + +The work that makes the Linux and Windows apps complete daily-use clients, the core work under them, and the sync service and features every platform still lacks. The bar is the macOS app plus what the market expects from a daily-use client. + +Written 2026-11-11 against main `8581bd6c7`, from code inventories of the macOS, Linux and Windows apps and the Rust core, and a survey of 20 other clients ([Sources](#sources)). The maintainer's answers of 2026-11-13 are under [Decisions](#decisions). What the Linux app does today is in [linux/docs/features.md](linux/docs/features.md). + +## How to track + +- Tick a box when its PR merges and write the PR after it: `- [x] Windows: #4321`. +- A partial PR leaves the box open and adds `partly #4321: `. +- IDs never change. A new item goes at the end of its section with the next free number. +- Tier, from the survey: **CORE** every daily user expects it, **STD** most serious clients have it, **ADV** a pro-tier differentiator. +- `macOS: yes` means the macOS app has it; its code and docs are the reference. `paid` means it is a paid feature there. +- `needs C-07` names a core item that lands first. +- A `server` box is work in tablepro-cloud, outside this repository. +- Recount the progress table: + +```sh +awk '/^## /{p=$0} /^ *- \[[ x]\]/{t[p]++} /^ *- \[x\]/{d[p]++} END{for(k in t) print d[k]+0"/"t[k]" "k}' ROADMAP.md +``` + +## Order + +1. Linux 0.1.0: the Linux items of Phase 0. +2. Phase 1, then Windows: the Windows items of Phase 0 and every CORE item of Phase 2, then the first public Windows release (D-04). +3. Phases 3 to 8, by tier and demand. + +## Progress + +| Section | Boxes | Done | +|---|---|---| +| Phase 0: Release blockers | 16 | 0 | +| Phase 1: Core enablers | 23 | 0 | +| Phase 2: Windows daily use | 62 | 0 | +| Phase 3: Standard features both apps lack | 116 | 0 | +| Phase 4: Advanced tier | 60 | 0 | +| Phase 5: Engines | 27 | 0 | +| Phase 6: Quality bars | 8 | 0 | +| Phase 7: Sync and teams | 15 | 0 | +| Phase 8: Beyond the market | 40 | 0 | +| Total | 367 | 0 | + +## Where each app stands + +**macOS**, the reference: 48 engine types (5 bundled driver plugins, 31 in the registry), and every survey tier up to ADV. Compare & Sync, Server Dashboard, Table Health, Query Insights, Data Rewind, EXPLAIN diagrams, charts, map mode, routine debugger, users and roles, backup and restore, an agent-mode AI with 15 providers, an MCP server with 47 tools, iCloud sync and Team features. + +**Linux**, 0.1.0-beta.3: 9 engines from the core. Covers most of the CORE tier: connections with SSH, TLS and sockets, filters, editing with undo, completion, formatter, snippets, Vim, history, saved queries, structure editing, ER diagram, 7 export formats, dump and SQL import, AI chat, MCP with 11 tools, a CLI. Missing: all of admin and monitoring, query parameters, drawn plans, charts, schema compare, data transfer, backup through native tools, SOCKS, cloud IAM, users and roles, view and routine editing, the 10 paid features. 0.1.0 waits on [release criteria](linux/docs/releasing.md#release-criteria) 8 and 10. + +**Windows**, unreleased: 9 engines through the FFI. Has the connection library (groups, tags, favourites), in-process SSH, TLS with remedies, paging and sort, table-row editing with SQL review, a Direct2D editor with highlighting and multiple cursors, run statement, selection or script with transactions, Safe Mode (3 levels), tab tear-out, session restore, an MSIX build. Missing most of the CORE tier past that: filters, value viewers, row details, FK navigation, copy formats, completion, formatter, history, saved queries, .sql files, export, import, structure, sidebar actions, undo of edits. + +**Core**: the logic mostly exists, the FFI does not. `ddl`, `export`, `import`, `dump`, `filter`, history, saved queries, `ai`, `mcp`, `cli`, `account` and `foreign-import` are core code the FFI does not expose. The formatter, completion scope, script runner, key-based change tracker, copy renderer, highlight rules, Open Quickly and ER layout sit in `linux/crates/app`, GTK-free. Phase 1 moves both down so Windows builds on the code Linux already runs. + +## What the market expects + +- Top reasons users pick or leave a client: startup speed and memory, price model, engine breadth, native feel and dark mode, stability on big tables, OS availability, editor smarts, abandoned tools, trust (no forced AI, no required login), guards against production mistakes. +- Native on all three OSes is rare: most cross-platform clients are JVM (DataGrip, DBeaver, DbVisualizer) or Electron (Beekeeper, DbGate, Antares). +- Safe Mode is a stated reason to pick TablePlus. TablePro has it on every platform. +- Moving into STD during 2025-2026: an MCP server, AI with per-action consent, cloud IAM sign-in, a command palette, visual EXPLAIN, schema compare. +- Azure Data Studio retired on 2026-02-28. SQL notebooks now live only in the VS Code mssql extension. + +## Principles + +- Core first: logic both apps need lands in a core crate and the FFI before a Windows UI uses it. A Linux move keeps Linux's behavior and switches Linux to the core version in the same PR. +- Native UI per platform (`AGENTS.md`), no shared UI layer. +- Linux and Windows link their drivers at compile time for good ([core ADR 0025](core/docs/decisions/0025-linux-and-windows-link-their-drivers.md)). Oracle is blocked on a client library. +- One license and one feature gate on every platform: what is paid on macOS is paid on Linux and Windows (D-02). +- A new question that would reverse a decision goes under [Decisions](#decisions) as the next D item, and waits for the maintainer. + +## Phase 0: Release blockers + +### Windows first public release + +- [ ] **R-01** RUSTSEC-2026-0459 (bundled SQLite before 3.54.0): `deny.toml` blocks a Windows release until sqlx allows libsqlite3-sys 0.39 and the pin is raised +- [ ] **R-02** Maintainer setup, `windows/RELEASING.md` steps 1-6: tag rulesets, Artifact Signing with a Public Trust profile, the OIDC app registration, the `windows-release` secrets, `WINDOWS_SIGNING_*` and `WINDOWS_PUBLISHER` (permanent after the first release), the `windows-winget` environment +- [ ] **R-03** Dry run of `release-windows.yml` from main: the x64 package, the bundle, install-and-start tests and winget validation, all unverified (ADR 0005) +- [ ] **R-04** Real hardware: Windows 10 build 17763, Native AOT, Mica on a GPU, TabView in the title bar on Windows 10, loading from a signed MSIX (ADR 0001, 0004) +- [ ] **R-05** Drop the Windows App SDK metapackage once Community Toolkit 8.3 is stable (41.8 MB of unused ONNX and DirectML per architecture) +- [ ] **R-06** Updates: an App Installer file or the Store, an in-app update check, stable and beta channels +- [ ] **R-07** Live-server Windows tests for the 7 engines no Windows suite connects to: MySQL, SQL Server, DuckDB, ClickHouse, Cassandra, MongoDB, Redis +- [ ] **R-08** Windows user guide on docs.tablepro.app and the download page +- [ ] **R-09** First `windows-v0.1.0` tag, once the rest of Phase 0 and every CORE item in Phase 2 are done; no public build before it (D-04) + +### Linux 0.1.0 + +- [ ] **R-10** [Release criterion](linux/docs/releasing.md#release-criteria) 8: the manual pass with Orca, the keyboard alone, High Contrast, 1.5x text and a right-to-left locale +- [ ] **R-11** Release criterion 10: a dated week of daily use +- [ ] **R-12** Bring [linux/docs/features.md](linux/docs/features.md) up to date: about 40 features from #4108 to #4159, #4145 and #4147 are missing, and the Saved queries, Sidebar, Preferences, Connections import, MCP Tools and Copy rows are stale +- [ ] **R-13** The display-scale pass on a real GPU and a HiDPI screen, and a hand install on Ubuntu 26.04 +- [ ] **R-14** #4099 (KDE Wallet prompt opens behind the window) and #4101 (`flatpak list` shows "Usage data") +- [ ] **R-15** After 0.1.0: the Flathub manifest and exception request, by the maintainer, under [Flathub's requirements](linux/docs/decisions/0041-beta-repositories-and-release-packages.md#context) +- [ ] **R-16** After 0.1.0: an AUR PKGBUILD, kept by the community + +## Phase 1: Core enablers + +Each item ends in an FFI surface Windows needs. Linux paths are under `linux/crates/app/src/`. + +- [ ] **C-01** Filters through the FFI: `table_query` takes a `FilterSet` (always `FilterSet::default()` in `core/crates/ffi/src/session.rs` today) and `operators_for` +- [ ] **C-02** Export through the FFI: `core::export` encoders (CSV, TSV, JSON, JSON Lines, HTML, Markdown, SQL INSERT, XML, XLSX) as a streaming job with progress and Stop; the sinks and ledger in `ui/export/` move down +- [ ] **C-03** CSV import and pasted rows through the FFI: `core::import::{csv_import, plan_import, PastedRows}` +- [ ] **C-04** SQL dump and SQL file import through the FFI: `core::dump`, `SqlFileReader`, with the orchestration in `ui/export/dump_job.rs` and `services/import_file.rs` moved down +- [ ] **C-05** Structure through the FFI: the table definition (columns, indexes, keys, comments), CREATE statements, `core::ddl` drafts, `diff_table`, plans and catalog operations (core ADR 0013); the logic in `services/pending_structure.rs` moves down +- [ ] **C-06** Storage through the FFI: `QueryHistory` (FTS5, retention, export), `SavedQueries` with folders and keywords, `Favourites`, `DraftStore` (deferred by core ADR 0017) +- [ ] **C-07** SQL formatter into core: `ui/editor/format_plan.rs` and `significant_tokens.rs` +- [ ] **C-08** Completion context into core: `completion/completion_scope.rs`, `catalog_read.rs` and the fuzzy ranking; proposal objects stay per app +- [ ] **C-09** Script runner into core: `script_runner.rs` and `run_log.rs` with `BatchErrorPolicy` (the FFI's `QueryEditor::run` takes one statement or one `GO` batch) +- [ ] **C-10** Pending row edits keyed by primary key into core: `services/change_tracker.rs` and `undo_op.rs`, so edits survive sort, filter and paging and undo is shared; replaces the position-keyed FFI `TableEditor` and Windows `UndoHistory.cs` +- [ ] **C-11** Copy and display text into core: `ui/clipboard/copy_renderer.rs`, `services/grid/display_text.rs`, `date_display.rs`, `hex_dump.rs`, `ui/format/thousands.rs` +- [ ] **C-12** Grid helpers into core: highlight rules (`services/grid/highlight.rs` and `persistence/highlight_rules_store.rs`) and find in grid (`find_matches.rs`) +- [ ] **C-13** Open Quickly matching and index into core: `ui/quick_open/{matching,search_index}.rs` +- [ ] **C-14** ER diagram model, layout and scene into core: `ui/diagram/{layout,model,scene}.rs`; drawing and export stay per app +- [ ] **C-15** Snippets in a neutral format: `builtin_snippets` is written in GtkSourceView syntax today; core keeps a neutral form and each app converts +- [ ] **C-16** Foreign import through the FFI: a Windows `ForeignHost` and `ForeignAppDirs`, passwords into Credential Manager, DPAPI-held passwords read (core ADR 0008) +- [ ] **C-17** AI through the FFI: providers, prompts, schema context, streamed replies +- [ ] **C-18** MCP server through the FFI, with a Windows host +- [ ] **C-19** Account through the FFI: the Windows `AppClient` once registered with tablepro-cloud, and the entitlement gate that every paid feature on Windows needs (core ADR 0016, D-02) +- [ ] **C-20** CLI on Windows: a `Host`, MCP dispatch, peer verification on the pipe, PowerShell completion (core ADR 0018) +- [ ] **C-21** Query-result editing through the FFI (core ADR 0015, after ADR 0019) +- [ ] **C-22** Connection library through the FFI: export to JSON, duplicate with secrets +- [ ] **C-23** uniffi 0.32 once uniffi-bindgen-cs supports it (issue #183, core ADR 0002) + +## Phase 2: Windows daily use + +The first public Windows release waits for every CORE item here and the Windows items of Phase 0 (D-04). + +### Connections + +- [ ] **W-01** Duplicate a connection with its secrets · CORE · needs C-22 +- [ ] **W-02** Export the connections file (no secrets); import of TablePro's file exists · STD · needs C-22 +- [ ] **W-03** Paste a URL on the Connections page to start a connection (today only in the engine chooser) · STD +- [ ] **W-04** Jump hosts in the SSH section; the core and the FFI record carry them · STD +- [ ] **W-05** Connect timeout field · STD +- [ ] **W-06** Group colour (the record has `Color`) · STD +- [ ] **W-07** Import from TablePlus, DBeaver, DataGrip, Beekeeper, Navicat and DBX · STD · needs C-16 +- [ ] **W-08** Production cue: the connection colour on the tab strip, title bar and toolbar, and an environment label · CORE + +### Sidebar + +- [ ] **W-09** Object context menu: Open, Open in New Tab, Copy Name, Show CREATE, Truncate, Drop, through Safe Mode · CORE · needs C-05 +- [ ] **W-10** Create and drop databases and schemas · CORE · needs C-05 +- [ ] **W-11** Database switcher per connection and per query tab · CORE +- [ ] **W-12** Open a routine, trigger or sequence: its definition read-only, with Copy and Open in Editor · STD +- [ ] **W-13** Columns, indexes and keys under a table node · STD · needs C-05 +- [ ] **W-14** Table info: rows, size, comment · STD + +### Grid + +- [ ] **W-15** Filters: per-column operators, raw WHERE, match any or all, kept per table · CORE · needs C-01 +- [ ] **W-16** Filter by a cell's value, or exclude it · CORE · needs C-01 +- [ ] **W-17** Value viewers for long text, JSON, binary (hex) and images; a tooltip on a cut cell · CORE +- [ ] **W-18** Row details pane with editing · STD +- [ ] **W-19** Follow a foreign key to the referenced row, and show referencing rows · CORE +- [ ] **W-20** Copy as CSV or TSV with headers, JSON, Markdown, INSERT, IN clause · CORE · needs C-11 +- [ ] **W-21** Reorder, hide and freeze columns, kept per table (the control has frozen columns) · STD +- [ ] **W-22** Context menu on query-result grids · CORE +- [ ] **W-23** Selection summary: count, sum, average, min, max · STD +- [ ] **W-24** Find in the grid · STD · needs C-12 +- [ ] **W-25** Grid display settings: NULL text, date format, grid font, row height, stripes · STD · needs C-11 +- [ ] **W-26** Highlight rules · ADV · needs C-12 + +### Editing + +- [ ] **W-27** Undo and redo of pending edits · CORE · needs C-10 +- [ ] **W-28** Paste rows from the clipboard · STD · needs C-03, C-10 +- [ ] **W-29** Edit query results that read one keyed table · STD · needs C-21 +- [ ] **W-30** Type editors: date and time picker, enum menu, JSON check, boolean toggle · STD + +### SQL editor + +- [ ] **W-31** Completion: tables, columns, aliases, schemas, functions, keywords · CORE · needs C-08 +- [ ] **W-32** Formatter · CORE · needs C-07 +- [ ] **W-33** Replace, and regular expressions in Find · CORE +- [ ] **W-34** Open and save .sql files, drop a file on the editor, recent files · CORE +- [ ] **W-35** Query history with search, pins and retention · CORE · needs C-06 +- [ ] **W-36** Saved queries in folders · CORE · needs C-06 +- [ ] **W-37** Snippets with tab stops · STD · needs C-15 +- [ ] **W-38** Run a whole script with an error policy, one entry per result · CORE · needs C-09 +- [ ] **W-39** Word wrap, bracket matching, the current-statement band, Go to Error · STD +- [ ] **W-40** Vim mode · STD +- [ ] **W-41** Code folding · STD + +### Structure + +- [ ] **W-42** Structure view: columns, indexes, foreign keys, comments, the CREATE statement · CORE · needs C-05 +- [ ] **W-43** Table designer: create and alter columns, indexes and foreign keys, with the SQL reviewed · CORE · needs C-05 +- [ ] **W-44** ER diagram · STD · needs C-14 + +### Import and export + +- [ ] **W-45** Export a table or a result to CSV, JSON, XLSX, SQL INSERT, Markdown, HTML and XML, with progress and Stop · CORE · needs C-02 +- [ ] **W-46** CSV import into a table with a column mapping · CORE · needs C-03 +- [ ] **W-47** Import SQL File and Export Database · CORE · needs C-04 + +### NoSQL + +- [ ] **W-48** Redis key tab: the value by type, length, TTL, Load More (opening a key does nothing today) · CORE +- [ ] **W-49** MongoDB: documents as JSON with a tree view · STD +- [ ] **W-50** Cassandra paging past the first page (the FFI refuses offsets; page by paging state) · CORE + +### Workspace + +- [ ] **W-51** Open Quickly: objects, saved and past queries, commands · STD · needs C-13 +- [ ] **W-52** Settings: editor font family, grid font, NULL display, history, AI and MCP pages · CORE +- [ ] **W-53** A toast when a long query finishes in a background tab · STD +- [ ] **W-54** Every string localizable, the editor's menu and find bar included; Vietnamese first · STD +- [ ] **W-55** Editor colour schemes · STD +- [ ] **W-56** Grid accessibility: row header peers, and a workaround for the empty `ColumnHeaders` in Windows App SDK 2.6.4 · CORE + +### AI, MCP, account, integration + +- [ ] **W-57** AI assistant: providers, chat with schema context, Explain, Review, Optimize, Fix, AI policy per connection · STD · needs C-17 +- [ ] **W-58** MCP server with an External Clients level per connection · ADV · needs C-18 +- [ ] **W-59** Account page, license ask, and the paid-feature gate on the macOS license (D-02) · STD · needs C-19 +- [ ] **W-60** `tablepro://` and database URL links · STD +- [ ] **W-61** File associations for .sql, SQLite and DuckDB files · STD +- [ ] **W-62** Launch arguments and the `tablepro` CLI (the execution alias ignores arguments today) · STD · needs C-20 + +## Phase 3: Standard features both apps lack + +The Windows box assumes its Phase 2 base. Linux-only items have no Windows box. + +### Connections + +- **S-01** SOCKS5 and HTTP proxy with remote DNS · STD · macOS: yes + - [ ] core: a `TransportKind` beside DirectTcp, SshForward and LocalSocket + - [ ] Linux + - [ ] Windows +- **S-02** Cloud IAM sign-in: AWS RDS and Aurora tokens, Google Cloud SQL IAM · STD · macOS: yes + - [ ] core: an `AuthMode` beside Password and Kerberos + - [ ] Linux + - [ ] Windows +- **S-03** Microsoft Entra ID for SQL Server (core ADR 0005) · STD · macOS: yes + - [ ] core + - [ ] Linux + - [ ] Windows +- **S-04** Startup SQL per connection · STD · macOS: yes + - [ ] core + - [ ] Linux + - [ ] Windows +- **S-05** Password from a command, an environment variable or a file; 1Password, Vault and AWS Secrets Manager after · ADV · macOS: yes + - [ ] core + - [ ] Linux + - [ ] Windows +- **S-06** Reusable SSH profiles · STD · macOS: yes + - [ ] core + - [ ] Linux + - [ ] Windows +- **S-07** Encrypted connection export with secrets · STD · macOS: paid + - [ ] core + - [ ] Linux + - [ ] Windows +- **S-08** Kerberos for PostgreSQL and MySQL; an SPN override for SQL Server outside the client's realm (a tiberius change) · ADV · macOS: yes + - [ ] core + - [ ] Linux + - [ ] Windows +- **S-09** Pre-connect and post-disconnect scripts; a tunnel command (kubectl port-forward, AWS SSM) · ADV · macOS: yes + - [ ] core + - [ ] Linux + - [ ] Windows + +### Grid and editing + +- **S-10** Saved filter presets and a default filter per table · STD · macOS: yes + - [ ] core + - [ ] Linux + - [ ] Windows +- **S-11** Foreign key value picker in the cell editor · STD · macOS: yes + - [ ] Linux + - [ ] Windows +- **S-12** Edit binary values from and to a file; array and spatial values · STD · macOS: yes + - [ ] core + - [ ] Linux + - [ ] Windows +- **S-13** A clock in the grid's cell editor (Row Details has one) · STD + - [ ] Linux +- **S-14** Display As: UUID forms, Unix timestamps, JSON inside text; MessagePack, Protobuf and PHP after · ADV · macOS: yes + - [ ] core + - [ ] Linux + - [ ] Windows +- **S-15** Search a value across every table · ADV · macOS: yes + - [ ] core + - [ ] Linux + - [ ] Windows + +### SQL editor + +- **S-16** Query parameters (`:name`, `?`) with a prompt, LIKE and IN expansion · STD · macOS: yes + - [ ] core: parameter scan in `sql_syntax`, binding per driver + - [ ] Linux + - [ ] Windows +- **S-17** EXPLAIN as a tree and a diagram, with EXPLAIN ANALYZE where the engine has it · STD · macOS: yes + - [ ] core: a plan model parsed per engine + - [ ] Linux + - [ ] Windows +- **S-18** Result tabs: keep earlier results, pin one, compare two · STD · macOS: yes + - [ ] Linux + - [ ] Windows +- **S-19** Split editor or tab groups · STD · macOS: no + - [ ] Linux + - [ ] Windows +- **S-20** Inline diagnostics: syntax errors, unknown tables and columns · ADV · macOS: partly + - [ ] core + - [ ] Linux + - [ ] Windows +- **S-21** Shortcut customization with conflicts and reset · STD · macOS: yes + - [ ] Linux + - [ ] Windows +- **S-22** Commands in Open Quickly (Linux finds objects and queries only) · STD · macOS: partly + - [ ] Linux + +### Structure and objects + +- **S-23** Create and edit views, routines and triggers; refresh materialized views · STD · macOS: yes + - [ ] core + - [ ] Linux + - [ ] Windows +- **S-24** Check constraints and partitions in the structure tab · STD · macOS: partly + - [ ] core + - [ ] Linux + - [ ] Windows +- **S-25** Drag to reorder columns, with the ALTER previewed · STD + - [ ] Linux + - [ ] Windows +- **S-26** Users, roles and privileges for MySQL, MariaDB, PostgreSQL and SQL Server · STD · macOS: yes + - [ ] core + - [ ] Linux + - [ ] Windows +- **S-27** PostgreSQL enum, composite and domain types; extensions · STD · macOS: yes + - [ ] core + - [ ] Linux + - [ ] Windows +- **S-28** Rename and drop views, routines and triggers from the sidebar; Copy Name · CORE + - [ ] Linux + +### Admin + +- **S-29** Process list with cancel and terminate · STD · macOS: yes + - [ ] core + - [ ] Linux + - [ ] Windows +- **S-30** Server variables and status · STD · macOS: partly + - [ ] core + - [ ] Linux + - [ ] Windows +- **S-31** Maintenance: VACUUM, ANALYZE, REINDEX, OPTIMIZE, CHECK, REPAIR, SQLite integrity check · STD · macOS: yes + - [ ] core + - [ ] Linux + - [ ] Windows + +### Import, export, transfer + +- **S-32** Import JSON, JSON Lines and XLSX; CSV into a new table; lift Linux's 64 MiB CSV limit · STD · macOS: yes + - [ ] core + - [ ] Linux + - [ ] Windows +- **S-33** Export Parquet and JSON Lines files · STD · macOS: yes + - [ ] core + - [ ] Linux + - [ ] Windows +- **S-34** Copy rows to another connection with a column mapping · STD · macOS: yes + - [ ] core + - [ ] Linux + - [ ] Windows +- **S-35** Backup and restore through the engines' tools (pg_dump and pg_restore, mysqldump, mongodump). Flatpak needs `flatpak-spawn --host` or bundled tools; MSIX needs them on PATH · STD · macOS: yes + - [ ] core + - [ ] Linux + - [ ] Windows +- **S-36** Reusable export presets · STD · macOS: no + - [ ] core + - [ ] Linux + - [ ] Windows + +### NoSQL + +- **S-37** Redis: edit values and TTL, create, rename and delete keys, a namespace tree · STD · macOS: yes + - [ ] core: `write_batch` returns `Unsupported(Tables)` today + - [ ] Linux + - [ ] Windows +- **S-38** Redis Cluster and Sentinel; Valkey tested · ADV · macOS: yes + - [ ] core + - [ ] Linux + - [ ] Windows +- **S-39** MongoDB: index management, a document tree editor, validation rules · STD · macOS: partly + - [ ] core + - [ ] Linux + - [ ] Windows + +### Visualization + +- **S-40** Charts from a result: bar, line, area, scatter · STD · macOS: paid + - [ ] Linux + - [ ] Windows +- **S-41** Map view for geometry columns · ADV · macOS: yes + - [ ] core + - [ ] Linux + - [ ] Windows + +### Workspace + +- **S-42** An app theme override and custom themes (Linux follows the system; Windows has Light, Dark, System) · STD · macOS: yes + - [ ] Linux + - [ ] Windows +- **S-43** French, Korean, Turkish, Simplified and Traditional Chinese, which macOS ships · STD + - [ ] Linux + - [ ] Windows +- **S-44** GNOME Shell search provider for connections · STD + - [ ] Linux + +## Phase 4: Advanced tier + +macOS has every item here, most as paid features, and the same license gates them on Linux and Windows (D-02). Linux and Windows have none; Linux's account page lists all 10 paid features as absent. + +- **A-01** Compare & Sync: schema diff and row diff between connections, a sync script, saved comparisons · paid + - [ ] core + - [ ] Linux + - [ ] Windows +- **A-02** Server Dashboard: sessions, metrics, slow queries, locks and blocking chains, replication status, saved-query tiles + - [ ] core + - [ ] Linux + - [ ] Windows +- **A-03** Table Health: bloat, unused and redundant indexes, missing keys, XID age, stale statistics, a fix script + - [ ] core + - [ ] Linux + - [ ] Windows +- **A-04** Query Insights: most run, slowest, got slower, failures · paid + - [ ] core + - [ ] Linux + - [ ] Windows +- **A-05** Data Rewind: restore values from before a save, kept 7 days · paid + - [ ] core + - [ ] Linux + - [ ] Windows +- **A-06** AI agent mode: tool calls with approval, `@` context, slash commands, saved conversations, AI rules per connection + - [ ] core + - [ ] Linux + - [ ] Windows +- **A-07** More AI providers: Gemini, xAI, OpenRouter, Copilot, Bedrock, llama.cpp (Linux has Anthropic, OpenAI and OpenAI-compatible) + - [ ] core + - [ ] Linux + - [ ] Windows +- **A-08** MCP client: the assistant calls outside MCP servers + - [ ] core + - [ ] Linux + - [ ] Windows +- **A-09** MCP server parity: 47 tools, resources, prompts, subscriptions, scoped tokens, pairing, an activity log, client setup snippets (Linux has 11 tools and one token) + - [ ] core + - [ ] Linux + - [ ] Windows +- **A-10** Linked SQL folders with Git status, commit, pull and push · paid + - [ ] core + - [ ] Linux + - [ ] Windows +- **A-11** Environment variables in connection fields · paid + - [ ] core + - [ ] Linux + - [ ] Windows +- **A-12** Masking rules across the grid, copies, exports, AI and MCP + - [ ] core + - [ ] Linux + - [ ] Windows +- **A-13** Generate test rows: up to 1M, foreign-key aware, seeded + - [ ] core + - [ ] Linux + - [ ] Windows +- **A-14** Join builder from foreign keys + - [ ] core + - [ ] Linux + - [ ] Windows +- **A-15** ER diagram editing (add keys and columns) and Mermaid, DOT and PDF export + - [ ] core + - [ ] Linux + - [ ] Windows +- **A-16** Data dictionary export to Markdown and HTML + - [ ] core + - [ ] Linux + - [ ] Windows +- **A-17** Copy tables and databases across connections and engines, with type translation + - [ ] core + - [ ] Linux + - [ ] Windows +- **A-18** Routine debugger for PL/pgSQL + - [ ] core + - [ ] Linux + - [ ] Windows +- **A-19** Live messages: PostgreSQL LISTEN/NOTIFY, Redis channels + - [ ] core + - [ ] Linux + - [ ] Windows +- **A-20** Data Files: open CSV, JSON and Excel without importing, through the DuckDB driver + - [ ] core + - [ ] Linux + - [ ] Windows + +## Phase 5: Engines + +The core has 9 drivers; macOS has 48 engine types. Linux and Windows link drivers at compile time ([core ADR 0025](core/docs/decisions/0025-linux-and-windows-link-their-drivers.md)), so each engine is a core crate on a client library that meets [adding-drivers.md, The client library](linux/docs/adding-drivers.md#1-the-client-library): maintained on crates.io, TLS through aws-lc-rs, a stream or Unix socket transport for SSH, and a way to stop a statement. + +Microsoft's mssql-tds is checked again each release as a SQL Server client. Today its TLS on Linux goes through OpenSSL and it takes no outside pull requests, so tiberius stays. + +### On the existing drivers + +- **E-01** MariaDB as its own entry on Windows + - [ ] Windows +- **E-02** Test and list Redshift, CockroachDB, YugabyteDB, TiDB, OceanBase, Databend and Valkey (untested today) + - [ ] core + - [ ] Linux + - [ ] Windows +- **E-03** MongoDB sharded clusters and Amazon Keyspaces tested + - [ ] core + +### New drivers, by survey demand + +- **E-04** Oracle · STD · blocked: the oracle crate has one maintainer, no release since 2025-01-02, and needs the proprietary Oracle client; checked again each release + - [ ] core + - [ ] Linux + - [ ] Windows +- **E-05** Snowflake, over the SQL REST API · STD + - [ ] core + - [ ] Linux + - [ ] Windows +- **E-06** BigQuery, over REST · STD + - [ ] core + - [ ] Linux + - [ ] Windows +- **E-07** Trino and Presto, over HTTP · STD + - [ ] core + - [ ] Linux + - [ ] Windows +- **E-08** libSQL/Turso and Cloudflare D1, over HTTP · ADV + - [ ] core + - [ ] Linux + - [ ] Windows +- **E-09** DynamoDB · ADV + - [ ] core + - [ ] Linux + - [ ] Windows +- **E-10** Elasticsearch and OpenSearch · ADV + - [ ] core + - [ ] Linux + - [ ] Windows +- **E-11** Kafka, Neo4j, InfluxDB, etcd, Typesense and the rest of macOS's registry, on user demand + - [ ] core +- **E-12** Dropped: engines added after install on Windows. Linux and Windows link drivers for good (D-03, [core ADR 0025](core/docs/decisions/0025-linux-and-windows-link-their-drivers.md)) + +## Phase 6: Quality bars + +Linux already holds each bar; these bring Windows to it, plus one shared item. + +- [ ] **Q-01** Large-catalog case on Windows: 100 schemas of 500 tables and one database of 50,000; the sidebar, its search and completion within time bounds +- [ ] **Q-02** 1,000,000-row paging and export on Windows, with bounds on time and resident memory +- [ ] **Q-03** The value corpus on Windows: dates at their extremes, decimals, JSON, UUIDs, Unicode and binary read back correctly per engine +- [ ] **Q-04** Kill-during-save recovery test on Windows +- [ ] **Q-05** Windows manual pass: Narrator, the keyboard alone, high contrast, 200% text +- [ ] **Q-06** Cold start and memory budgets in CI on Linux and Windows (survey reason 1); the first Windows launch took 16.7 s with JIT +- [ ] **Q-07** On Windows, offer the crash report on the next launch, as Linux does +- [ ] **Q-08** Security review of the Windows surfaces in `.oss-scanner/threat_model.md` before the first release, as Linux had before beta.1 + +## Phase 7: Sync and teams + +A TablePro sync service on every platform (D-01). macOS keeps iCloud beside it, and the user picks one. It syncs connections and groups, secrets encrypted end to end, saved queries and settings, and Team Library and Team Catalog; iCloud Sync, Team Library and Team Catalog are 3 of the 10 paid features. + +- **T-01** Design ADR: the data model, conflict rules (field by field, as core ADR 0010 merges CloudKit records), end-to-end encryption of secrets and key recovery, whether query history syncs, and iCloud beside the service on macOS + - [ ] core +- **T-02** The service: storage per account and team, the sync API, the entitlement check (core ADR 0016) + - [ ] server +- **T-03** Sync client in the core: pull, push, merge, an offline queue, and the device list + - [ ] core +- **T-04** Connections, groups, tags, colours and SSH profiles, without their secrets + - [ ] Linux + - [ ] Windows +- **T-05** Secrets encrypted on the device before they leave it, never readable on the server + - [ ] core + - [ ] Linux + - [ ] Windows +- **T-06** Saved queries, snippets, favourites and settings + - [ ] Linux + - [ ] Windows +- **T-07** Team Library and Team Catalog: shared connections and queries with roles, as on macOS + - [ ] core + - [ ] server + - [ ] Linux + - [ ] Windows +- **T-08** macOS on the service: everything T-04 to T-07 sync, beside iCloud, a setting to pick one, and a move from iCloud to the service + - [ ] macOS + +## Phase 8: Beyond the market + +Survey features no client covers on every platform, and the macOS app lacks them too, so each has a macOS box. All but G-06 and G-12 were taken (D-05). + +- **G-01** SQL notebooks: SQL and Markdown cells with results (only VS Code mssql since Azure Data Studio retired) + - [ ] core + - [ ] Linux + - [ ] Windows + - [ ] macOS +- **G-02** Scheduled jobs: export, backup or run SQL on a schedule, with a notification (Navicat, DBeaver PRO, TablePlus 27.2) + - [ ] core + - [ ] Linux + - [ ] Windows + - [ ] macOS +- **G-03** Go to definition, find usages and rename in SQL (DataGrip, Navicat 18, dbForge) + - [ ] core + - [ ] Linux + - [ ] Windows + - [ ] macOS +- **G-04** Object dependencies: uses and used by (DataGrip, DBeaver, SSMS, pgAdmin) + - [ ] core + - [ ] Linux + - [ ] Windows + - [ ] macOS +- **G-05** Schema in version control: compare a database against SQL files or migrations (SSMS, VS Code mssql, dbForge, DBeaver PRO) + - [ ] core + - [ ] Linux + - [ ] Windows + - [ ] macOS +- **G-06** Not taken (D-05): a visual MongoDB aggregation pipeline builder (Navicat) +- **G-07** Column profiling: nulls, distinct values, distribution (Navicat 17) + - [ ] core + - [ ] Linux + - [ ] Windows + - [ ] macOS +- **G-08** Pivot tables on a result (dbForge, Navicat) + - [ ] core + - [ ] Linux + - [ ] Windows + - [ ] macOS +- **G-09** Edit tables with no primary key through `ctid` or `rowid`, with a warning (DBeaver, DataGrip) + - [ ] core + - [ ] Linux + - [ ] Windows + - [ ] macOS +- **G-10** Server log viewer and live trace such as Extended Events (SSMS, Querious, MySQL Workbench) + - [ ] core + - [ ] Linux + - [ ] Windows + - [ ] macOS +- **G-11** Run a query every N seconds and chart it (DbVisualizer) + - [ ] core + - [ ] Linux + - [ ] Windows + - [ ] macOS +- **G-12** Not taken (D-05): a browser-hosted edition (CloudBeaver, DbGate, pgAdmin server mode) + +## Decisions + +Answered by the maintainer on 2026-11-13. + +| ID | Question | Decision | +|---|---|---| +| D-01 | Sync and team features on Linux and Windows | A TablePro sync service on every platform, with iCloud kept beside it on macOS ([Phase 7](#phase-7-sync-and-teams)). It reverses the Linux roadmap's earlier "no cloud sync through a TablePro service" | +| D-02 | Paid features on Linux and Windows | One license and one feature gate on all three platforms | +| D-03 | Engines added after install on Windows | No. Linux and Windows link drivers at compile time for good ([core ADR 0025](core/docs/decisions/0025-linux-and-windows-link-their-drivers.md)) | +| D-04 | The bar for the first public Windows release | Phase 0 plus every CORE item in Phase 2, with no public build before | +| D-05 | Which survey gaps to take | All but G-06 and G-12 ([Phase 8](#phase-8-beyond-the-market)) | +| D-06 | Which comes first | Linux 0.1.0, then Phase 1 and Windows ([Order](#order)) | +| D-07 | An Android app | Not now | + +## Out of scope + +- Drivers added after install on Linux and Windows ([core ADR 0025](core/docs/decisions/0025-linux-and-windows-link-their-drivers.md)) +- Embedded scripting: JavaScript, Python, Lua. SQL is enough, and a scripting engine widens the attack surface +- AppImage and Snap ([Linux ADR 0018](linux/docs/decisions/0018-ppa-copr-and-flathub-later.md), [0041](linux/docs/decisions/0041-beta-repositories-and-release-packages.md)) +- KDE-native styling: the Linux app runs with the Adwaita style everywhere +- An Android app, for now (D-07) +- G-06 and G-12 (D-05) + +## Sources + +- Code inventories of `apple/`, `linux/`, `windows/` and `core/` at `8581bd6c7`, and the docs site clone (last commit 2026-10-28, behind the app: Neo4j, InfluxDB, Qdrant, Memcached, StarRocks, masking, Table Health, Live Messages, result tabs and account sign-in have no page yet). +- Survey, from official feature pages and 2025-2026 release notes: + - DataGrip: https://www.jetbrains.com/help/datagrip/2026.3/release-notes-datagrip.html + - DBeaver: https://dbeaver.com/edition/, https://dbeaver.io/news/ + - TablePlus: https://tableplus.com/osx/changelog + - Navicat: https://www.navicat.com/en/navicat-18-highlights + - Beekeeper Studio: https://www.beekeeperstudio.io/features + - DbVisualizer: https://www.dbvis.com/whatsnew + - pgAdmin: https://www.pgadmin.org/news/ + - SSMS 22: https://learn.microsoft.com/ssms/release-notes-22 + - VS Code mssql: https://learn.microsoft.com/en-us/sql/tools/visual-studio-code-extensions/mssql/mssql-extension-visual-studio-code + - DbGate: https://www.dbgate.io/features + - Postico 2: https://releases.eggerapps.at/postico2/changelog + - Sequel Ace: https://github.com/Sequel-Ace/Sequel-Ace/releases + - Also HeidiSQL, dbForge (search summaries only, devart.com refuses fetches), MySQL Workbench, Antares, Querious, Chat2DB. +- Reasons users switch: about 20 Hacker News threads and GitHub trackers, for example https://news.ycombinator.com/item?id=39660592, https://news.ycombinator.com/item?id=46078571, https://github.com/TablePlus/TablePlus/issues/2669. diff --git a/core/AGENTS.md b/core/AGENTS.md index 46cfbbea1c..bfbe0036dc 100644 --- a/core/AGENTS.md +++ b/core/AGENTS.md @@ -9,7 +9,7 @@ This is the guide for work under `core/`. The root `AGENTS.md` holds the rules e 1. **Tests define behavior**, as in the root `AGENTS.md`. 2. **No GUI, no platform service.** A core crate depends on no GUI toolkit and on no platform crate. What a platform does its own way comes in as a value or a trait the app passes in, or sits behind a `cfg` split; `ARCHITECTURE.md`, Platforms, lists both. 3. **Every target builds.** A change keeps the crates building for Linux, Windows (x64 and Arm64) and macOS. `std::os::unix`, `rustix`, `/proc` and Unix sockets go behind `cfg(unix)` or `cfg(target_os = "linux")`, with the other platforms' answer beside them. -4. **One-directional crates.** `ARCHITECTURE.md` has the graph. Drivers are linked in at compile time until the driver ABI lands (`docs/decisions/0004-driver-plugin-abi.md`). +4. **One-directional crates.** `ARCHITECTURE.md` has the graph. Linux and Windows link their drivers at compile time for good (`docs/decisions/0025-linux-and-windows-link-their-drivers.md`); the driver ABI in `docs/decisions/0004-driver-plugin-abi.md` is for macOS. 5. **Errors carry a code, not a sentence.** Each boundary error has a stable `code()` and typed fields; an app words it. No translation catalog lives here. 6. **Decisions are recorded.** One that holds for every platform goes in `docs/decisions/` (`docs/decisions/README.md`). diff --git a/core/docs/decisions/0004-driver-plugin-abi.md b/core/docs/decisions/0004-driver-plugin-abi.md index 2bc5d6669e..5ac509fa3b 100644 --- a/core/docs/decisions/0004-driver-plugin-abi.md +++ b/core/docs/decisions/0004-driver-plugin-abi.md @@ -1,6 +1,6 @@ # 0004: Downloadable drivers over a small C ABI of our own -- **Status**: Accepted +- **Status**: Accepted; superseded for Linux and Windows by 0025 - **Date**: 2026-11-02 ## Context diff --git a/core/docs/decisions/0025-linux-and-windows-link-their-drivers.md b/core/docs/decisions/0025-linux-and-windows-link-their-drivers.md new file mode 100644 index 0000000000..f0806ae23f --- /dev/null +++ b/core/docs/decisions/0025-linux-and-windows-link-their-drivers.md @@ -0,0 +1,32 @@ +# 0025: Linux and Windows link their drivers at compile time for good + +- **Status**: Accepted +- **Date**: 2026-11-13 + +## Context + +[0004](0004-driver-plugin-abi.md) chose downloadable drivers on every platform over a small C ABI, superseded [Linux ADR 0001](../../../linux/docs/decisions/0001-no-plugin-system.md), and had the first Windows release link its 9 drivers until the ABI lands. The ABI has not landed, so every app on the core links its drivers today. + +The roadmap asked whether Windows should take engines after install ([ROADMAP.md](../../../ROADMAP.md#decisions), D-03). The maintainer answered on 2026-11-13. + +## Decision + +The Linux and Windows apps link every driver at compile time and never load one at runtime; 0004 still holds for macOS. + +## Rationale + +- Linux ADR 0001's reasons hold for both apps: on macOS, plugin loading, ABI mismatches and stale registry data trace to about 15% of issues, and plugin validation and signing take real time. +- 0004 left open risks that only the downloading apps carry: Microsoft Store Policy 10.2.2 on code included at runtime, `dlopen` inside the Flatpak and loading from an MSIX package's `LocalState`, all untested. +- Both apps ship whole through channels that update them: the PPA, COPR and the Flatpak repositories on Linux ([Linux ADR 0041](../../../linux/docs/decisions/0041-beta-repositories-and-release-packages.md)), MSIX and winget on Windows ([Windows ADR 0005](../../../windows/docs/decisions/0005-distribution.md)). + +## Consequences + +- Linux ADR 0001 is in force again. 0004 is superseded for Linux and Windows and stays accepted for macOS, which moves its engines to the core under [0010](0010-macos-on-the-core.md). +- A new engine reaches Linux and Windows only in an app release, the cost 0004 named under "Static drivers only". +- The drivers' `plugin` feature and the C ABI serve macOS alone. A Linux or Windows build never turns the feature on. +- Windows signs no driver DLLs and checks none with `WinVerifyTrust`. + +## Alternatives considered + +- **0004 as written.** Downloads on every platform. Lost on the reasons above. +- **Downloads on Windows only, Linux linked.** The roadmap's other option. Windows would still carry the Store policy risk and DLL signing, for engines that Linux, on the same core, ships in releases. diff --git a/core/docs/decisions/README.md b/core/docs/decisions/README.md index 331672cfe2..b0556c6abb 100644 --- a/core/docs/decisions/README.md +++ b/core/docs/decisions/README.md @@ -11,7 +11,7 @@ The format, the statuses and how a later ADR changes an earlier one follow [the | [0001](0001-shared-core.md) | One shared Rust core, a native UI per platform | Accepted; SSH on Windows amended by 0008 | The UI-free crates move to `core/crates` and build on Linux, Windows and macOS; each app keeps a native UI and passes its platform services in. | | [0002](0002-uniffi-bindings.md) | One UniFFI API for Swift and C#, with a C ABI beside it | Accepted | UniFFI proc macros in the core; Swift through UniFFI's generator and C# through uniffi-bindgen-cs v0.11.1+v0.31.0, each with a thin layer for cancel, progress, streams and off-UI-thread calls; `extern "C"` and csbindgen for hot paths and as the fallback. | | [0003](0003-result-windows-for-native-grids.md) | The core owns the result set, and a native grid pulls windows of text | Accepted; amended by 0007; the row limit as the bound on memory superseded by 0020 | A columnar result set in the core; one packed UTF-8 window per visible range with exact, locale-free text; one coalesced rows-arrived callback; Arrow only for bulk export. | -| [0004](0004-driver-plugin-abi.md) | Downloadable drivers over a small C ABI of our own | Accepted | A static descriptor, minor-version negotiation, protobuf messages, Arrow C Data rows, a runtime per driver and `catch_unwind` at every export; signed per platform, never unloaded, linked statically on iOS. | +| [0004](0004-driver-plugin-abi.md) | Downloadable drivers over a small C ABI of our own | Accepted; superseded for Linux and Windows by 0025 | A static descriptor, minor-version negotiation, protobuf messages, Arrow C Data rows, a runtime per driver and `catch_unwind` at every export; signed per platform, never unloaded, linked statically on iOS. | | [0005](0005-sql-server-transport.md) | SQL Server on tiberius everywhere, with Kerberos added and ODBC as a Windows option | Accepted | tiberius on every platform with SSPI Negotiate added in a fork, Entra ID tokens from the core, and an optional Windows connection type over an installed ODBC Driver 18 for Always Encrypted; msodbcsql18 is never bundled. | | [0006](0006-connection-library.md) | The connection library holds a group tree, manual order and favourites | Accepted; how the Linux app shows groups superseded by linux 0032, the version 2 upgrade by linux 0033 | Groups form a tree by id, connections and groups carry an explicit order, favourites are one ordered list; version 2 group names become top-level groups. | | [0007](0007-sorting-a-result.md) | A sort names its column by name or position, else the core sorts the rows held | Accepted | `sort_reference` names a unique plain column, else its position on PostgreSQL, SQLite, SQL Server and DuckDB; otherwise, and for a statement that cannot run again, `value::order` sorts the rows held, which `ResultSet::sorted` gives the FFI as a view. | @@ -32,3 +32,4 @@ The format, the statuses and how a later ADR changes an earlier one follow [the | [0022](0022-browsing-through-the-ffi.md) | A table page is read on the session with its filter bound, and structure, definitions, export and history cross the FFI | Accepted | `read_table_page` builds the page with the filter, binds its values and reads it with `read_page` on a pooled connection as run events; `table_structure`, `object_definition`, `export_rows`, `export_table` and `Core::history` give the Linux app's reads to an app on the FFI. | | [0023](0023-mcp-client-setup-from-one-catalog.md) | Both apps set up MCP clients from one catalog | Accepted | `core/crates/mcp/clients.json`, bundled, lists each client per OS; install by deeplink, then the client's CLI by argv, then a comment-keeping splice into its config file with a `.tablepro-backup`, else copy; macOS writes the stdio bridge and no token, Linux the URL and token, and the Linux server serves only the user's own account; brand marks from Simple Icons or the brand, still their owners' trademarks. | | [0024](0024-copy-rows-through-copy-in.md) | An imported COPY block loads through PostgreSQL's copy-in | Accepted | The `ScriptReader` gives a `COPY ... FROM stdin` then its rows as written in pieces of at most 256 KiB, up to `\.`, which is never sent; `run_sql_import` streams them through `EditorSession::copy_in`, in the import's transaction or the driver's own; binary is refused; tokio-postgres comes from a fork with the copy-in fix (rust-postgres#1402) until a release has it. | +| [0025](0025-linux-and-windows-link-their-drivers.md) | Linux and Windows link their drivers at compile time for good | Accepted | The Linux and Windows apps link every driver at compile time and never load one at runtime, so a new engine reaches them in an app release; 0004's downloadable drivers stay for macOS, and Linux 0001 is in force again. | diff --git a/linux/AGENTS.md b/linux/AGENTS.md index 302fc7ada8..44195b773f 100644 --- a/linux/AGENTS.md +++ b/linux/AGENTS.md @@ -9,7 +9,7 @@ This is the guide for work under `linux/`. The root `AGENTS.md` holds the rules 1. **Tests define behavior**, as in the root `AGENTS.md`. 2. **Native only.** GTK 4 and libadwaita, used the way the GNOME Human Interface Guidelines describe, with the widget the toolkit provides before anything drawn by hand. No web views, no cross-platform toolkit. 3. **One-directional crates.** The domain crate (`tablepro-core`) never imports the GUI or a driver, and a new database engine is one crate. `core/ARCHITECTURE.md` has the graph. -4. **Drivers are linked in at compile time** until the driver ABI lands (`core/docs/decisions/0004-driver-plugin-abi.md`). +4. **Drivers are linked in at compile time**, for good (`core/docs/decisions/0025-linux-and-windows-link-their-drivers.md`). 5. **Decisions are recorded.** A change that reverses a decision in `docs/decisions/` adds an ADR that supersedes it; the old one changes only its Status line (`docs/decisions/README.md`). ## Map diff --git a/linux/README.md b/linux/README.md index 8da355c712..40ad20d27d 100644 --- a/linux/README.md +++ b/linux/README.md @@ -4,7 +4,7 @@ Native Linux database client, the Linux sibling of the macOS TablePro app. It bu ## Status -The public beta is available as [0.1.0-beta.3](https://github.com/TableProApp/TablePro/releases/tag/linux-v0.1.0-beta.3). It connects to 11 engines: PostgreSQL, MySQL, MariaDB, SQL Server, ClickHouse, Cassandra, ScyllaDB, SQLite, DuckDB, Redis and MongoDB. [Supported servers](#supported-servers) lists the tested versions and limits. A window holds several connection sessions side by side in one tab view. Follow the [install guide](https://docs.tablepro.app/linux/install) for the beta PPA, COPR and Flatpak channels. [ROADMAP.md](ROADMAP.md) lists what is built, what is not, and the release criteria. +The public beta is available as [0.1.0-beta.3](https://github.com/TableProApp/TablePro/releases/tag/linux-v0.1.0-beta.3). It connects to 11 engines: PostgreSQL, MySQL, MariaDB, SQL Server, ClickHouse, Cassandra, ScyllaDB, SQLite, DuckDB, Redis and MongoDB. [Supported servers](#supported-servers) lists the tested versions and limits. A window holds several connection sessions side by side in one tab view. Follow the [install guide](https://docs.tablepro.app/linux/install) for the beta PPA, COPR and Flatpak channels. [docs/features.md](docs/features.md) lists what is built, the repository's [ROADMAP.md](../ROADMAP.md) what is not, and [docs/releasing.md](docs/releasing.md#release-criteria) the release criteria. ## Supported servers @@ -608,7 +608,9 @@ From the 30th day you use TablePro without a license, a toast asks whether you w | Topic | File | |---|---| | Layered architecture, crate boundaries, dependency rules | [ARCHITECTURE.md](ARCHITECTURE.md) | -| What is built, the backlog and the release criteria | [ROADMAP.md](ROADMAP.md) | +| What is built | [docs/features.md](docs/features.md) | +| The work left, for Linux, Windows and the core | [ROADMAP.md](../ROADMAP.md) | +| The 0.1.0 release criteria | [docs/releasing.md](docs/releasing.md#release-criteria) | | Contributing: dev workflow, lint, commits, PRs | [CONTRIBUTING.md](CONTRIBUTING.md) | | **Adding a database driver** | [docs/adding-drivers.md](docs/adding-drivers.md) | | State management: windows, sessions, background work | [docs/state-management.md](docs/state-management.md) | diff --git a/linux/ROADMAP.md b/linux/ROADMAP.md index a8380d2c7e..b3a46a8d6d 100644 --- a/linux/ROADMAP.md +++ b/linux/ROADMAP.md @@ -1,258 +1,3 @@ # Roadmap -**Status, 2026-11-08**: [0.1.0-beta.3](https://github.com/TableProApp/TablePro/releases/tag/linux-v0.1.0-beta.3) is published on GitHub Releases, the beta PPA, the beta COPR project and the beta Flatpak repository ([README](README.md#betas)). 0.1.0 waits on [release criteria](#release-criteria) 1, 8 and 10. The [backlog](#backlog) lists the remaining work and known issues. - -beta.2 was tagged but never published: [release run 42382067978](https://github.com/TableProApp/TablePro/actions/runs/42382067978) failed before publishing. [#4093](https://github.com/TableProApp/TablePro/pull/4093) fixed the failure for beta.3. - -The app runs on GNOME 50 ([ADR 0015](docs/decisions/0015-gnome-50-platform-floor.md)) and connects to nine engines, each a crate linked in at compile time ([ADR 0001](docs/decisions/0001-no-plugin-system.md)): [PostgreSQL](docs/drivers/postgresql.md), [MySQL and MariaDB](docs/drivers/mysql.md), [SQL Server](docs/drivers/sql-server.md), [ClickHouse](docs/drivers/clickhouse.md), [Cassandra and ScyllaDB](docs/drivers/cassandra.md), [SQLite](docs/drivers/sqlite.md), [DuckDB](docs/drivers/duckdb.md), [Redis](docs/drivers/redis.md) and [MongoDB](docs/drivers/mongodb.md). - -## Implemented - -### Connections - -| Capability | Detail | -|---|---| -| Saved connections | Create and edit (the name included), duplicate with the secrets carried to the copy, delete with or without the connection's history | -| Groups, favourites and colours | Groups nest 3 levels deep and show as a tree in the library's order, empty ones too. New Group, New Subgroup, Rename and Delete from the menus; a delete asks first. A connection or a group moves by drag and drop or from its menu (Move to Group, Move Group To, Move Up, Move Down). Favourites and the 5 connections opened last lead the picker; favourites reorder the same way | -| Tags and icons | Several named tags per connection, each with a colour, from the row's menu or the connect dialog, shown after the name and read with the row's description; Manage Tags renames, recolours and deletes them. An icon from a fixed set shows in the row and beside the window title | -| Search | The connection list's search (Ctrl+F, or start typing) matches the name, host, database, user, driver, the names on the group's path and tag names | -| Import and export | A JSON file with no secrets in it, tags and icons included. On import, an entry with the same id and the same settings updates its name, colour, group, tags and icon; any other is added as a new connection. Tags are matched by id, then by name, so a second import adds none | -| Connection URLs | A URL pasted at the top of a new connection fills the form: the engine, host, port, user, database and TLS mode, the authentication database, a DNS seed list and a replica set's hosts, and the password, kept in the Secret Service with Remember Password on. libpq, MySQL, MongoDB, Redis and Valkey, ClickHouse and Cassandra URLs, SQL Server's JDBC form and SQLite and DuckDB file URLs are read ([core `connection_url`](../core/crates/core/src/connection_url/mod.rs)) | -| Unix sockets | PostgreSQL, MySQL and MariaDB on this computer through the server's socket, for peer, `auth_socket` and `unix_socket` logins: a folder for PostgreSQL, the socket file for MySQL, found in the distribution's usual place. The Flatpak sees the sockets under `/run/postgresql` and `/run/mysqld` ([ADR 0035](docs/decisions/0035-flatpak-local-database-sockets.md)) | -| Test before saving | Test connects once and reports, then disconnects | -| Passwords | Kept in the Secret Service; a prompt asks when one is missing or refused, with Remember Password | -| Safe Mode | A level per connection, set in the connect dialog or the main menu while connected and saved back to the connection. Off asks before DROP, TRUNCATE, and DELETE or UPDATE without WHERE. Confirm Writes also asks before every other write from the editor, a grid save, a structure save, a CSV import, a SQL file import, or a drop, truncate or create from the sidebar, showing the SQL, or the file, and the connection, with Cancel the default. Read-Only refuses every editor statement that does not read, and opens the connection read-only: SQLite, DuckDB and ClickHouse refuse writes at the engine, PostgreSQL and MySQL run in read-only transactions, SQL Server relies on the login, with the app's own reads in a rolled-back transaction, and Cassandra and ScyllaDB rely on the login. A statement is a read only when its engine's grammar shows it reads, each statement of a script on its own. Moving to or from Read-Only reconnects the window | -| Query timeout per connection | Custom Query Timeout in the connect dialog sets the editor's timeout for that connection in place of the one in Preferences, from the next connect; 0 turns it off. The app's own calls keep their fixed limits: 15 seconds for metadata, 60 for a page or a count, 120 for a row save or a CSV import, none for a schema change or an export, and on the server 60 for a table-tab statement and 10 for a lock wait | -| Database files | SQLite and DuckDB: choose a file, create a new one, open one from Files or a terminal, where the file's header picks the engine, find a moved one with Locate, and choose read-only or read-write for one on a network or FUSE filesystem | -| Kerberos for SQL Server | From the ticket cache, in the Flatpak through the KCM socket | -| Health and reconnect | A banner while the connection is lost, reconnect with a backoff from 5 to 60 seconds, and metadata, page and count reads replayed once after it; writes are never replayed | -| Cancel on the server | Stopping a query stops the statement on the server (in process on SQLite); a ClickHouse mutation already running in a save is left to finish. CQL has no stop, so on Cassandra and ScyllaDB the app stops waiting and the server runs the statement to its own timeout | - -### SSH - -| Capability | Detail | -|---|---| -| System OpenSSH client | One ControlMaster per connection ([ADR 0013](docs/decisions/0013-openssh-client-transport.md)); empty fields come from `~/.ssh/config` | -| Jump hosts | A ProxyJump chain, passed to `ssh -J` | -| Authentication | Agent, private key, password and keyboard-interactive; prompts go through the app's askpass helper | -| Host keys | An unknown or changed key is shown with its SHA256 fingerprint before connecting, even where ssh_config says accept-new or no. A changed key can be replaced in known_hosts, except under StrictHostKeyChecking yes, where the user fixes known_hosts outside the app and retries. A revoked key is refused | - -### TLS - -| Capability | Detail | -|---|---| -| Modes | Disable, Prefer (PostgreSQL and MySQL), Require and Verify full; a new connection starts on the mode the engine's own client starts on ([core ADR 0014](../core/docs/decisions/0014-tls-mode-of-a-new-connection.md)) | -| Certificates | CA file, client certificate and key (every network engine but SQL Server), and a server name override (MySQL only through an SSH tunnel) | -| Remedies | A TLS failure says what went wrong. An unknown issuer jumps to the CA file, a name mismatch to the server name, and a server that refuses or requires TLS to the Encryption row | - -### Browse and edit - -| Capability | Detail | -|---|---| -| Data grid | A virtualized `GtkColumnView` with keyboard-focusable cells, pages of 100 to 10,000 rows, and a pager with an exact or estimated row count; a table of about 100,000 rows or fewer is counted on its own, a larger one offers Count Rows | -| Filters | Per-column operators, a raw WHERE fragment checked as one expression, match any or all; binary columns compare to `0x` hex. Kept per table, and per tab across a restart or a reopen. On Cassandra and ScyllaDB only the operators the server evaluates, matched all, with `ALLOW FILTERING` | -| Sorting | A header click sorts tables on the server and query results in the grid, one column at a time. A Cassandra or ScyllaDB table keeps the server's order, and pages by its paging state | -| Cell editing | Editors by column kind: inline text, a multi-line editor, a calendar for dates and, in Row Details, a clock for times, a toggle for booleans, JSON checked before saving; values are edited from their exact text, never from what the cell displays. Tables with a primary key, in a table tab or as a query result that reads one table with its whole key ([ADR 0036](docs/decisions/0036-editing-query-results.md)); key, generated and auto-increment columns, and binary, spatial, array and composite values, are read-only | -| Rows | Insert, duplicate and delete; Paste (Ctrl+V) adds tab-separated rows from the clipboard, filling the columns from the focused one or by a header's names, or edits the focused cell with one value, and asks first above 1,000 rows, up to 100,000; Set NULL and Empty, and DEFAULT on a new row; undo and redo; save or discard pending changes, and stop a save. On ClickHouse, Cassandra and ScyllaDB a save is not atomic, and Stop takes effect between statements | -| Server-computed values | A date, time or timestamp cell takes the engine's own `NOW()`, `CURRENT_TIMESTAMP`, `CURRENT_DATE` and the like, typed in any letter case or picked from the cell menu, and a saved row's cell takes DEFAULT where the engine has `SET c = DEFAULT` (PostgreSQL, MySQL and MariaDB, SQL Server, DuckDB). Only each engine's own list is offered, which on DuckDB is `now()` alone, since the bundled build has no ICU extension; the save writes the expression into the statement, so the Confirm Writes review and the history show it as written | -| Bulk delete | Deleting 10 rows or more asks first, unless Confirm Before Deleting Rows is off in Preferences | -| Copy | Copy; Copy As rows, with headers, CSV with or without headers, JSON, JSON Lines, Markdown, a text table, IN clause or one row of SQL values, and INSERT with or without generated keys in an editable table tab; Copy Column Name; Show Row as JSON | -| Foreign keys | Open Referenced Row (Ctrl+J) on a key cell opens the table it points at in a new tab, filtered on every column of the key; Show Referencing Rows on a saved row opens a table whose key points at it. A tab already showing those rows comes to the front | -| Column layout | Order, hidden columns and widths kept per table; a column added since goes last and a dropped one keeps its place. A header drag, or Move Column Left and Move Column Right in the cell menu (Alt+Left and Alt+Right), reorders them; Widen Column and Narrow Column (Shift+Alt+Right and Shift+Alt+Left) resize them; Reset Columns in the Columns dialog goes back to the table's own order | -| CSV import | Into an existing table, with a column mapping, in one write batch (one transaction where the engine has them), up to 64 MiB | -| Sidebar | Tables (partitioned ones included), views, materialized views and foreign tables by schema, with search and Refresh, read again after the editor runs DDL, Open in New Tab and Show CREATE TABLE; Edit Structure, Import CSV, Truncate Table and Drop Table for tables, Delete All Documents for collections; New and Drop Schema, and New and Drop Database (Keyspace on Cassandra), on every engine that has them, never offered for a system object or the session's own database; empty schemas listed | -| Routines and triggers | Functions, procedures and sequences in the sidebar after each schema's tables, and triggers with the table each fires on, on every engine that has them. Opening one shows its definition read-only, with Copy and Open in Editor; every overload of a PostgreSQL function name is shown | -| ER diagram | Show ER Diagram in a table's menu or on a schema's heading opens the schema's tables as cards and their foreign keys as lines in crow's foot notation, read two tables at a time with Stop. Pan, zoom, Best Fit, drag tables, Reset Layout, and PNG and SVG export. Each table is a list item the keyboard and a screen reader reach: Tab and the arrow keys move between tables, Enter opens one, Alt+arrows move it, and its description names its columns and the tables it joins | - -### Structure - -| Capability | Detail | -|---|---| -| Table definition | Columns, indexes, foreign keys and column comments | -| Index statements | Show CREATE INDEX and Copy CREATE INDEX on each index the table has, as the statement that makes it again: the server's own text on PostgreSQL, MySQL, MariaDB, SQLite and DuckDB, and written from the catalog, storage and options included, on SQL Server, ClickHouse, Cassandra and ScyllaDB. An index a constraint owns, such as a primary key or a UNIQUE constraint, a partition's index attached to its parent's and a ClickHouse sorting key offer none. Show CREATE TABLE uses the same statements | -| Changes | Create, rename and drop tables; add, drop and rename columns, and change their type, nullability, default, comment, primary key and auto-increment; add and drop indexes (column keys, unique, descending) and foreign keys. ClickHouse creates no tables, indexes or foreign keys and changes no primary key or auto-increment; SQL Server changes no auto-increment; SQLite keeps no column comments; Cassandra and ScyllaDB take no default or NOT NULL, and rename only key columns | -| Review | The SQL is previewed, and a save that loses data or can stop halfway is reviewed before it runs | -| SQLite rebuilds | Changes SQLite cannot ALTER rebuild the table in one transaction, keeping its rows, indexes, triggers, the views and triggers that name it and its AUTOINCREMENT counter, with foreign keys checked before commit. SQLite itself checks the views and triggers made again; a trigger that lists a dropped column or inserts by position is refused before Save | - -### Keys - -| Capability | Detail | -|---|---| -| Key list | A Redis connection lists the keys of its numbered database with their types, read with `SCAN`; the search goes to the server, plain text matching anywhere in a key and text with `*`, `?` or `[` as a glob. A banner says when the list stops at its 5,000-key limit | -| Key tab | A key opens by type: a string's value, a hash's fields, a list by index, a set's members, a sorted set with scores and a stream's entries, 500 at a time with Load More, under its length and expiry | -| Commands | The editor takes Redis commands, one per line, and shows each reply as redis-cli lays it out; `MULTI` is tracked as a transaction. A waiting command stops with `CLIENT UNBLOCK`. Read-Only refuses every command that is not a read before it is sent ([redis.md](docs/drivers/redis.md)) | - -### Documents - -| Capability | Detail | -|---|---| -| Connecting | A MongoDB connection reaches one host directly, a replica set from its hosts and name, a replica set or cluster through its DNS seed list (`mongodb+srv://`), or one host through SSH, with an optional authentication database | -| Collections | Databases list their collections and views. A collection opens in a table tab: its top-level fields as columns, `_id` first, nested documents and arrays as JSON. Paging, filters, the raw filter as a query document, sorting, editing a field, inserting and deleting run as mongosh calls with bound values, shown in the history and the Safe Mode review ([mongodb.md](docs/drivers/mongodb.md)) | -| Statements | The editor takes mongosh statements (`find`, `aggregate`, the writes, `runCommand`, `use`, `show`) and shows documents one per row. A running statement stops with `killSessions`. Read-Only refuses every statement that is not a read, `$out` and `$merge` included, before it is sent | - -### SQL editor - -| Capability | Detail | -|---|---| -| Editing | GtkSourceView with SQL highlighting, a scheme that follows the light or dark style, and toggle comment | -| Completion | Tables, views, columns, schemas, functions and keywords, with aliases resolved | -| Snippets | SELECT, INSERT, UPDATE, DELETE, a join (none on Cassandra and ScyllaDB), CREATE TABLE and CREATE INDEX per engine, and the user's own in GtkSourceView's format from a folder read again when it changes, a snippet scoped to one engine or to all; offered in completion, with Tab between stops ([README](README.md#snippets)) | -| Formatter | Format SQL, leaving a statement as typed when formatting would change its tokens | -| Scripts | Split per dialect (`DELIMITER`, `GO` and `GO n`, routine and trigger bodies) and sent a statement at a time, or a batch at a time on SQL Server; each result set, row count, notice or error is its own entry, and a failure stops the script except on SQL Server. Run Selection, and run the statement at the cursor | -| Find and replace | Ctrl+F and Ctrl+H, with case, whole word and regular expressions | -| Files | Open a .sql file into the editor (Ctrl+O) or drop one on it, and save to it (Ctrl+S, or Save As with Ctrl+Shift+S) | -| Results | Several result sets per run, a limit of 10,000 rows per result and 100,000 per run with a banner and Export All, and Go to Error | -| Drafts | Each editor tab's text is kept, and a connection's tabs (table tabs with page and sort, structure and editor tabs) reopen when it opens | -| Multiple cursors | Ctrl+D for the next match, Ctrl+Shift+L for every match, Shift+Alt+Up and Down for the lines above and below, Ctrl+click; typing, deleting, pasting and moves at every cursor, one undo for all of them ([README](README.md#multiple-cursors)) | -| Vim mode | GtkSourceView's Vim emulation, off by default, with the mode and pending command under the text; `:w`, `:e`, `:q`, `:wq` and `:x` act on the tab, and the editor's Ctrl shortcuts work in every mode ([README](README.md#vim-keybindings)) | - -### History and saved queries - -| Capability | Detail | -|---|---| -| Query history | A SQLite database with full-text search, filters by connection, time and status, pins, export as SQL or CSV, and a retention period | -| What is recorded | Editor runs, and the SQL the app runs for grid saves, structure saves and successful imports; a run that can carry a password or connection secret, or whose text does not tokenize, is not recorded, and recording can be turned off | -| Show in Files | For the history database, from the history dialog and Preferences | -| Saved queries | Saved from the editor against a connection, listed by connection with the active one first, and opened in a new tab or the current one | - -### Export - -| Capability | Detail | -|---|---| -| Formats | CSV with its options, JSON, Markdown, HTML, XML, Excel, and SQL INSERT from a table tab | -| Scope | From a table tab, the current page with its pending edits, or every saved row under the filter and sort. From the editor, the rows shown, or every row by running the statement again on a separate read-only connection without the tab's USE or SET; a statement that writes is refused | -| Running | Off the GTK thread with progress and Stop; closing or quitting asks about a running export | -| Database | Export Database in the main menu writes a whole database or one schema to a `.sql` or `.sql.gz` file: tables, views, routines and triggers, and every table's rows as multi-row INSERTs, in the order `pg_dump` and `mysqldump` use, so `psql`, `mysql`, `sqlcmd`, `sqlite3` and `clickhouse-client` load it as well as Import SQL File does. Read in process from the connection, not by calling those tools ([core ADR 0011](../core/docs/decisions/0011-sql-dump-and-import-in-process.md)); not offered on Redis, MongoDB, Cassandra and ScyllaDB ([README](README.md#export-a-database-and-import-a-sql-file)) | - -### Import - -| Capability | Detail | -|---|---| -| SQL files | Import SQL File in the main menu runs a `.sql` or `.sql.gz` file of any size on an editor session of its own, split as the engine's client splits it (`DELIMITER`, `GO n`, routine bodies, dollar quotes), with progress, Stop and a summary of what failed and where. pg_dump's `COPY ... FROM stdin` rows load through the copy protocol, text or CSV, and its `\restrict` lines are passed over | -| Errors and transactions | Stop at First Error, or run the rest and list each failure with its line. On PostgreSQL, SQL Server, SQLite and DuckDB the file can run as one transaction, so a failure or Stop undoes it all; MySQL, MariaDB and ClickHouse commit each statement as it runs. Safe Mode Read-Only offers neither import, and the import dialog is the one question Confirm Writes asks for the whole file | - -### Windows and sessions - -| Capability | Detail | -|---|---| -| Sessions in a window | A window holds several connection sessions, their tabs side by side in one tab view, and a connection already open brings its window forward ([ADR 0028](docs/decisions/0028-sessions-share-a-window.md)) | -| One instance | A second launch presents the running app; New Window (Ctrl+Shift+N) opens a picker | -| Tabs | `AdwTabView` with the tab overview and split header bars, adapting down to 360×294 | -| Session restore | The windows of saved connections and database files open at quit open again at launch (Restore Session, on by default), also after New Window or a quit during the restore | -| Closing safely | Unsaved edits, a save in flight or of unknown outcome, an open editor transaction, or a running export ask before a window closes or the app quits; logout waits while any of those holds, and suspend while a save runs or an export writes | -| Notifications | Work that finishes in a tab you are not looking at sends a notification | -| Preferences | Restore session, page size, the bulk delete confirmation, query history, editor font and scheme, Vim keybindings, query timeout, the AI assistant, the MCP server | -| Shortcuts and About | A shortcuts dialog, and About from the metainfo with third-party licenses and debug info | - -### AI assistant - -| Capability | Detail | -|---|---| -| Providers | Off until a provider is chosen in Preferences: Anthropic, OpenAI, or Ollama and other servers through the OpenAI-compatible protocol. Keys in the keyring; the model picked from the provider's list ([ADR 0022](docs/decisions/0022-ai-assistant-and-mcp-server.md)) | -| Chat | A pane beside the tabs (Ctrl+Alt+A) with streamed replies, Stop, Retry and New Conversation; code blocks with Copy and Insert. A conversation carries the editor's SQL and the structure of the tables it names, and reads no rows | -| Editor | Explain, Review and Optimize the selection or the statement at the cursor, Fix with AI on a failed statement, and suggestions while typing (off by default) that Tab accepts | -| AI policy | Per connection: Ask Each Time (the default) asks before the first request in a window, Allow sends without asking, Never sends nothing from the connection | - -### MCP server - -| Capability | Detail | -|---|---| -| Server | Streamable HTTP on `127.0.0.1` only, off until turned on in Preferences, with a port preference and a bearer token kept in the keyring ([ADR 0022](docs/decisions/0022-ai-assistant-and-mcp-server.md)) | -| External Clients | A level per connection: Blocked hides it, Read Only (the default) lets clients read, Read & Write lets them write after the user approves each statement in Safe Mode's dialog. Safe Mode Read-Only refuses every client write | -| Tools | List connections, open one in a window, list schemas and tables, describe a table and show its DDL, browse and count rows with filters, and run one statement; runs go into the query history | - -### TablePro account - -| Capability | Detail | -|---|---| -| Sign-in | Preferences > Account signs in to a TablePro account through the browser, as on macOS; the sign-in is kept in the keyring ([ADR 0038](docs/decisions/0038-account-page-and-license-ask.md)) | -| Plan, devices and teams | The plan and its status, each paid feature this platform has, included or not by the plan ([ADR 0042](docs/decisions/0042-account-page-lists-this-platforms-features.md)), the account's devices with Remove, the device limit dialog, teams, and offline files for a computer with no internet | -| License ask | From the 30th day of use without a license, a toast asks whether you would buy one, then at most every 90 days | -| Usage data | On by default, as on macOS: the clients.md events go to PostHog until Preferences > General > Privacy turns it off ([ADR 0039](docs/decisions/0039-usage-data.md)) | - -### Packaging and platform - -| Capability | Detail | -|---|---| -| Flatpak | The Devel manifest builds on GNOME 51 for x86_64 and aarch64 with every Meson suite in the sandbox, and is linted, in the nightly Linux run; the release manifest builds the Flatpak a release signs into `flatpak.tablepro.app` and bundles for GitHub, offline from the release tarballs; CI tests it, signs it into test repositories, then installs, starts, updates and switches branches on Ubuntu 22.04, 24.04 and 26.04 ([ADR 0041](docs/decisions/0041-beta-repositories-and-release-packages.md)) | -| .deb and .rpm | Ubuntu 26.04 and 26.10 and Fedora 44 and 45, built offline in CI the way Launchpad and COPR build them, linted, then installed and started in fresh containers; a `linux-v*` tag publishes them on GitHub Releases, uploads to the PPA and starts the COPR build, a beta tag to the beta ones ([ADR 0018](docs/decisions/0018-ppa-copr-and-flathub-later.md), [ADR 0041](docs/decisions/0041-beta-repositories-and-release-packages.md)) | -| Desktop integration | Desktop file with Open With for SQLite files, D-Bus activation, a man page, metainfo with screenshots, and SVG icons | -| Translations | Vietnamese ships. The app's own strings go through gettext, and CI fails when `POTFILES.in` is stale or a translation loses a placeholder. CI builds the template with gettext 1.0 and publishes it from main and with each release; translators send pull requests against `po/*.po` ([po/README.md](po/README.md#where-translators-work)) | -| Logs | stderr, which the session journals, with JSON lines on request. A panic also writes a crash report under `$XDG_STATE_HOME`, offered with Show Report on the next launch | -| Tests | Unit, gtk (with an accessibility audit of the picker, the connect pages, the workspace, the connect dialog and every preferences page), data and packaging suites; connection, DDL and TLS conformance, a CSV and SQL INSERT export round trip, a copy and paste round trip, and a database dump loaded back through Import SQL File and dumped again to the same file, on every SQL engine, keyspace and TLS conformance on Redis, and document and TLS conformance on MongoDB; Docker jobs for PostgreSQL with PgBouncer, MySQL and MariaDB, SQL Server, ClickHouse, Cassandra and ScyllaDB, Redis, MongoDB, SSH, the session and the grid save ([testing.md](docs/testing.md)); every critical audit finding has named guards ([regression-tests.md](docs/regression-tests.md)) | - -## Backlog - -Remaining work and known issues, in no order. - -### Connections - -- Kerberos against a service outside the client's realm, which needs an SPN override in tiberius. -- Report when Remember Password cannot save a password because there is no default keyring ([#4098](https://github.com/TableProApp/TablePro/issues/4098)). -- Bring the KDE Wallet unlock prompt in front of the TablePro window ([#4099](https://github.com/TableProApp/TablePro/issues/4099)). - -### Browse, edit and structure - -- Edit binary columns from and to a file. They are read-only today, as are array, spatial, composite and variant columns. -- A clock in the grid's cell editor, where times are typed. Row Details has one beside the calendar. -- Reorder columns in the structure tab by dragging, with the ALTER previewed. - -### Release and project - -The [Linux user guide](https://docs.tablepro.app/linux), [download page](https://tablepro.app/download) and [support channels](../README.md#docs-and-community) are live. Support is through GitHub issues and Discord. - -- After 0.1.0 stable, the maintainer writes and submits the Flathub manifest and exception request by hand, under [Flathub's requirements](docs/decisions/0041-beta-repositories-and-release-packages.md#context). -- An AUR PKGBUILD, kept by the community. -- More languages: French, Korean, Turkish, and Simplified and Traditional Chinese, which the macOS app ships. -- A manual pass with Orca, the keyboard alone, High Contrast, 1.5x text scaling and a right-to-left locale. -- The [display scale pass](docs/testing.md#display-scales) again on a machine with a GPU and a HiDPI screen: the 2026-10-24 one ran in a container, on a software renderer. -- Install and use it on Ubuntu 26.04 by hand. Fedora 44 GNOME and KDE Plasma passed the [installed-bundle smoke pass](#release-criteria). -- Investigate the roughly 40-second first launch after a Flatpak update, seen once in a VM ([#4100](https://github.com/TableProApp/TablePro/issues/4100)). -- Track Flatpak's app-name parsing bug, which makes `flatpak list` show "Usage data" ([#4101](https://github.com/TableProApp/TablePro/issues/4101)). - -### More engines - -Each one is a crate under `core/crates/drivers` ([adding-drivers.md](docs/adding-drivers.md)), on a client library that meets [adding-drivers.md, The client library](docs/adding-drivers.md#1-the-client-library): maintained on crates.io, TLS through aws-lc-rs, a stream or Unix socket transport for SSH, and a way to stop a statement. - -| Engine | Client | Condition | -|---|---|---| -| Oracle | none | Blocked. The oracle crate has one maintainer, no release since 2025-01-02, and needs the proprietary Oracle client | - -Microsoft's mssql-tds is checked again each release as a SQL Server client. Today its TLS on Linux goes through OpenSSL and it takes no outside pull requests, so tiberius stays. - -### Ideas - -Not committed: server monitoring (sessions, locks, slow queries), maintenance commands, backup and restore through the engines' own tools (`pg_dump`, `mysqldump`), replication status, comparing result sets, schema diff and data sync between connections, drawn query plans and scheduled queries. - -## Release criteria - -What has to hold before 0.1.0, for a user on GNOME 50 with Ubuntu 26.04 or Fedora 44, and where each stands on 2026-11-08: - -beta.3 passed all seven items of the [installed-bundle smoke pass](docs/releasing.md#installed-bundle-smoke-pass) on Fedora 44 GNOME 50.6 and Fedora 44 KDE Plasma 6.8.2. The [record on #4089](https://github.com/TableProApp/TablePro/pull/4089#issuecomment-6713150474) includes the beta.1 to beta.3 Flatpak update on both desktops and the known issues. This does not close the manual accessibility pass or the week of daily use below. - -| # | The user | Holds today | Still needed | -|---|---|---|---| -| 1 | Installs `tablepro` from the PPA or the COPR project, and gets updates from the system's updater | beta.3 is published in the [beta PPA](https://launchpad.net/~tablepro/+archive/ubuntu/tablepro-beta) for Ubuntu 26.04 and 26.10, amd64 and arm64, and the [beta COPR project](https://copr.fedorainfracloud.org/coprs/g/tablepro/tablepro-beta/build/11284999/) for Fedora 44 and 45, x86_64 and aarch64. Fresh installs from both repositories passed in containers on both architectures. On 2026-11-08, beta.1 upgraded to beta.3 with `apt upgrade` from the PPA in Ubuntu 26.04 arm64 and with `dnf upgrade` from COPR in Fedora 44 aarch64, and both started | Nothing | -| 2 | Connects to their everyday PostgreSQL, MySQL, MariaDB, SQL Server, ClickHouse, Cassandra, ScyllaDB or SQLite database | The supported releases and why others are out, in the README's [supported servers](README.md#supported-servers). CI runs every driver's Docker suite on each tested release, MySQL 8.0 and SQL Server 2017 and 2019 among them | Nothing | -| 3 | Browses tables of real-world data (dates, decimals, JSON, UUIDs, NULLs) and sees correct values | Per-engine decoding with the type fallback and unsupported-type conformance cases ([ADR 0014](docs/decisions/0014-lossless-values-and-dialects.md)). A value corpus on every engine, MariaDB too: dates and times at their extremes and in other zones, decimals, JSON, UUIDs, Unicode and binary values, read back through a table tab, Export All and an editor run, and exported as CSV and SQL INSERT and loaded back into an empty copy | Nothing | -| 4 | Runs typical queries against tables of a million rows or more without running out of memory or freezing | The 10,000-row editor limit with Export All, and driver tests over 2,000,000 rows. Pages seek past the edge row's key, or walk PostgreSQL heap block windows for a table with no key; OFFSET only under a user sort, a restored deep offset or a partitioned keyless table. Docker tests page 60k and 25k-row tables both ways and check the plan. A 1,000,000-row table is paged to its end and exported on PostgreSQL, MySQL, MariaDB, SQL Server, ClickHouse, Cassandra, ScyllaDB, SQLite and DuckDB, with bounds on time and on resident peak growth. The file engines' cases run in the cargo suite, each in a test binary of its own, so the peak is its alone | Nothing | -| 5 | Edits data in place, and the changes commit correctly even when the connection or the app misbehaves | Write, row guard and commit resolution conformance on every engine, with the fault fakes and the grid save Docker test. `kill_during_save` kills TablePro halfway through a SQLite save: the file keeps none of it, and the next launch restores the session with its history, settings and saved tabs. A save into a SQLite file another program holds locked fails as `Busy(FileLocked)`, which says another program or an editor tab holds the file's lock, and leaves the file as it was whether the lock shows at `BEGIN IMMEDIATE` or at the `COMMIT` | Nothing | -| 6 | Trusts the app with credentials: TLS, SSH tunnels, no password in plain text | Each engine's own client TLS default, Verify full one choice away, the TLS conformance suite, the Secret Service, and statement logging silenced | Nothing. In place of an outside review, a security review by a model other than the one that wrote the code covered every Linux and core surface in `.oss-scanner/threat_model.md` on the release candidate before 0.1.0-beta.1, and its confirmed findings are fixed | -| 7 | Recovers when the network drops or the database restarts | Health monitoring, backoff and replay rules with their tests, a stopped container in the liveness tests, and a session test that restarts PostgreSQL: the read in flight runs again, the save in flight does not and leaves no row | Nothing | -| 8 | Works with a screen reader, the keyboard alone and larger text | Label audits of the picker, the connect pages, the workspace, the connect dialog and preferences, labelled cells and real-key tests. Sorting from the cell menu, named filter fields and cell editors, focus handed on when a control hides, and announced query results and errors. Columns move and resize from the keyboard, and a column sized by a key or a header drag draws at that width, also when it comes back. The ER diagram's tables are focusable list items that name their columns and joins | The manual pass in the backlog | -| 9 | Sees no message that cannot be translated, even while only English ships | Every string the app writes is in the template. Core errors carry values the app words itself: CSV import, cell and JSON parsing, type and default syntax, the keyring, certificate files, unsupported features, the SSH host, username and jump host checks, a failed write of the saved connections, the SSH runtime directory checks, ssh's exit status, and an ssh that would not start. A panic, an export encoder failure, an SSH failure with no sentence of its own and a TLS failure the app does not classify show the app's words and log the detail | Nothing | -| 10 | Uses the app daily for a week without an unrecoverable failure | Nothing yet | A dated week of daily use | -| 11 | Works with a database of many schemas or tables, such as one schema per tenant, without the sidebar or completion freezing | The large-catalog case on PostgreSQL with 100 schemas of 500 tables and MySQL with one database of 50,000: the sidebar's first listing, its search a key at a time, and completion after `FROM `, a key typed into it and after a schema's dot each have a time bound, none may stall the main loop past 100 ms, and the catalog has a bound on resident peak growth ([testing.md](docs/testing.md#large-catalog-case)) | Nothing | - -## Out of scope - -| Item | Reason | -|---|---| -| Plugins loaded at runtime | Drivers are linked in at compile time ([ADR 0001](docs/decisions/0001-no-plugin-system.md)) | -| Windows and macOS builds | Those platforms have their own apps in this repository | -| Embedded scripting (JavaScript, Python, Lua) | SQL is enough, and a scripting engine widens the attack surface | -| Hot-reloading drivers | Drivers are compiled in | -| Cloud sync of connections through a TablePro service | Not without a business model that needs it | -| KDE-native styling | The app runs with the Adwaita style everywhere | - -The distribution channels, and why there is no AppImage or Snap, are in [ADR 0018](docs/decisions/0018-ppa-copr-and-flathub-later.md). +The Linux app's remaining work and its order are in the repository's [ROADMAP.md](../ROADMAP.md). What the app does today is in [docs/features.md](docs/features.md), and what 0.1.0 needs is in the [release criteria](docs/releasing.md#release-criteria). diff --git a/linux/docs/README.md b/linux/docs/README.md index c09095a042..80ac56e4bb 100644 --- a/linux/docs/README.md +++ b/linux/docs/README.md @@ -1,6 +1,6 @@ # Linux docs -The reference for working on the Linux app. Start with [ARCHITECTURE.md](../ARCHITECTURE.md) for the crate graph and [CONTRIBUTING.md](../CONTRIBUTING.md) for the build; [ROADMAP.md](../ROADMAP.md) says what is built and what is not. +The reference for working on the Linux app. Start with [ARCHITECTURE.md](../ARCHITECTURE.md) for the crate graph and [CONTRIBUTING.md](../CONTRIBUTING.md) for the build; [features.md](features.md) says what is built, and the repository's [ROADMAP.md](../../ROADMAP.md) what is not. ## Guides @@ -14,7 +14,8 @@ The reference for working on the Linux app. Start with [ARCHITECTURE.md](../ARCH | [toolkit-workarounds.md](toolkit-workarounds.md) | Each place the app steps around a GTK, libadwaita, GtkSourceView, IBus or gtk-rs defect, and when it can go | | [troubleshooting.md](troubleshooting.md) | For users: saved passwords, SSH, Kerberos, logs, crash reports, bug reports and downgrades | | [regression-tests.md](regression-tests.md) | The tests that guard each critical audit finding | -| [releasing.md](releasing.md) | The setup before the first release, a release, a packaging fix and a fix release | +| [features.md](features.md) | What the app does today, area by area | +| [releasing.md](releasing.md) | The setup before the first release, the 0.1.0 release criteria, a release, a packaging fix and a fix release | | [po/README.md](../po/README.md) | Marking strings for translation and generating the template | ## Drivers diff --git a/linux/docs/decisions/0001-no-plugin-system.md b/linux/docs/decisions/0001-no-plugin-system.md index e3bb37f099..d8429f1e7c 100644 --- a/linux/docs/decisions/0001-no-plugin-system.md +++ b/linux/docs/decisions/0001-no-plugin-system.md @@ -1,6 +1,6 @@ # 0001: No plugin system; drivers are statically linked -- **Status**: Superseded by core 0004 (`core/docs/decisions/0004-driver-plugin-abi.md`) +- **Status**: Accepted; superseded by core 0004 from 2026-11-02 until core 0025 (`core/docs/decisions/0025-linux-and-windows-link-their-drivers.md`) put it back in force - **Date**: 2026-04-26 ## Context diff --git a/linux/docs/decisions/README.md b/linux/docs/decisions/README.md index 6ee017ffa7..7299d5a144 100644 --- a/linux/docs/decisions/README.md +++ b/linux/docs/decisions/README.md @@ -49,7 +49,7 @@ A fact the repository keeps elsewhere, such as a workflow trigger, a branch, a v | # | Title | Status | Summary | |---|---|---|---| -| [0001](0001-no-plugin-system.md) | No plugin system; drivers are statically linked | Superseded by core 0004 | Drivers are crates, registered at compile time. No `.tableplugin`-equivalent on Linux. | +| [0001](0001-no-plugin-system.md) | No plugin system; drivers are statically linked | Accepted; superseded by core 0004 until core 0025 put it back in force | Drivers are crates, registered at compile time. No `.tableplugin`-equivalent on Linux. | | [0002](0002-rust-gtk4-libadwaita.md) | Rust + GTK4 + libadwaita | Accepted; version floor superseded by 0015, the Relm4 consequence by 0012 | Validated by spike. Only stack with a production virtualized data grid (GtkColumnView). | | [0003](0003-relm4-architecture.md) | Relm4 for app architecture | Superseded by 0012 | Elm-style components scale to TablePro's view count. | | [0004](0004-libsecret-secret-storage.md) | Secret storage through oo7 | Accepted; store API and Flatpak path amended 2026-09-15, the rules for edits 2026-10-15 | The Secret Service on the host, and oo7's own keyring file with a key from the Secret portal inside Flatpak; never a plain-text file. | diff --git a/linux/docs/features.md b/linux/docs/features.md new file mode 100644 index 0000000000..aeae818bd0 --- /dev/null +++ b/linux/docs/features.md @@ -0,0 +1,181 @@ +# Features + +What the Linux app does, recorded on 2026-11-08. [0.1.0-beta.3](https://github.com/TableProApp/TablePro/releases/tag/linux-v0.1.0-beta.3) is published on GitHub Releases, the beta PPA, the beta COPR project and the beta Flatpak repository ([README](../README.md#betas)). beta.2 was tagged but never published: [release run 42382067978](https://github.com/TableProApp/TablePro/actions/runs/42382067978) failed before publishing, and [#4093](https://github.com/TableProApp/TablePro/pull/4093) fixed the failure for beta.3. + +The work left and its order are in the repository's [ROADMAP.md](../../ROADMAP.md), and what 0.1.0 needs in the [release criteria](releasing.md#release-criteria). + +The app runs on GNOME 50 ([ADR 0015](decisions/0015-gnome-50-platform-floor.md)) and connects to nine engines, each a crate linked in at compile time ([ADR 0001](decisions/0001-no-plugin-system.md)): [PostgreSQL](drivers/postgresql.md), [MySQL and MariaDB](drivers/mysql.md), [SQL Server](drivers/sql-server.md), [ClickHouse](drivers/clickhouse.md), [Cassandra and ScyllaDB](drivers/cassandra.md), [SQLite](drivers/sqlite.md), [DuckDB](drivers/duckdb.md), [Redis](drivers/redis.md) and [MongoDB](drivers/mongodb.md). + + +## Connections + +| Capability | Detail | +|---|---| +| Saved connections | Create and edit (the name included), duplicate with the secrets carried to the copy, delete with or without the connection's history | +| Groups, favourites and colours | Groups nest 3 levels deep and show as a tree in the library's order, empty ones too. New Group, New Subgroup, Rename and Delete from the menus; a delete asks first. A connection or a group moves by drag and drop or from its menu (Move to Group, Move Group To, Move Up, Move Down). Favourites and the 5 connections opened last lead the picker; favourites reorder the same way | +| Tags and icons | Several named tags per connection, each with a colour, from the row's menu or the connect dialog, shown after the name and read with the row's description; Manage Tags renames, recolours and deletes them. An icon from a fixed set shows in the row and beside the window title | +| Search | The connection list's search (Ctrl+F, or start typing) matches the name, host, database, user, driver, the names on the group's path and tag names | +| Import and export | A JSON file with no secrets in it, tags and icons included. On import, an entry with the same id and the same settings updates its name, colour, group, tags and icon; any other is added as a new connection. Tags are matched by id, then by name, so a second import adds none | +| Connection URLs | A URL pasted at the top of a new connection fills the form: the engine, host, port, user, database and TLS mode, the authentication database, a DNS seed list and a replica set's hosts, and the password, kept in the Secret Service with Remember Password on. libpq, MySQL, MongoDB, Redis and Valkey, ClickHouse and Cassandra URLs, SQL Server's JDBC form and SQLite and DuckDB file URLs are read ([core `connection_url`](../../core/crates/core/src/connection_url/mod.rs)) | +| Unix sockets | PostgreSQL, MySQL and MariaDB on this computer through the server's socket, for peer, `auth_socket` and `unix_socket` logins: a folder for PostgreSQL, the socket file for MySQL, found in the distribution's usual place. The Flatpak sees the sockets under `/run/postgresql` and `/run/mysqld` ([ADR 0035](decisions/0035-flatpak-local-database-sockets.md)) | +| Test before saving | Test connects once and reports, then disconnects | +| Passwords | Kept in the Secret Service; a prompt asks when one is missing or refused, with Remember Password | +| Safe Mode | A level per connection, set in the connect dialog or the main menu while connected and saved back to the connection. Off asks before DROP, TRUNCATE, and DELETE or UPDATE without WHERE. Confirm Writes also asks before every other write from the editor, a grid save, a structure save, a CSV import, a SQL file import, or a drop, truncate or create from the sidebar, showing the SQL, or the file, and the connection, with Cancel the default. Read-Only refuses every editor statement that does not read, and opens the connection read-only: SQLite, DuckDB and ClickHouse refuse writes at the engine, PostgreSQL and MySQL run in read-only transactions, SQL Server relies on the login, with the app's own reads in a rolled-back transaction, and Cassandra and ScyllaDB rely on the login. A statement is a read only when its engine's grammar shows it reads, each statement of a script on its own. Moving to or from Read-Only reconnects the window | +| Query timeout per connection | Custom Query Timeout in the connect dialog sets the editor's timeout for that connection in place of the one in Preferences, from the next connect; 0 turns it off. The app's own calls keep their fixed limits: 15 seconds for metadata, 60 for a page or a count, 120 for a row save or a CSV import, none for a schema change or an export, and on the server 60 for a table-tab statement and 10 for a lock wait | +| Database files | SQLite and DuckDB: choose a file, create a new one, open one from Files or a terminal, where the file's header picks the engine, find a moved one with Locate, and choose read-only or read-write for one on a network or FUSE filesystem | +| Kerberos for SQL Server | From the ticket cache, in the Flatpak through the KCM socket | +| Health and reconnect | A banner while the connection is lost, reconnect with a backoff from 5 to 60 seconds, and metadata, page and count reads replayed once after it; writes are never replayed | +| Cancel on the server | Stopping a query stops the statement on the server (in process on SQLite); a ClickHouse mutation already running in a save is left to finish. CQL has no stop, so on Cassandra and ScyllaDB the app stops waiting and the server runs the statement to its own timeout | + +## SSH + +| Capability | Detail | +|---|---| +| System OpenSSH client | One ControlMaster per connection ([ADR 0013](decisions/0013-openssh-client-transport.md)); empty fields come from `~/.ssh/config` | +| Jump hosts | A ProxyJump chain, passed to `ssh -J` | +| Authentication | Agent, private key, password and keyboard-interactive; prompts go through the app's askpass helper | +| Host keys | An unknown or changed key is shown with its SHA256 fingerprint before connecting, even where ssh_config says accept-new or no. A changed key can be replaced in known_hosts, except under StrictHostKeyChecking yes, where the user fixes known_hosts outside the app and retries. A revoked key is refused | + +## TLS + +| Capability | Detail | +|---|---| +| Modes | Disable, Prefer (PostgreSQL and MySQL), Require and Verify full; a new connection starts on the mode the engine's own client starts on ([core ADR 0014](../../core/docs/decisions/0014-tls-mode-of-a-new-connection.md)) | +| Certificates | CA file, client certificate and key (every network engine but SQL Server), and a server name override (MySQL only through an SSH tunnel) | +| Remedies | A TLS failure says what went wrong. An unknown issuer jumps to the CA file, a name mismatch to the server name, and a server that refuses or requires TLS to the Encryption row | + +## Browse and edit + +| Capability | Detail | +|---|---| +| Data grid | A virtualized `GtkColumnView` with keyboard-focusable cells, pages of 100 to 10,000 rows, and a pager with an exact or estimated row count; a table of about 100,000 rows or fewer is counted on its own, a larger one offers Count Rows | +| Filters | Per-column operators, a raw WHERE fragment checked as one expression, match any or all; binary columns compare to `0x` hex. Kept per table, and per tab across a restart or a reopen. On Cassandra and ScyllaDB only the operators the server evaluates, matched all, with `ALLOW FILTERING` | +| Sorting | A header click sorts tables on the server and query results in the grid, one column at a time. A Cassandra or ScyllaDB table keeps the server's order, and pages by its paging state | +| Cell editing | Editors by column kind: inline text, a multi-line editor, a calendar for dates and, in Row Details, a clock for times, a toggle for booleans, JSON checked before saving; values are edited from their exact text, never from what the cell displays. Tables with a primary key, in a table tab or as a query result that reads one table with its whole key ([ADR 0036](decisions/0036-editing-query-results.md)); key, generated and auto-increment columns, and binary, spatial, array and composite values, are read-only | +| Rows | Insert, duplicate and delete; Paste (Ctrl+V) adds tab-separated rows from the clipboard, filling the columns from the focused one or by a header's names, or edits the focused cell with one value, and asks first above 1,000 rows, up to 100,000; Set NULL and Empty, and DEFAULT on a new row; undo and redo; save or discard pending changes, and stop a save. On ClickHouse, Cassandra and ScyllaDB a save is not atomic, and Stop takes effect between statements | +| Server-computed values | A date, time or timestamp cell takes the engine's own `NOW()`, `CURRENT_TIMESTAMP`, `CURRENT_DATE` and the like, typed in any letter case or picked from the cell menu, and a saved row's cell takes DEFAULT where the engine has `SET c = DEFAULT` (PostgreSQL, MySQL and MariaDB, SQL Server, DuckDB). Only each engine's own list is offered, which on DuckDB is `now()` alone, since the bundled build has no ICU extension; the save writes the expression into the statement, so the Confirm Writes review and the history show it as written | +| Bulk delete | Deleting 10 rows or more asks first, unless Confirm Before Deleting Rows is off in Preferences | +| Copy | Copy; Copy As rows, with headers, CSV with or without headers, JSON, JSON Lines, Markdown, a text table, IN clause or one row of SQL values, and INSERT with or without generated keys in an editable table tab; Copy Column Name; Show Row as JSON | +| Foreign keys | Open Referenced Row (Ctrl+J) on a key cell opens the table it points at in a new tab, filtered on every column of the key; Show Referencing Rows on a saved row opens a table whose key points at it. A tab already showing those rows comes to the front | +| Column layout | Order, hidden columns and widths kept per table; a column added since goes last and a dropped one keeps its place. A header drag, or Move Column Left and Move Column Right in the cell menu (Alt+Left and Alt+Right), reorders them; Widen Column and Narrow Column (Shift+Alt+Right and Shift+Alt+Left) resize them; Reset Columns in the Columns dialog goes back to the table's own order | +| CSV import | Into an existing table, with a column mapping, in one write batch (one transaction where the engine has them), up to 64 MiB | +| Sidebar | Tables (partitioned ones included), views, materialized views and foreign tables by schema, with search and Refresh, read again after the editor runs DDL, Open in New Tab and Show CREATE TABLE; Edit Structure, Import CSV, Truncate Table and Drop Table for tables, Delete All Documents for collections; New and Drop Schema, and New and Drop Database (Keyspace on Cassandra), on every engine that has them, never offered for a system object or the session's own database; empty schemas listed | +| Routines and triggers | Functions, procedures and sequences in the sidebar after each schema's tables, and triggers with the table each fires on, on every engine that has them. Opening one shows its definition read-only, with Copy and Open in Editor; every overload of a PostgreSQL function name is shown | +| ER diagram | Show ER Diagram in a table's menu or on a schema's heading opens the schema's tables as cards and their foreign keys as lines in crow's foot notation, read two tables at a time with Stop. Pan, zoom, Best Fit, drag tables, Reset Layout, and PNG and SVG export. Each table is a list item the keyboard and a screen reader reach: Tab and the arrow keys move between tables, Enter opens one, Alt+arrows move it, and its description names its columns and the tables it joins | + +## Structure + +| Capability | Detail | +|---|---| +| Table definition | Columns, indexes, foreign keys and column comments | +| Index statements | Show CREATE INDEX and Copy CREATE INDEX on each index the table has, as the statement that makes it again: the server's own text on PostgreSQL, MySQL, MariaDB, SQLite and DuckDB, and written from the catalog, storage and options included, on SQL Server, ClickHouse, Cassandra and ScyllaDB. An index a constraint owns, such as a primary key or a UNIQUE constraint, a partition's index attached to its parent's and a ClickHouse sorting key offer none. Show CREATE TABLE uses the same statements | +| Changes | Create, rename and drop tables; add, drop and rename columns, and change their type, nullability, default, comment, primary key and auto-increment; add and drop indexes (column keys, unique, descending) and foreign keys. ClickHouse creates no tables, indexes or foreign keys and changes no primary key or auto-increment; SQL Server changes no auto-increment; SQLite keeps no column comments; Cassandra and ScyllaDB take no default or NOT NULL, and rename only key columns | +| Review | The SQL is previewed, and a save that loses data or can stop halfway is reviewed before it runs | +| SQLite rebuilds | Changes SQLite cannot ALTER rebuild the table in one transaction, keeping its rows, indexes, triggers, the views and triggers that name it and its AUTOINCREMENT counter, with foreign keys checked before commit. SQLite itself checks the views and triggers made again; a trigger that lists a dropped column or inserts by position is refused before Save | + +## Keys + +| Capability | Detail | +|---|---| +| Key list | A Redis connection lists the keys of its numbered database with their types, read with `SCAN`; the search goes to the server, plain text matching anywhere in a key and text with `*`, `?` or `[` as a glob. A banner says when the list stops at its 5,000-key limit | +| Key tab | A key opens by type: a string's value, a hash's fields, a list by index, a set's members, a sorted set with scores and a stream's entries, 500 at a time with Load More, under its length and expiry | +| Commands | The editor takes Redis commands, one per line, and shows each reply as redis-cli lays it out; `MULTI` is tracked as a transaction. A waiting command stops with `CLIENT UNBLOCK`. Read-Only refuses every command that is not a read before it is sent ([redis.md](drivers/redis.md)) | + +## Documents + +| Capability | Detail | +|---|---| +| Connecting | A MongoDB connection reaches one host directly, a replica set from its hosts and name, a replica set or cluster through its DNS seed list (`mongodb+srv://`), or one host through SSH, with an optional authentication database | +| Collections | Databases list their collections and views. A collection opens in a table tab: its top-level fields as columns, `_id` first, nested documents and arrays as JSON. Paging, filters, the raw filter as a query document, sorting, editing a field, inserting and deleting run as mongosh calls with bound values, shown in the history and the Safe Mode review ([mongodb.md](drivers/mongodb.md)) | +| Statements | The editor takes mongosh statements (`find`, `aggregate`, the writes, `runCommand`, `use`, `show`) and shows documents one per row. A running statement stops with `killSessions`. Read-Only refuses every statement that is not a read, `$out` and `$merge` included, before it is sent | + +## SQL editor + +| Capability | Detail | +|---|---| +| Editing | GtkSourceView with SQL highlighting, a scheme that follows the light or dark style, and toggle comment | +| Completion | Tables, views, columns, schemas, functions and keywords, with aliases resolved | +| Snippets | SELECT, INSERT, UPDATE, DELETE, a join (none on Cassandra and ScyllaDB), CREATE TABLE and CREATE INDEX per engine, and the user's own in GtkSourceView's format from a folder read again when it changes, a snippet scoped to one engine or to all; offered in completion, with Tab between stops ([README](../README.md#snippets)) | +| Formatter | Format SQL, leaving a statement as typed when formatting would change its tokens | +| Scripts | Split per dialect (`DELIMITER`, `GO` and `GO n`, routine and trigger bodies) and sent a statement at a time, or a batch at a time on SQL Server; each result set, row count, notice or error is its own entry, and a failure stops the script except on SQL Server. Run Selection, and run the statement at the cursor | +| Find and replace | Ctrl+F and Ctrl+H, with case, whole word and regular expressions | +| Files | Open a .sql file into the editor (Ctrl+O) or drop one on it, and save to it (Ctrl+S, or Save As with Ctrl+Shift+S) | +| Results | Several result sets per run, a limit of 10,000 rows per result and 100,000 per run with a banner and Export All, and Go to Error | +| Drafts | Each editor tab's text is kept, and a connection's tabs (table tabs with page and sort, structure and editor tabs) reopen when it opens | +| Multiple cursors | Ctrl+D for the next match, Ctrl+Shift+L for every match, Shift+Alt+Up and Down for the lines above and below, Ctrl+click; typing, deleting, pasting and moves at every cursor, one undo for all of them ([README](../README.md#multiple-cursors)) | +| Vim mode | GtkSourceView's Vim emulation, off by default, with the mode and pending command under the text; `:w`, `:e`, `:q`, `:wq` and `:x` act on the tab, and the editor's Ctrl shortcuts work in every mode ([README](../README.md#vim-keybindings)) | + +## History and saved queries + +| Capability | Detail | +|---|---| +| Query history | A SQLite database with full-text search, filters by connection, time and status, pins, export as SQL or CSV, and a retention period | +| What is recorded | Editor runs, and the SQL the app runs for grid saves, structure saves and successful imports; a run that can carry a password or connection secret, or whose text does not tokenize, is not recorded, and recording can be turned off | +| Show in Files | For the history database, from the history dialog and Preferences | +| Saved queries | Saved from the editor against a connection, listed by connection with the active one first, and opened in a new tab or the current one | + +## Export + +| Capability | Detail | +|---|---| +| Formats | CSV with its options, JSON, Markdown, HTML, XML, Excel, and SQL INSERT from a table tab | +| Scope | From a table tab, the current page with its pending edits, or every saved row under the filter and sort. From the editor, the rows shown, or every row by running the statement again on a separate read-only connection without the tab's USE or SET; a statement that writes is refused | +| Running | Off the GTK thread with progress and Stop; closing or quitting asks about a running export | +| Database | Export Database in the main menu writes a whole database or one schema to a `.sql` or `.sql.gz` file: tables, views, routines and triggers, and every table's rows as multi-row INSERTs, in the order `pg_dump` and `mysqldump` use, so `psql`, `mysql`, `sqlcmd`, `sqlite3` and `clickhouse-client` load it as well as Import SQL File does. Read in process from the connection, not by calling those tools ([core ADR 0011](../../core/docs/decisions/0011-sql-dump-and-import-in-process.md)); not offered on Redis, MongoDB, Cassandra and ScyllaDB ([README](../README.md#export-a-database-and-import-a-sql-file)) | + +## Import + +| Capability | Detail | +|---|---| +| SQL files | Import SQL File in the main menu runs a `.sql` or `.sql.gz` file of any size on an editor session of its own, split as the engine's client splits it (`DELIMITER`, `GO n`, routine bodies, dollar quotes), with progress, Stop and a summary of what failed and where. pg_dump's `COPY ... FROM stdin` rows load through the copy protocol, text or CSV, and its `\restrict` lines are passed over | +| Errors and transactions | Stop at First Error, or run the rest and list each failure with its line. On PostgreSQL, SQL Server, SQLite and DuckDB the file can run as one transaction, so a failure or Stop undoes it all; MySQL, MariaDB and ClickHouse commit each statement as it runs. Safe Mode Read-Only offers neither import, and the import dialog is the one question Confirm Writes asks for the whole file | + +## Windows and sessions + +| Capability | Detail | +|---|---| +| Sessions in a window | A window holds several connection sessions, their tabs side by side in one tab view, and a connection already open brings its window forward ([ADR 0028](decisions/0028-sessions-share-a-window.md)) | +| One instance | A second launch presents the running app; New Window (Ctrl+Shift+N) opens a picker | +| Tabs | `AdwTabView` with the tab overview and split header bars, adapting down to 360×294 | +| Session restore | The windows of saved connections and database files open at quit open again at launch (Restore Session, on by default), also after New Window or a quit during the restore | +| Closing safely | Unsaved edits, a save in flight or of unknown outcome, an open editor transaction, or a running export ask before a window closes or the app quits; logout waits while any of those holds, and suspend while a save runs or an export writes | +| Notifications | Work that finishes in a tab you are not looking at sends a notification | +| Preferences | Restore session, page size, the bulk delete confirmation, query history, editor font and scheme, Vim keybindings, query timeout, the AI assistant, the MCP server | +| Shortcuts and About | A shortcuts dialog, and About from the metainfo with third-party licenses and debug info | + +## AI assistant + +| Capability | Detail | +|---|---| +| Providers | Off until a provider is chosen in Preferences: Anthropic, OpenAI, or Ollama and other servers through the OpenAI-compatible protocol. Keys in the keyring; the model picked from the provider's list ([ADR 0022](decisions/0022-ai-assistant-and-mcp-server.md)) | +| Chat | A pane beside the tabs (Ctrl+Alt+A) with streamed replies, Stop, Retry and New Conversation; code blocks with Copy and Insert. A conversation carries the editor's SQL and the structure of the tables it names, and reads no rows | +| Editor | Explain, Review and Optimize the selection or the statement at the cursor, Fix with AI on a failed statement, and suggestions while typing (off by default) that Tab accepts | +| AI policy | Per connection: Ask Each Time (the default) asks before the first request in a window, Allow sends without asking, Never sends nothing from the connection | + +## MCP server + +| Capability | Detail | +|---|---| +| Server | Streamable HTTP on `127.0.0.1` only, off until turned on in Preferences, with a port preference and a bearer token kept in the keyring ([ADR 0022](decisions/0022-ai-assistant-and-mcp-server.md)) | +| External Clients | A level per connection: Blocked hides it, Read Only (the default) lets clients read, Read & Write lets them write after the user approves each statement in Safe Mode's dialog. Safe Mode Read-Only refuses every client write | +| Tools | List connections, open one in a window, list schemas and tables, describe a table and show its DDL, browse and count rows with filters, and run one statement; runs go into the query history | + +## TablePro account + +| Capability | Detail | +|---|---| +| Sign-in | Preferences > Account signs in to a TablePro account through the browser, as on macOS; the sign-in is kept in the keyring ([ADR 0038](decisions/0038-account-page-and-license-ask.md)) | +| Plan, devices and teams | The plan and its status, each paid feature this platform has, included or not by the plan ([ADR 0042](decisions/0042-account-page-lists-this-platforms-features.md)), the account's devices with Remove, the device limit dialog, teams, and offline files for a computer with no internet | +| License ask | From the 30th day of use without a license, a toast asks whether you would buy one, then at most every 90 days | +| Usage data | On by default, as on macOS: the clients.md events go to PostHog until Preferences > General > Privacy turns it off ([ADR 0039](decisions/0039-usage-data.md)) | + +## Packaging and platform + +| Capability | Detail | +|---|---| +| Flatpak | The Devel manifest builds on GNOME 51 for x86_64 and aarch64 with every Meson suite in the sandbox, and is linted, in the nightly Linux run; the release manifest builds the Flatpak a release signs into `flatpak.tablepro.app` and bundles for GitHub, offline from the release tarballs; CI tests it, signs it into test repositories, then installs, starts, updates and switches branches on Ubuntu 22.04, 24.04 and 26.04 ([ADR 0041](decisions/0041-beta-repositories-and-release-packages.md)) | +| .deb and .rpm | Ubuntu 26.04 and 26.10 and Fedora 44 and 45, built offline in CI the way Launchpad and COPR build them, linted, then installed and started in fresh containers; a `linux-v*` tag publishes them on GitHub Releases, uploads to the PPA and starts the COPR build, a beta tag to the beta ones ([ADR 0018](decisions/0018-ppa-copr-and-flathub-later.md), [ADR 0041](decisions/0041-beta-repositories-and-release-packages.md)) | +| Desktop integration | Desktop file with Open With for SQLite files, D-Bus activation, a man page, metainfo with screenshots, and SVG icons | +| Translations | Vietnamese ships. The app's own strings go through gettext, and CI fails when `POTFILES.in` is stale or a translation loses a placeholder. CI builds the template with gettext 1.0 and publishes it from main and with each release; translators send pull requests against `po/*.po` ([po/README.md](../po/README.md#where-translators-work)) | +| Logs | stderr, which the session journals, with JSON lines on request. A panic also writes a crash report under `$XDG_STATE_HOME`, offered with Show Report on the next launch | +| Tests | Unit, gtk (with an accessibility audit of the picker, the connect pages, the workspace, the connect dialog and every preferences page), data and packaging suites; connection, DDL and TLS conformance, a CSV and SQL INSERT export round trip, a copy and paste round trip, and a database dump loaded back through Import SQL File and dumped again to the same file, on every SQL engine, keyspace and TLS conformance on Redis, and document and TLS conformance on MongoDB; Docker jobs for PostgreSQL with PgBouncer, MySQL and MariaDB, SQL Server, ClickHouse, Cassandra and ScyllaDB, Redis, MongoDB, SSH, the session and the grid save ([testing.md](testing.md)); every critical audit finding has named guards ([regression-tests.md](regression-tests.md)) | diff --git a/linux/docs/releasing.md b/linux/docs/releasing.md index ddc6ec15bc..4935b6a467 100644 --- a/linux/docs/releasing.md +++ b/linux/docs/releasing.md @@ -173,6 +173,26 @@ The app's own files also need a maintainer before the submission: Our existing installs keep their TablePro origin. Adding Flathub or changing the default branch does not migrate that origin. Before offering migration instructions, test an explicit origin change from both our stable and beta installs to the accepted Flathub app. Record the commands and before/after origin, branch and commit from `flatpak info`. Verify updates come from Flathub, secrets still load, saved work survives and rollback works. Keep our repository available until that tested migration is published. Do not promise automatic migration. +## Release criteria + +What has to hold before 0.1.0, for a user on GNOME 50 with Ubuntu 26.04 or Fedora 44, and where each stands on 2026-11-08: + +beta.3 passed all seven items of the [installed-bundle smoke pass](#installed-bundle-smoke-pass) on Fedora 44 GNOME 50.6 and Fedora 44 KDE Plasma 6.8.2. The [record on #4089](https://github.com/TableProApp/TablePro/pull/4089#issuecomment-6713150474) includes the beta.1 to beta.3 Flatpak update on both desktops and the known issues. This does not close the manual accessibility pass or the week of daily use below. + +| # | The user | Holds today | Still needed | +|---|---|---|---| +| 1 | Installs `tablepro` from the PPA or the COPR project, and gets updates from the system's updater | beta.3 is published in the [beta PPA](https://launchpad.net/~tablepro/+archive/ubuntu/tablepro-beta) for Ubuntu 26.04 and 26.10, amd64 and arm64, and the [beta COPR project](https://copr.fedorainfracloud.org/coprs/g/tablepro/tablepro-beta/build/11284999/) for Fedora 44 and 45, x86_64 and aarch64. Fresh installs from both repositories passed in containers on both architectures. On 2026-11-08, beta.1 upgraded to beta.3 with `apt upgrade` from the PPA in Ubuntu 26.04 arm64 and with `dnf upgrade` from COPR in Fedora 44 aarch64, and both started | Nothing | +| 2 | Connects to their everyday PostgreSQL, MySQL, MariaDB, SQL Server, ClickHouse, Cassandra, ScyllaDB or SQLite database | The supported releases and why others are out, in the README's [supported servers](../README.md#supported-servers). CI runs every driver's Docker suite on each tested release, MySQL 8.0 and SQL Server 2017 and 2019 among them | Nothing | +| 3 | Browses tables of real-world data (dates, decimals, JSON, UUIDs, NULLs) and sees correct values | Per-engine decoding with the type fallback and unsupported-type conformance cases ([ADR 0014](decisions/0014-lossless-values-and-dialects.md)). A value corpus on every engine, MariaDB too: dates and times at their extremes and in other zones, decimals, JSON, UUIDs, Unicode and binary values, read back through a table tab, Export All and an editor run, and exported as CSV and SQL INSERT and loaded back into an empty copy | Nothing | +| 4 | Runs typical queries against tables of a million rows or more without running out of memory or freezing | The 10,000-row editor limit with Export All, and driver tests over 2,000,000 rows. Pages seek past the edge row's key, or walk PostgreSQL heap block windows for a table with no key; OFFSET only under a user sort, a restored deep offset or a partitioned keyless table. Docker tests page 60k and 25k-row tables both ways and check the plan. A 1,000,000-row table is paged to its end and exported on PostgreSQL, MySQL, MariaDB, SQL Server, ClickHouse, Cassandra, ScyllaDB, SQLite and DuckDB, with bounds on time and on resident peak growth. The file engines' cases run in the cargo suite, each in a test binary of its own, so the peak is its alone | Nothing | +| 5 | Edits data in place, and the changes commit correctly even when the connection or the app misbehaves | Write, row guard and commit resolution conformance on every engine, with the fault fakes and the grid save Docker test. `kill_during_save` kills TablePro halfway through a SQLite save: the file keeps none of it, and the next launch restores the session with its history, settings and saved tabs. A save into a SQLite file another program holds locked fails as `Busy(FileLocked)`, which says another program or an editor tab holds the file's lock, and leaves the file as it was whether the lock shows at `BEGIN IMMEDIATE` or at the `COMMIT` | Nothing | +| 6 | Trusts the app with credentials: TLS, SSH tunnels, no password in plain text | Each engine's own client TLS default, Verify full one choice away, the TLS conformance suite, the Secret Service, and statement logging silenced | Nothing. In place of an outside review, a security review by a model other than the one that wrote the code covered every Linux and core surface in `.oss-scanner/threat_model.md` on the release candidate before 0.1.0-beta.1, and its confirmed findings are fixed | +| 7 | Recovers when the network drops or the database restarts | Health monitoring, backoff and replay rules with their tests, a stopped container in the liveness tests, and a session test that restarts PostgreSQL: the read in flight runs again, the save in flight does not and leaves no row | Nothing | +| 8 | Works with a screen reader, the keyboard alone and larger text | Label audits of the picker, the connect pages, the workspace, the connect dialog and preferences, labelled cells and real-key tests. Sorting from the cell menu, named filter fields and cell editors, focus handed on when a control hides, and announced query results and errors. Columns move and resize from the keyboard, and a column sized by a key or a header drag draws at that width, also when it comes back. The ER diagram's tables are focusable list items that name their columns and joins | R-10 in the [roadmap](../../ROADMAP.md#linux-010) | +| 9 | Sees no message that cannot be translated, even while only English ships | Every string the app writes is in the template. Core errors carry values the app words itself: CSV import, cell and JSON parsing, type and default syntax, the keyring, certificate files, unsupported features, the SSH host, username and jump host checks, a failed write of the saved connections, the SSH runtime directory checks, ssh's exit status, and an ssh that would not start. A panic, an export encoder failure, an SSH failure with no sentence of its own and a TLS failure the app does not classify show the app's words and log the detail | Nothing | +| 10 | Uses the app daily for a week without an unrecoverable failure | Nothing yet | A dated week of daily use | +| 11 | Works with a database of many schemas or tables, such as one schema per tenant, without the sidebar or completion freezing | The large-catalog case on PostgreSQL with 100 schemas of 500 tables and MySQL with one database of 50,000: the sidebar's first listing, its search a key at a time, and completion after `FROM `, a key typed into it and after a schema's dot each have a time bound, none may stall the main loop past 100 ms, and the catalog has a bound on resident peak growth ([testing.md](testing.md#large-catalog-case)) | Nothing | + ## The first release `main` carries 0.1.0 from before any tag: a metainfo `` and a spec `%changelog` entry for it, and the fragments of every change on the way.