Download the PHP package myneid/laravel-db-tui without Composer

laravel-db-tui

I built this because I kept getting frustrated bouncing between TablePlus, my terminal, and VSCode just to check on data or run a quick query. SSHing into a server to use the MySQL CLI is painful, and switching apps constantly breaks the flow. I wanted something that lived right in the console — where I already spend most of my time — that could handle the things I actually reach for a GUI to do: browse tables, sort, inspect a row, edit a value, run ad-hoc SQL. This is that tool.

An interactive terminal UI for browsing and editing your Laravel application's database — or any remote MySQL, PostgreSQL, or SQLite database — without leaving the command line.

Features

• Browse any table — scrollable table list on the left, paginated row view on the right
• Fixed-width, resizable columns — each column gets a sensible default width based on its content; widen, narrow, or hide columns from a dedicated popup instead of everything getting squeezed evenly
• Sort columns — press 1–9 to sort by that column, again to toggle ASC/DESC
• Inspect rows — press Enter on a row to see every field in a word-wrapped key/value layout
• Edit and save rows — edit any field in the detail view and write it back to the database
• SQL popup runner — open a query window from anywhere, execute SQL, and inspect results
• Context-aware autocomplete — table names after FROM/JOIN, columns in SELECT/WHERE, alias.column completion with Tab
• Saved connections — store named connection URLs in ~/.laravel-db-tui.json, outside any repo
• Remote connections — connect to any MySQL, PostgreSQL, or SQLite database via URL
• Faster remote browsing — table metadata/page results are cached in-memory during a session
• Mouse support — click to select a table or row, scroll wheel to navigate
• Uses Laravel's existing config — zero setup for the default database connection

Requirements

• PHP 8.1+
• Laravel 10, 11, 12, or 13
• A terminal that supports ANSI escape codes (macOS Terminal, iTerm2, Windows Terminal, most Linux terminals)

Installation

Laravel's package auto-discovery will register the db:tui command automatically. No service provider registration needed.

First time publishing this package? Replace myneid with your actual Packagist vendor name in composer.json and in all namespace declarations across the src/ files.

Quick start

Usage

--url format

Passwords with special characters should be URL-encoded (e.g. p@ss → p%40ss).

Saved connections

Connection URLs (including passwords) are stored in ~/.laravel-db-tui.json in your home directory. This file is never inside a project, so it cannot be accidentally committed.

Key bindings

Tables panel (left)

Data panel (right)

Columns are fixed-width (sized from their header/content, capped at 40 chars by default) instead of being split evenly, so a short id column doesn't get the same width as a long email column. When the visible columns are wider than the panel, the title shows ←N/→N for how many columns are scrolled off each side.

Columns popup

Opened with c from the data panel. Lists every column on the current table with a checkbox and its current width.

Hidden columns and custom widths are remembered per table for the rest of the session.

Row detail view

Fields are word-wrapped. Edited-but-unsaved fields are shown in yellow with a ● marker. The title bar shows [UNSAVED CHANGES] when there is anything pending.

Storing null: type the literal word NULL (uppercase) in the edit buffer and confirm — the field will be written as a database NULL.

Saving uses the table's primary key as the WHERE clause when one is detected, and falls back to matching all original column values if no primary key is found.

SQL editor

Autocomplete is context-aware:

• after FROM, JOIN, UPDATE, INTO: suggests table names
• after SELECT, WHERE, ON, ORDER BY, GROUP BY: suggests columns from tables in your query
• for alias. or table.: suggests matching columns for that alias/table

Non-SELECT statements (INSERT, UPDATE, DELETE, CREATE, etc.) are supported — the results panel shows the number of affected rows.

SQL result row detail

Click any result row to open the same full key/value edit view used for table rows (see Row detail (edit mode) below).

Editing is only enabled when the query is a plain SELECT from a single table (no JOIN, and every selected column maps to a real column on that table). Anything else — joins, computed/aliased columns, non-SELECT statements — opens the same view read-only, marked [READ-ONLY] in the title.

Mouse

UI panels

Browse mode

The active panel is indicated by a double-line border (╔═╗) and brackets around the title. Inactive panels use a rounded border (╭─╮).

Row detail (edit mode)

Architecture

The package follows a simple four-layer design:

State machine (App): The Mode enum drives which key bindings are active and which panel is rendered. State transitions are:

Editing (App): Row detail tracks editFieldIndex, isEditing, editBuffer, and dirtyValues. Confirming an edit stages the change in dirtyValues; pressing s flushes all staged changes in a single UPDATE statement and refreshes the page. Row and SqlRow share this same mechanism — SqlRow resolves its target table via sqlResultTable, detected from the executed SQL (null when the query isn't a single plain table, which disables saving).

Column layout (App): columnWidths and hiddenColumns are override maps keyed by "table.column", so preferences are scoped per table. Auto-computed default widths are cached in defaultColumnWidths whenever a page of rows is fetched (based on header/content length, capped at 40 chars); columnWidth() returns the user override if one exists, otherwise the cached default. The Data table only sends Renderer as many fixed-width columns as fit the panel, starting at columnOffset, so a wide table scrolls horizontally instead of every column being squeezed into an even percentage.

Rendering (Renderer): Stateless — called every frame (~60 fps), reads App and builds a GridWidget tree. It also receives the current terminal width (fetched each frame in DbTuiCommand) so the Data table can decide how many fixed-width columns fit. php-tui diffs the widget tree against the previous frame before writing to the terminal.

Database (PdoConnection): Raw PDO only — no Eloquent, no query builder. Identifiers are quoted per-driver to prevent injection from schema-derived names. Raw SQL mode executes user input directly (intentional for a developer tool). updateRow() uses the primary key as the WHERE predicate when available.

Performance (App): While the TUI is open, per-table metadata (columns, COUNT(*)) and fetched pages are cached in memory. Moving through the table list no longer eagerly loads every highlighted table; load happens when you open a table with Enter/Tab/→ (or click into the data panel).

Customising

Page size

The default page size is 200 rows. To change it, set $app->limit before calling $app->init() in DbTuiCommand::handle():

Adding a connection type

PdoConnection handles the three standard drivers. To add another (e.g. SQL Server via sqlsrv), extend PdoConnection and override getTables(), getColumns(), getPrimaryKey(), and qi().

License

MIT — do whatever you want with it.