← All apps

🔎 CandyQuery

Terminal SQLite browser

port of lazysql sql sqlite tui pdo

Composer-installable multi-driver SQL TUI: connect to SQLite, MySQL, or PostgreSQL, browse tables, peek at row data, run ad-hoc queries, and explore a full MySQL-Workbench-style admin dashboard — all on the SugarCraft stack. SQLite-first; MySQL and PostgreSQL drivers plus a Performance Dashboard, Server Status, Variables, Connections, Reports, and Performance Schema Setup ship as of v1.

Install

composer require sugarcraft/candy-query

Quickstart

# SQLite via bare path (inferred as Flavor::Sqlite)
bin/candy-query app.sqlite

# Any DSN — MySQL, PostgreSQL, SQLite, SQLSRV
bin/candy-query --dsn mysql://user:pass@localhost:3306/dbname

// Or wire it up programmatically:
use SugarCraft\Core\Program;
use SugarCraft\Core\ProgramOptions;
use SugarCraft\Query\App;
use SugarCraft\Query\Db\ConnectionFactory;

$pdo = ConnectionFactory::fromDsn('mysql://user:pass@localhost:3306/dbname');
(new Program(App::start($pdo), new ProgramOptions(useAltScreen: true)))->run();

What's in the box

Source & demos

• Source on GitHub
• Full README
• Runnable examples
• Port of lazysql (Go upstream)

Try the quickstart →

API

Smoke Testing.

Manual verification checklist — CI runs unit tests against fakes; these steps validate end-to-end behavior against real database servers.

SQLite smoke (browser regression)

No live server needed. Tests the TUI layer and async cache with an in-memory SQLite connection.

1. php bin/candy-query --dsn sqlite:///tmp/smoke_test.db — launches; table list populates within 1 second.
2. Press Tab to cycle panes — Schema Browser, Query Editor, History, Results all render without crash.
3. Press n in Schema Browser — new table dialog opens; confirm/cancel works.
4. Press e in table list — rows load with spinner; second tick shows rows (async cache).
5. Press r in Query Editor — run a SELECT 1; result grid renders correctly.
6. Press x in Results pane — CSV export produces valid RFC-4180 output (no trailing space padding, formula guard active).
7. Press q — clean exit; no segfault or panic.

MySQL smoke (admin pages + round-trips)

Requires a scratch MySQL 5.6+ instance. Validates all 7 admin panes, version gating, and write round-trips.

1. php bin/candy-query --dsn mysql://user:pass@localhost:3306/testdb — connects; status bar shows MySQL version.
2. Admin pages reachable via number keys (1–7):
   • 1 Server Status — sidebar gauges (Connections, Traffic, Key Efficiency, QPS, InnoDB) render with live rate calculations; restart detection badge works.
   • 2 Process List — PS path active when performance_schema = ON; KILL button kills a test connection cleanly; KILL QUERY aborts a running query.
   • 3 Connections — connection list loads; ConnectionActions (kill, killQuery, setInstrumentation) all respond.
   • 4 Variables — [e] opens edit dialog for dynamic vars; [p] cycles GLOBAL/PERSIST/PERSIST_ONLY modes; error 1238 surfaces for static vars; SET PERSIST_ONLY commits successfully on MySQL 8+.
   • 5 Performance Schema — Easy Setup badge shows (fully/default/custom/disabled); all 7 tabs navigate; [c] commits dirty changes; on MySQL 5.5, actors tab is empty (version gate).
   • 6 Reports — category tree loads from catalog; [h]/[l] cycle categories; [ ] cycle reports; report executes and renders with unit toggle [c]; [x] exports CSV.
   • 7 Dashboard — widgets render with real values; alert toasts fire once on breach entry (not every tick); history recorder responds to poll loop.
3. Variables edit round-trip: 4 → pick wait_timeout → [e] → change value → [Enter] confirm → verify variable updated via SHOW GLOBAL VARIABLES LIKE 'wait_timeout'.
4. PS instrument commit round-trip: 5 → Instruments tab → Space toggles a row → [c] commits → verify via SELECT * FROM performance_schema.setup_instruments WHERE NAME = '...'.
5. CSV export round-trip: 6 → navigate to a report → [x] → save to /tmp/export.csv → verify file is valid RFC-4180 CSV (no trailing spaces, formula cells prefixed with ').
6. Replica panel (MySQL 5.7.6+): connect to a replica → 1 → Server Status → replica card shows configured/not-configured state; [g] opens GTID mode selector; [c] cycles modes; Enter commits SET @@GLOBAL.GTID_MODE = ....

PostgreSQL smoke

Requires a scratch PostgreSQL 10+ instance. Validates PostgresWidgetCatalog and pg_stat_database aggregation.

1. php bin/candy-query --dsn pgsql://user:pass@localhost:5432/testdb — connects; status bar shows PostgreSQL version.
2. Widgets show pg_stat_database-backed values (not empty/not stub).
3. shared_buffers shows byte value (scaled from 8KB block count × 8192).

Known limitations (documented, not fixed in this audit)

• hasStoredPrograms() in ServerStatusPage renders via a sync information_schema.ROUTINES query. Low-overhead on typical servers; worth monitoring on routine-heavy schemas.
• GTID mode cycling uses array_search strict comparison — current enum value is shown verbatim; cycling starts at index 0 on mismatch. MySQL normalizes GTID_MODE to uppercase so this is academic.
• CSV export for empty tables produces a blank file (LIMIT 0/LIMIT 1 column detection requires at least one row).
• AlertNotifier is final — spy injection via ReflectionProperty::setValue() blocked by PHP typed-property enforcement. Dedup behavioral test deferred.

Demos.

VHS-recorded GIFs of every example shipped with the app. Regenerated automatically on every push that touches the source.

Play

Browse tables, load rows, run an ad-hoc query.

Query history

↑↓ cycles through history, Ctrl+F favorites a query.