+ A recorded walkthrough of sql-bomb, running against a local
+ Flight SQL server with sample data.
+ Hover to pause, or choose a view above to explore.
+
+
+
+
+ 01 / QUERY
+
Stay in your flow.
+
Multiline SQL, table and column suggestions, and a searchable action menu.
+
+
+ 02 / EXPLORE
+
Follow the rows.
+
Browse results as they arrive.
+ Open a cell to see the complete value and its type.
+
+
+ 03 / KEEP
+
Good SQL deserves an encore.
+
Return to local history, star a useful query, and reopen saved connections.
Install commands require a published release.
+ Build from source
+ to run this checkout.
+
+
+
+
+
+
+
+
+
diff --git a/crates/completion/Cargo.toml b/crates/completion/Cargo.toml
index 0cfab25..41fcd97 100644
--- a/crates/completion/Cargo.toml
+++ b/crates/completion/Cargo.toml
@@ -3,6 +3,8 @@ name = "sql-bomb-completion"
version = "0.1.0"
edition = "2024"
license = "MIT"
+description = "SQL table and column completion from cursor position and catalog metadata"
+repository = "https://github.com/fusor-rs/sql-bomb"
[dependencies]
thiserror.workspace = true
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..11219f4
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,35 @@
+# How it works
+
+This page describes the implementation for contributors. The
+[workspace guide](workspace.md) covers using the app.
+
+## Clients and results
+
+Each client implements the public [QueryClient trait](../src/lib.rs), the shared
+Rust interface for running queries. It returns the columns and their types,
+followed by a stream of Arrow record batches: chunks of rows stored by column.
+Errors can arrive with the stream. The terminal displays a window of those rows
+and columns while keeping received rows in memory.
+
+The [client registry](../src/client.rs) supplies the chooser, CLI flags, and
+connection setup. Network operations run in Tokio, Rust's asynchronous runtime,
+so the interface can respond while results arrive.
+
+Each Flight SQL query opens a gRPC connection, executes a statement, and reads all
+returned endpoints in order. When an endpoint advertises multiple locations,
+sql-bomb uses the first. The optional `QueryClient::tables()` method uses the
+Flight SQL `CommandGetTables` operation with schemas included. It returns each
+table's catalog, database schema, name, type, and Arrow column schema.
+
+## Terminal interface
+
+Fusor connects the [HTML template](../ui/app.html) to
+[Rust state](../src/terminal.rs), updating the view when that state changes.
+Hypercmd handles terminal layout, focus, and input.
+
+## SQL suggestions
+
+The independent [completion crate](../crates/completion) uses Tree-sitter, a
+parser library, to read SQL around the cursor. It combines that syntax with table
+and column information from the client and returns text edits to the editor.
+It runs inside sql-bomb; it does not start a language server or execute SQL.
diff --git a/docs/flight-sql.md b/docs/flight-sql.md
new file mode 100644
index 0000000..3fa8ceb
--- /dev/null
+++ b/docs/flight-sql.md
@@ -0,0 +1,58 @@
+# Clients and Flight SQL
+
+A client is the part of sql-bomb that connects to a server and runs queries.
+Flight SQL is currently the only client; PostgreSQL and MySQL clients are not
+implemented. Arrow Flight SQL sends SQL over gRPC and receives results in Apache
+Arrow format, which preserves each column's data type.
+
+## Connection address
+
+Choose **Flight SQL** in the client chooser, or pass its flag:
+
+```sh
+boom --flightsql
+boom --flightsql http://localhost:50051
+```
+
+The first command opens the connection form. The second also skips the form, so
+use it for connections without headers. An address without the flag, such as
+`boom http://localhost:50051`, fills in the form after you choose a client.
+
+The server URL contains a scheme, host, and port, such as
+`http://localhost:50051` or `https://sql.example.com:443`. Credentials, paths, and
+query parameters do not belong in the URL. Use `http://` or `grpc+tcp://` for an
+unencrypted connection. Use `https://` or `grpc+tls://` for TLS encryption with
+certificates trusted by your operating system.
+
+## Authentication
+
+Headers are extra name/value pairs sent with a request, often to carry a token.
+Leave the field empty if your server needs none. Otherwise, enter one header per
+line as `name: value`:
+
+```text
+authorization: Bearer YOUR_TOKEN
+x-tenant: YOUR_TENANT
+```
+
+Header names and values must be ASCII; binary metadata is not supported.
+Authentication uses these headers. Flight handshake authentication and client
+certificates (mutual TLS) are not implemented.
+
+A Flight SQL server can direct sql-bomb to another address to fetch results.
+Headers are sent only to addresses with the same scheme, host, and port as the
+configured server. See the
+[Arrow Flight protocol](https://arrow.apache.org/docs/format/Flight.html) for the
+protocol's endpoint and authentication conventions.
+
+## Remembering headers
+
+Headers stay in memory unless you check **Remember headers securely** when saving
+a connection. This option is off by default. It stores headers in macOS Keychain
+or Linux Secret Service. On Linux, the Secret Service keyring must be unlocked
+and available on your session D-Bus.
+
+Without that option, reopening a saved connection that used headers asks for
+them again. Renaming the connection without entering headers keeps that prompt.
+Credential-store failures appear in the form. Headers are never saved in query
+history or written to a plaintext fallback file.
diff --git a/docs/get-started.md b/docs/get-started.md
new file mode 100644
index 0000000..d54471a
--- /dev/null
+++ b/docs/get-started.md
@@ -0,0 +1,80 @@
+# Get started
+
+sql-bomb runs in a terminal on macOS or Linux. To run queries, you need the address
+of a server that supports [Arrow Flight SQL](flight-sql.md). sql-bomb connects to
+that server; it does not start a database for you.
+
+## Install with Cargo
+
+Cargo is Rust's package manager, included when you install Rust through
+[rustup](https://rustup.rs). After a sql-bomb release is published to crates.io,
+you can install the `boom` executable with:
+
+```sh
+cargo install sql-bomb --locked
+boom
+```
+
+`--locked` uses the dependency versions recorded in the release. Cargo installs
+`boom` in `~/.cargo/bin` by default; that directory needs to be in your shell's PATH.
+
+## Install a binary release
+
+The shell installer downloads the latest published GitHub release for x86-64 or
+ARM64 on Linux or macOS. It verifies the download's SHA-256 checksum and installs
+`boom` in `~/.sqlbomb/bin`, without sudo or a Rust toolchain:
+
+```sh
+curl -fsSL https://boom.fusor.build/install.sh | sh
+export PATH="$HOME/.sqlbomb/bin:$PATH"
+boom
+```
+
+Add the `export` line to your shell profile, such as `~/.zshrc` or `~/.bashrc`, so
+new terminals can find `boom`. Run the installer again to upgrade. To select a
+release, append `-s -- v0.1.0` to `sh`. Set `SQL_BOMB_INSTALL` on the `sh` command
+to choose a different install directory; the executable goes in its `bin/`.
+Saved connections, query history, and stars are left untouched.
+
+This method requires a GitHub release with completed binary uploads.
+
+## Connect to a server
+
+1. Run `boom` and choose **Flight SQL**, the only client currently available.
+2. Enter your server URL, including its scheme and port, such as
+ `http://localhost:50051`. This example requires a server already running at that
+ address. Use `https://` for a server with TLS encryption.
+3. If the server requires authentication, enter its request headers, such as
+ `authorization: Bearer YOUR_TOKEN`. Otherwise, leave the headers empty.
+4. Select **Open workspace**.
+
+Type a query in the editor and press Ctrl+R, or click **Run**:
+
+```sql
+SELECT 1 AS value;
+```
+
+Rows appear below the editor as the server sends them. Press Ctrl+C to quit.
+
+For a connection without headers, you can skip the chooser and form:
+
+```sh
+boom --flightsql http://localhost:50051
+```
+
+Once you save a connection, `boom` opens your saved connections instead. See
+[Using sql-bomb](workspace.md) for saving connections and browsing results, or
+[Flight SQL](flight-sql.md) for supported URLs and authentication.
+
+## Build from source
+
+With Rust and Cargo installed, clone the repository and install from the checkout:
+
+```sh
+git clone https://github.com/fusor-rs/sql-bomb
+cd sql-bomb
+cargo install --path . --locked
+boom
+```
+
+For development, `cargo run --locked` builds and launches the app from the checkout.
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..ee7fe65
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,20 @@
+# sql-bomb
+
+sql-bomb is a terminal application for running SQL and streaming results into a
+table. You can inspect complete cell values and return to queries from your local
+history or starred library. The installed executable is named `boom`.
+
+Flight SQL is currently the only supported connection type. It connects to
+servers that implement Arrow Flight SQL, a protocol for running SQL over gRPC.
+Direct PostgreSQL and MySQL connections are not implemented.
+
+The terminal interface is built with
+[Hypercmd](https://github.com/fusor-rs/hypercmd) and
+[Fusor](https://github.com/fusor-rs/fusor).
+
+**In development · v0.1** — See [available clients](flight-sql.md) and
+[status and known limitations](status.md).
+
+[Get started](get-started.md) · [Using sql-bomb](workspace.md) ·
+[Clients](flight-sql.md) · [How it works](architecture.md) · [Status](status.md) ·
+[Contributing](../README.md#contributing)
diff --git a/docs/status.md b/docs/status.md
new file mode 100644
index 0000000..d8903c2
--- /dev/null
+++ b/docs/status.md
@@ -0,0 +1,18 @@
+# Status and known limitations
+
+sql-bomb is in early development. Queries currently target statements that return
+rows, such as `SELECT`. Client availability and protocol-specific limits are
+listed under [Clients](flight-sql.md).
+
+| Area | Included |
+| --- | --- |
+| Query workspace | Multiline SQL editor, searchable action menu, keyboard and mouse controls |
+| SQL suggestions | Qualified tables and columns from referenced tables and aliases |
+| Results | Streaming table, cancellation, and full cell inspection |
+| Query library | Local history and starred queries in SQLite |
+| Saved connections | Searchable saved connections; optional OS credential storage |
+| Terminal platforms | macOS and Linux |
+
+All received rows stay in memory until another query starts or the connection
+changes. **Cancel** stops receiving results. It does not send a server-side SQL
+cancellation command, so the server decides whether to keep running the query.
diff --git a/docs/workspace.md b/docs/workspace.md
new file mode 100644
index 0000000..f721dbd
--- /dev/null
+++ b/docs/workspace.md
@@ -0,0 +1,124 @@
+# Using sql-bomb
+
+## Saved connections
+
+Check **Save on this device** in the connection form. Give it a name
+(the hostname is suggested), then choose **Save & open**. Leave the checkbox
+unchecked for a session-only connection. A direct CLI launch remains unsaved;
+**Menu → Save connection…** saves it without clearing SQL or results.
+
+When saved connections exist, launching `boom` opens **Connections**. Search
+by name, client, or address; recently opened connections appear first. Click a row,
+or use Up/Down and Enter, to open it. **New connection**, **Edit**, and **Remove**
+are visible actions. Editing requires **Save changes**; Escape discards the edit.
+Removal asks for confirmation and keeps query history, stars, and the active workspace.
+
+Saved connections live in `~/.sqlbomb/queries.sqlite3`. Authentication and credential
+storage options are described in the [client settings](flight-sql.md).
+
+## The menu
+
+**Menu** is always visible in the header. Click it or press Ctrl+K, then search
+for an action. Click a result to open it, or use Up/Down and Enter. Unavailable
+actions explain what is needed when selected.
+
+Press `/` in results, previews, or other non-editing controls to open the same
+menu. In text fields, `/` remains ordinary text. Search for an action by name, such as
+`history`; a leading `/` is optional. Escape restores the previous pane, including the editor's
+cursor and selection. Queries continue streaming while the menu is open.
+
+## SQL suggestions
+
+Clients that implement table discovery provide suggestions as you type. After
+`FROM` or `JOIN`, the editor suggests tables from the active connection, including
+catalog and schema qualifiers. In column positions, it suggests columns from
+referenced tables and aliases, with their data types and source tables.
+
+Use Up/Down to choose a suggestion, then Tab or a click to insert it. Insertion
+replaces the identifier at the caret and preserves the rest of the query. Escape
+closes suggestions; Enter inserts a newline. Suggestions stay out of comments
+and string literals. Quoted identifiers preserve their quoting style.
+The list shows a bounded set of matches; keep typing to narrow it.
+
+Table and column information is loaded when you open the workspace and kept in
+memory. **Refresh schema** reloads it after database changes or a discovery
+failure. Loading and failures appear beneath the editor; typing and executing SQL
+remain available. Clients without discovery work without suggestions.
+
+Completion resolves catalog tables and aliases within the current statement or
+subquery. Columns derived from `WITH` queries (CTEs), subquery select lists, and
+set operations such as `UNION` are not resolved. Ambiguous table references do not
+produce guessed column lists.
+
+## Results
+
+The multiline editor preserves pasted SQL, including comments and string
+literals. Results appear as rows arrive. Column headers stay visible,
+the selected cell is highlighted, and the footer shows your row and column.
+Use the arrow keys to browse or the mouse wheel to scroll.
+
+Long values end with an ellipsis. Enter opens the complete selected value and its
+data type in a scrollable inspector. Large values are split into bounded parts
+with Previous/Next controls. **Error details** opens the complete query error.
+HTTP(S) cells show **Open link ↗**; a normal left click opens the full destination
+in your browser.
+
+**Cancel** stops receiving rows and keeps the results already received. While a
+query streams, your selection stays put; End jumps to the latest row.
+
+## History and starred queries
+
+**Library** opens searchable **History** and **Starred** tabs. Filter by SQL or
+connection address, browse the list, and preview the selected query. Each entry
+includes its original server address and local timestamp. The panes stack in narrow
+terminals.
+
+**Use query** or Enter loads the full SQL into your current connection's editor
+without executing it. Escape returns to your unchanged draft. **Star** or Ctrl+S
+saves the editor's query, including SQL you have not run. In the library, it
+stars or unstars the selected query. A star belongs to the exact SQL and server address;
+editing that SQL creates a different query to star.
+
+History and stars live in `~/.sqlbomb/queries.sqlite3`, outside the project.
+Every run attempt is recorded before contacting the server, including failed and
+cancelled queries. Repeated executions remain separate history entries. The
+library survives restarts and supports multiple sql-bomb sessions.
+
+New directories and database files are private to your account. The database
+stores full SQL and server addresses in plaintext, with no automatic history expiry.
+Storage errors are displayed rather than silently dropping the record.
+
+## Keyboard and mouse
+
+The Menu lists actions and their shortcuts. The full reference is below.
+
+| Key | Action |
+| --- | --- |
+| Ctrl+K or Menu | Open or close the searchable action menu |
+| / outside text fields | Open the menu |
+| Command+Enter in SQL or Ctrl+R | Run the SQL in the editor |
+| Ctrl+E / Ctrl+L | Focus SQL / results |
+| Ctrl+P | Open the query library / focus its search |
+| Ctrl+S | Star or unstar the editor's query / selected library query |
+| Enter in library search or list | Load the selected query into the editor |
+| Up / Down, then Enter in Connections | Choose and open a saved connection |
+| Space on a checkbox | Toggle saving or remembering headers |
+| Enter in SQL | Insert a newline |
+| Ctrl+A in SQL | Select the entire query |
+| Tab or Shift+Tab | Move between controls and panes |
+| Arrows in results | Select a cell and reveal it when outside the window |
+| PageUp / PageDown | Move one page through results or the inspector |
+| Up / Down in library | Select the previous / next query |
+| PageUp / PageDown in library | Browse one page of queries |
+| Home / End in results | Select the first / last received row |
+| Enter in results | Inspect the selected cell |
+| Mouse wheel | Scroll the pane under the pointer |
+| Shift+wheel or horizontal wheel | Move through result columns |
+| Escape | Go back from connection setup, library, or inspector; otherwise cancel a running query |
+| Ctrl+C | Quit and restore the terminal |
+
+Command+Enter works only if your terminal forwards the Command key through
+[enhanced keyboard reporting](https://sw.kovidgoyal.net/kitty/keyboard-protocol/).
+If your terminal reserves that shortcut, map it to `ESC [ 13 ; 9 u` (without
+spaces), or use Ctrl+R. Link clicks use `open` on macOS or `xdg-open` on Linux.
+Modifier-click gestures belong to the terminal emulator.
diff --git a/examples/site-preview/sample.sql b/examples/site-preview/sample.sql
new file mode 100644
index 0000000..c69a2e6
--- /dev/null
+++ b/examples/site-preview/sample.sql
@@ -0,0 +1,13 @@
+CREATE TABLE destinations (
+ city TEXT,
+ country TEXT,
+ distance_km INTEGER
+);
+
+INSERT INTO destinations VALUES
+ ('Lisbon', 'Portugal', 5420),
+ ('Montréal', 'Canada', 534),
+ ('Tokyo', 'Japan', 10838),
+ ('Copenhagen', 'Denmark', 6198),
+ ('Buenos Aires', 'Argentina', 8523),
+ ('Reykjavík', 'Iceland', 4208);
diff --git a/examples/site-preview/server.rs b/examples/site-preview/server.rs
new file mode 100644
index 0000000..9ce5e45
--- /dev/null
+++ b/examples/site-preview/server.rs
@@ -0,0 +1,142 @@
+use arrow_array::{ArrayRef, Int64Array, RecordBatch, StringArray};
+use arrow_flight::{
+ FlightDescriptor, FlightEndpoint, FlightInfo, Ticket,
+ encode::FlightDataEncoderBuilder,
+ error::FlightError,
+ flight_service_server::{FlightService, FlightServiceServer},
+ sql::{
+ CommandGetTables, CommandStatementQuery, ProstMessageExt, SqlInfo, TicketStatementQuery,
+ server::FlightSqlService,
+ },
+};
+use futures_util::{TryStreamExt, stream};
+use prost::Message;
+use std::sync::Arc;
+use tokio::net::TcpListener;
+use tokio_stream::wrappers::TcpListenerStream;
+use tonic::{Request, Response, Status, transport::Server};
+
+const SAMPLE_QUERY: &str = "SELECT city, country, distance_km FROM destinations";
+
+struct Destinations;
+
+pub(super) async fn start() -> Result> {
+ let listener = TcpListener::bind("127.0.0.1:0").await?;
+ let address = format!("http://{}", listener.local_addr()?);
+ tokio::spawn(async move {
+ if let Err(error) = Server::builder()
+ .add_service(FlightServiceServer::new(Destinations))
+ .serve_with_incoming(TcpListenerStream::new(listener))
+ .await
+ {
+ eprintln!("Preview Flight SQL server failed: {error}");
+ }
+ });
+ Ok(address)
+}
+
+fn query(sql: &str) -> Result> {
+ let database = rusqlite::Connection::open_in_memory()?;
+ database.execute_batch(include_str!("sample.sql"))?;
+ let mut statement = database.prepare(sql)?;
+ let mut cities = Vec::new();
+ let mut countries = Vec::new();
+ let mut distances = Vec::new();
+ let mut rows = statement.query([])?;
+ while let Some(row) = rows.next()? {
+ cities.push(row.get::<_, String>(0)?);
+ countries.push(row.get::<_, String>(1)?);
+ distances.push(row.get::<_, i64>(2)?);
+ }
+ Ok(RecordBatch::try_from_iter([
+ ("city", Arc::new(StringArray::from(cities)) as ArrayRef),
+ (
+ "country",
+ Arc::new(StringArray::from(countries)) as ArrayRef,
+ ),
+ (
+ "distance_km",
+ Arc::new(Int64Array::from(distances)) as ArrayRef,
+ ),
+ ])?)
+}
+
+#[tonic::async_trait]
+impl FlightSqlService for Destinations {
+ type FlightService = Self;
+
+ async fn get_flight_info_statement(
+ &self,
+ command: CommandStatementQuery,
+ _request: Request,
+ ) -> Result, Status> {
+ let batch =
+ query(&command.query).map_err(|error| Status::invalid_argument(error.to_string()))?;
+ flight_info(
+ &batch,
+ Ticket::new(
+ TicketStatementQuery {
+ statement_handle: command.query.into(),
+ }
+ .as_any()
+ .encode_to_vec(),
+ ),
+ )
+ }
+
+ async fn do_get_statement(
+ &self,
+ ticket: TicketStatementQuery,
+ _request: Request,
+ ) -> Result::DoGetStream>, Status> {
+ let sql = std::str::from_utf8(&ticket.statement_handle)
+ .map_err(|error| Status::invalid_argument(error.to_string()))?;
+ let batch = query(sql).map_err(|error| Status::invalid_argument(error.to_string()))?;
+ Ok(encode(batch))
+ }
+
+ async fn get_flight_info_tables(
+ &self,
+ command: CommandGetTables,
+ _request: Request,
+ ) -> Result, Status> {
+ let ticket = Ticket::new(command.as_any().encode_to_vec());
+ flight_info(&tables(command)?, ticket)
+ }
+
+ async fn do_get_tables(
+ &self,
+ command: CommandGetTables,
+ _request: Request,
+ ) -> Result::DoGetStream>, Status> {
+ Ok(encode(tables(command)?))
+ }
+
+ async fn register_sql_info(&self, _identifier: i32, _result: &SqlInfo) {}
+}
+
+fn tables(command: CommandGetTables) -> Result {
+ let batch = query(SAMPLE_QUERY).map_err(|error| Status::internal(error.to_string()))?;
+ let mut tables = command.into_builder();
+ tables.append("", "", "destinations", "TABLE", &batch.schema())?;
+ tables
+ .build()
+ .map_err(|error| Status::internal(error.to_string()))
+}
+
+fn flight_info(batch: &RecordBatch, ticket: Ticket) -> Result, Status> {
+ Ok(Response::new(
+ FlightInfo::new()
+ .try_with_schema(&batch.schema())
+ .map_err(FlightError::from)?
+ .with_endpoint(FlightEndpoint::new().with_ticket(ticket)),
+ ))
+}
+
+fn encode(batch: RecordBatch) -> Response<::DoGetStream> {
+ let encoded = FlightDataEncoderBuilder::new()
+ .with_schema(batch.schema())
+ .build(stream::iter([Ok(batch)]))
+ .map_err(Status::from);
+ Response::new(Box::pin(encoded))
+}
diff --git a/examples/site-preview/snapshot.rs b/examples/site-preview/snapshot.rs
new file mode 100644
index 0000000..5d93cfb
--- /dev/null
+++ b/examples/site-preview/snapshot.rs
@@ -0,0 +1,135 @@
+use std::io::{self, Read};
+use vt100::{Cell, Color, Screen};
+
+const CELL_WIDTH: u16 = 8;
+const CELL_HEIGHT: u16 = 17;
+const BASELINE: u16 = 13;
+
+#[derive(Clone, Copy)]
+pub(super) enum Format {
+ Svg,
+ Text,
+}
+
+struct TextRun<'screen> {
+ cell: &'screen Cell,
+ column: u16,
+ row: u16,
+ columns: u16,
+ text: String,
+}
+
+pub(super) fn write(format: Format) -> Result<(), Box> {
+ let mut dimensions = std::env::args().skip(2);
+ let columns = dimensions.next().ok_or("Pass columns")?.parse()?;
+ let rows = dimensions.next().ok_or("Pass rows")?.parse()?;
+ let mut bytes = Vec::new();
+ io::stdin().read_to_end(&mut bytes)?;
+ let mut parser = vt100::Parser::new(rows, columns, 0);
+ parser.process(&bytes);
+ match format {
+ Format::Text => println!("{}", parser.screen().contents()),
+ Format::Svg => svg(parser.screen())?,
+ }
+ Ok(())
+}
+
+fn svg(screen: &Screen) -> Result<(), Box> {
+ let (rows, columns) = screen.size();
+ println!(
+ r##"");
+ Ok(())
+}
+
+fn paint_row(screen: &Screen, row: u16) -> Result<(), Box> {
+ let mut column = 0;
+ while column < screen.size().1 {
+ let start = column;
+ let cell = screen.cell(row, column).expect("cell is inside the screen");
+ let mut text = String::new();
+ while let Some(next) = screen
+ .cell(row, column)
+ .filter(|next| same_style(cell, next))
+ {
+ if next.has_contents() {
+ text.push_str(&next.contents());
+ } else if !next.is_wide_continuation() {
+ text.push(' ');
+ }
+ column += 1;
+ }
+ paint(&TextRun {
+ cell,
+ column: start,
+ row,
+ columns: column - start,
+ text,
+ })?;
+ }
+ Ok(())
+}
+
+fn same_style(first: &Cell, second: &Cell) -> bool {
+ first.fgcolor() == second.fgcolor()
+ && first.bgcolor() == second.bgcolor()
+ && first.bold() == second.bold()
+ && first.italic() == second.italic()
+ && first.underline() == second.underline()
+ && first.inverse() == second.inverse()
+}
+
+fn paint(run: &TextRun<'_>) -> Result<(), Box> {
+ let cell = run.cell;
+ let left = run.column * CELL_WIDTH;
+ let top = run.row * CELL_HEIGHT;
+ let width = run.columns * CELL_WIDTH;
+ let mut foreground = color(cell.fgcolor(), "#faf9f6")?;
+ let mut background = color(cell.bgcolor(), "#272a2c")?;
+ if cell.inverse() {
+ std::mem::swap(&mut foreground, &mut background);
+ }
+ println!(
+ r#""#,
+ );
+ if !run.text.trim().is_empty() {
+ let weight = if cell.bold() { "bold" } else { "normal" };
+ let style = if cell.italic() { "italic" } else { "normal" };
+ let decoration = if cell.underline() {
+ "underline"
+ } else {
+ "none"
+ };
+ let baseline = top + BASELINE;
+ let escaped = run
+ .text
+ .replace('&', "&")
+ .replace('<', "<")
+ .replace('>', ">");
+ println!(
+ r#"{escaped}"#,
+ );
+ }
+ Ok(())
+}
+
+fn color(color: Color, default: &str) -> Result> {
+ match color {
+ Color::Default => Ok(default.into()),
+ Color::Rgb(red, green, blue) => Ok(format!("#{red:02x}{green:02x}{blue:02x}")),
+ Color::Idx(index) => {
+ Err(format!("Expected native RGB colors, found palette index {index}").into())
+ }
+ }
+}
diff --git a/justfile b/justfile
new file mode 100644
index 0000000..7ac3398
--- /dev/null
+++ b/justfile
@@ -0,0 +1,49 @@
+fusor := env_var_or_default("FUSOR_BIN", "fusor")
+
+default:
+ @just --list
+
+check:
+ cargo fmt --all -- --check
+ cargo clippy --workspace --all-targets --locked -- -D warnings
+ cargo test --workspace --locked
+
+site-check:
+ cargo fmt --manifest-path apps/Cargo.toml --all -- --check
+ cargo clippy --manifest-path apps/Cargo.toml --workspace --all-targets --locked -- -D warnings
+ cargo test --manifest-path apps/Cargo.toml --workspace --locked
+
+[working-directory: "apps"]
+site:
+ {{fusor}} build --site --locked
+
+preview port="4187":
+ {{fusor}} preview apps/dist --port {{port}}
+
+landing-dev:
+ {{fusor}} dev --manifest-path apps/landing/Cargo.toml
+
+docs-dev:
+ {{fusor}} dev --manifest-path apps/docs/Cargo.toml
+
+capture-preview:
+ python3 scripts/capture-preview.py
+
+site-browser:
+ node scripts/site.mjs
+
+setup-browser:
+ cargo install fusor-cli --version 0.1.4 --locked
+ {{fusor}} install --manifest-path apps/Cargo.toml -p sql-bomb-docs --locked
+ npm ci
+ npx playwright install chromium
+
+[unix]
+deploy environment="production":
+ @case "{{environment}}" in \
+ production|preview) ;; \
+ *) echo "deploy: expected production or preview" >&2; exit 2 ;; \
+ esac
+ vercel build {{ if environment == "production" { "--prod" } else { "" } }} --yes
+ find .vercel/output/static -name '.fusor-*.json' -delete
+ vercel deploy --prebuilt {{ if environment == "production" { "--prod" } else { "" } }} --yes
diff --git a/package-lock.json b/package-lock.json
new file mode 100644
index 0000000..31e78a8
--- /dev/null
+++ b/package-lock.json
@@ -0,0 +1,60 @@
+{
+ "name": "sql-bomb-site",
+ "lockfileVersion": 3,
+ "requires": true,
+ "packages": {
+ "": {
+ "name": "sql-bomb-site",
+ "devDependencies": {
+ "playwright": "1.62.1"
+ }
+ },
+ "node_modules/fsevents": {
+ "version": "2.3.2",
+ "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
+ "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+ "dev": true,
+ "hasInstallScript": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ],
+ "engines": {
+ "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+ }
+ },
+ "node_modules/playwright": {
+ "version": "1.62.1",
+ "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.62.1.tgz",
+ "integrity": "sha512-0M+L3LAD8/nm554LOla9Ayx0j0tmFZ0FBcoQ7F1VuVHpM/XpiC8RcDzBQB8W5+hA8L22THxELzeF+2WcUzvcLg==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "dependencies": {
+ "playwright-core": "1.62.1"
+ },
+ "bin": {
+ "playwright": "cli.js"
+ },
+ "engines": {
+ "node": ">=20"
+ },
+ "optionalDependencies": {
+ "fsevents": "2.3.2"
+ }
+ },
+ "node_modules/playwright-core": {
+ "version": "1.62.1",
+ "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.62.1.tgz",
+ "integrity": "sha512-wPYSwEBJY9GHraISXqyqtx0na0LpO3XEX7jNDhntbex7tzUS7kLnZsOlFruFJB4Hi/rhDMjXGqHewDZ68nYZVw==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "bin": {
+ "playwright-core": "cli.js"
+ },
+ "engines": {
+ "node": ">=20"
+ }
+ }
+ }
+}
diff --git a/package.json b/package.json
new file mode 100644
index 0000000..9d40703
--- /dev/null
+++ b/package.json
@@ -0,0 +1,8 @@
+{
+ "name": "sql-bomb-site",
+ "private": true,
+ "type": "module",
+ "devDependencies": {
+ "playwright": "1.62.1"
+ }
+}
diff --git a/scripts/browser-app.mjs b/scripts/browser-app.mjs
new file mode 100644
index 0000000..8032ffc
--- /dev/null
+++ b/scripts/browser-app.mjs
@@ -0,0 +1,62 @@
+import assert from "node:assert/strict";
+import { execFileSync, spawn } from "node:child_process";
+import { createServer } from "node:net";
+import { join, resolve } from "node:path";
+import { chromium } from "playwright";
+
+export async function checkBrowser(directory, verify, buildArguments = []) {
+ const app = resolve(import.meta.dirname, "..", directory);
+ const fusor = process.env.FUSOR_BIN ?? "fusor";
+ execFileSync(fusor, [
+ "build", ...buildArguments, "--manifest-path", join(app, "Cargo.toml"),
+ "--debug", "--locked", "--offline",
+ ], { cwd: app, stdio: "inherit", timeout: 180_000 });
+ const { server, ready, origin } = await preview(fusor, app);
+ let browser;
+ try {
+ await ready;
+ browser = await chromium.launch();
+ const page = await browser.newPage();
+ page.setDefaultTimeout(15_000);
+ const errors = [];
+ page.on("console", message => {
+ if (message.type() === "error") errors.push(message.text());
+ });
+ page.on("pageerror", error => errors.push(error.message));
+ try {
+ await verify(page, origin);
+ } finally {
+ assert.deepEqual(errors, []);
+ }
+ } finally {
+ await browser?.close();
+ server.kill();
+ if (server.exitCode === null) await new Promise(resolve => server.once("exit", resolve));
+ }
+}
+
+async function preview(fusor, app) {
+ const portPicker = createServer();
+ await new Promise((resolve, reject) => {
+ portPicker.once("error", reject);
+ portPicker.listen(0, "127.0.0.1", resolve);
+ });
+ const port = portPicker.address().port;
+ await new Promise(resolve => portPicker.close(resolve));
+ const server = spawn(fusor, ["preview", join(app, "dist"), "--port", String(port)], { cwd: app });
+ const ready = new Promise((resolve, reject) => {
+ const timeout = setTimeout(() => {
+ reject(new Error("fusor preview did not become ready"));
+ }, 10_000);
+ server.once("error", error => { clearTimeout(timeout); reject(error); });
+ server.once("exit", code => {
+ clearTimeout(timeout);
+ reject(new Error(`fusor preview exited: ${code}`));
+ });
+ server.stderr.on("data", bytes => {
+ if (bytes.toString().includes("Ready.")) { clearTimeout(timeout); resolve(); }
+ });
+ server.stderr.pipe(process.stderr);
+ });
+ return { server, ready, origin: `http://127.0.0.1:${port}/` };
+}
diff --git a/scripts/capture-preview.py b/scripts/capture-preview.py
new file mode 100644
index 0000000..c2e1d08
--- /dev/null
+++ b/scripts/capture-preview.py
@@ -0,0 +1,118 @@
+import errno
+import fcntl
+import os
+from pathlib import Path
+import select
+import signal
+import struct
+import subprocess
+import tempfile
+import termios
+import time
+
+
+ROOT = Path(__file__).resolve().parent.parent
+BINARY = ROOT / "target/debug/examples/site-preview"
+OUTPUT = ROOT / "apps/landing/public/terminal"
+COLUMNS = 110
+ROWS = 28
+TIMEOUT = 20
+# Ratatui ends each draw with these resets; the sample has no hyperlink draw groups.
+FRAME_END = b"\x1b[39m\x1b[49m\x1b[0m"
+QUERY = """SELECT city, country, distance_km
+FROM destinations
+ORDER BY distance_km;"""
+
+
+def render(output, output_format):
+ return subprocess.run(
+ [BINARY, output_format, str(COLUMNS), str(ROWS)],
+ input=output,
+ capture_output=True,
+ check=True,
+ ).stdout
+
+
+def capture(terminal, output, name, expected):
+ deadline = time.monotonic() + TIMEOUT
+ while True:
+ ready, _, _ = select.select([terminal], [], [], max(0, deadline - time.monotonic()))
+ if not ready:
+ raise TimeoutError(f"Waiting for {name}:\n{render(output, '--text').decode()}")
+ chunk = os.read(terminal, 65536)
+ if not chunk:
+ raise RuntimeError(f"Native app exited while capturing {name}")
+ output.extend(chunk)
+ boundary = output.rfind(FRAME_END)
+ if boundary < 0:
+ continue
+ frame = output[:boundary + len(FRAME_END)]
+ text = render(frame, "--text").decode()
+ if all(value in text for value in expected):
+ (OUTPUT / f"{name}.svg").write_bytes(render(frame, "--svg"))
+ print(f"Captured {name}")
+ return
+
+
+def walkthrough(terminal):
+ output = bytearray()
+ capture(terminal, output, "welcome", ["Ready", "Ctrl+C quit"])
+ os.write(terminal, f"\x1b[200~{QUERY}\x1b[201~\x12".encode())
+ capture(terminal, output, "results", ["Complete", "Row 1 / 6", "Tokyo"])
+ os.write(terminal, b"\x0c\r")
+ capture(terminal, output, "inspector", ["Row 1", "Utf8", "Scroll to read"])
+ os.write(terminal, b"\x1b")
+ capture(terminal, output, "results", ["Complete", "Row 1 / 6", "Arrows select"])
+ os.write(terminal, b"\x13\x10")
+ capture(terminal, output, "library", ["Query library", "›★ SELECT", "Menu for more actions"])
+ os.write(terminal, b"\x0b")
+ capture(terminal, output, "menu", ["Find an action", "Browse results", "Enter open"])
+ os.write(terminal, b"\x03")
+
+
+def main():
+ subprocess.run(
+ ["cargo", "build", "--example", "site-preview", "--locked", "--offline"],
+ cwd=ROOT,
+ check=True,
+ )
+ OUTPUT.mkdir(parents=True, exist_ok=True)
+ with tempfile.TemporaryDirectory(prefix="sql-bomb-preview-") as directory:
+ child, terminal = os.forkpty()
+ if child == 0:
+ fcntl.ioctl(0, termios.TIOCSWINSZ, struct.pack("HHHH", ROWS, COLUMNS, 0, 0))
+ environment = {name: value for name, value in os.environ.items() if name != "NO_COLOR"}
+ environment.update(TERM="xterm-256color", COLORTERM="truecolor")
+ os.execve(BINARY, [str(BINARY), directory], environment)
+ try:
+ walkthrough(terminal)
+ drain(terminal)
+ except BaseException:
+ os.kill(child, signal.SIGTERM)
+ os.waitpid(child, 0)
+ raise
+ finally:
+ os.close(terminal)
+ _, status = os.waitpid(child, 0)
+ if status != 0:
+ raise RuntimeError(f"Native app exited with status {status}")
+
+
+def drain(terminal):
+ deadline = time.monotonic() + TIMEOUT
+ while True:
+ ready, _, _ = select.select([terminal], [], [], max(0, deadline - time.monotonic()))
+ if not ready:
+ raise TimeoutError("Native app did not close after Ctrl+C")
+ try:
+ if not os.read(terminal, 65536):
+ return
+ except OSError as error:
+ if error.errno != errno.EIO:
+ raise
+ # Linux PTYs report EIO when the slave closes.
+ return
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/site.mjs b/scripts/site.mjs
new file mode 100644
index 0000000..67da13c
--- /dev/null
+++ b/scripts/site.mjs
@@ -0,0 +1,141 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { checkBrowser } from "./browser-app.mjs";
+
+const root = resolve(import.meta.dirname, "..");
+const navigation = JSON.parse(await readFile(resolve(root, "apps/docs/navigation.json"), "utf8"));
+
+await checkBrowser("apps", async (page, origin) => {
+ await page.setViewportSize({ width: 1440, height: 1100 });
+ await page.clock.install({ time: "2026-01-01T00:00:00Z" });
+ await page.goto(origin);
+ await page.getByRole("heading", { name: "Ultrafast SQL Client in your Terminal" }).waitFor();
+ const installer = await page.request.get(origin + "install.sh");
+ assert.equal(installer.status(), 200);
+ assert.equal(await installer.text(), await readFile(resolve(root, "install.sh"), "utf8"));
+ await page.locator(".example").hover();
+ await checkWalkthrough(page);
+ await page.context().grantPermissions(["clipboard-read", "clipboard-write"]);
+ const methods = page.getByRole("group", { name: "Installation method" });
+ assert.equal(await methods.getByRole("button", { name: "Cargo" }).getAttribute("aria-pressed"),
+ "true");
+ for (const [name, command] of [
+ ["Cargo", "cargo install sql-bomb --locked"],
+ ["Linux", "curl -fsSL https://boom.fusor.build/install.sh | sh"],
+ ]) {
+ const button = methods.getByRole("button", { name, exact: true });
+ await button.click();
+ assert.equal(await button.getAttribute("aria-pressed"), "true");
+ assert.equal(await page.locator("#install-command code").textContent(), command);
+ await page.getByRole("button", { name: "Copy command", exact: true }).click();
+ await page.getByRole("button", { name: "Copied!", exact: true }).waitFor();
+ assert.equal(await page.evaluate(() => navigator.clipboard.readText()), command);
+ }
+ await methods.getByRole("button", { name: "Cargo" }).click();
+ await page.screenshot({ path: resolve(root, "apps/target/landing-desktop.png"), fullPage: true });
+ for (const width of [320, 390, 768]) {
+ await page.setViewportSize({ width, height: 844 });
+ assert.equal(await page.evaluate(() => document.documentElement.scrollWidth), width);
+ }
+ await page.emulateMedia({ reducedMotion: "reduce" });
+ assert.equal(await page.locator(".example").evaluate(node =>
+ getComputedStyle(node).animationName), "none");
+ await page.setViewportSize({ width: 390, height: 844 });
+ await page.screenshot({ path: resolve(root, "apps/target/landing-mobile.png"), fullPage: true });
+ await page.getByRole("link", { name: "Documentation", exact: false }).click();
+ assert.equal(new URL(page.url()).pathname, "/docs/");
+ await checkDocs(page, origin);
+}, ["--site"]);
+console.log("PASS: native walkthrough, clipboard, responsive layout, docs, routing and themes");
+
+async function checkWalkthrough(page) {
+ const controls = page.getByRole("group", { name: "Explore sql-bomb", exact: true });
+ const capture = page.locator(".terminal-capture");
+ for (const [name, filename, expected] of [
+ ["Workspace", "welcome", "Ready"],
+ ["Query", "results", "Montréal"],
+ ["Inspect", "inspector", "Utf8"],
+ ["Library", "library", "SQL PREVIEW"],
+ ["Menu", "menu", "Find an action"],
+ ]) {
+ const button = controls.getByRole("button", { name, exact: true });
+ await button.focus();
+ await page.keyboard.press("Enter");
+ assert.equal(await button.getAttribute("aria-pressed"), "true");
+ assert.equal(await controls.locator('[aria-pressed="true"]').count(), 1);
+ assert.equal(await capture.getAttribute("src"), `/terminal/${filename}.svg`);
+ await capture.evaluate(image => image.decode());
+ const response = await page.request.get(new URL(await capture.getAttribute("src"), page.url()).href);
+ assert.equal(response.status(), 200);
+ assert.ok((await response.text()).includes(expected));
+ }
+ await controls.getByRole("button", { name: "Query", exact: true }).click();
+ const outside = page.getByRole("heading", { name: "Ultrafast SQL Client in your Terminal" });
+ const clockStep = "00:03";
+ await page.clock.pauseAt("2026-01-01T00:01:00Z");
+ await page.clock.fastForward(clockStep);
+ assert.equal(await capture.getAttribute("src"), "/terminal/results.svg");
+ await outside.hover();
+ for (const filename of ["inspector", "library", "menu", "welcome", "results"]) {
+ await page.clock.fastForward(clockStep);
+ assert.equal(await capture.getAttribute("src"), `/terminal/${filename}.svg`);
+ }
+ await capture.hover();
+ await page.clock.fastForward(clockStep);
+ assert.equal(await capture.getAttribute("src"), "/terminal/results.svg");
+ await controls.getByRole("button", { name: "Menu", exact: true }).click();
+ await page.clock.fastForward(clockStep);
+ assert.equal(await capture.getAttribute("src"), "/terminal/menu.svg");
+ await outside.hover();
+ await page.clock.fastForward(clockStep);
+ assert.equal(await capture.getAttribute("src"), "/terminal/welcome.svg");
+ await page.emulateMedia({ reducedMotion: "reduce" });
+ await page.clock.fastForward(clockStep);
+ assert.equal(await capture.getAttribute("src"), "/terminal/welcome.svg");
+ await controls.getByRole("button", { name: "Query", exact: true }).click();
+ assert.equal(await capture.getAttribute("src"), "/terminal/results.svg");
+ await page.emulateMedia({ reducedMotion: "no-preference" });
+ await page.clock.resume();
+}
+
+async function checkDocs(page, origin) {
+ for (const { slug } of navigation) {
+ const filename = `${slug || "index"}.md`;
+ const markdown = await readFile(resolve(root, "docs", filename), "utf8");
+ const title = markdown.split("\n")[0].slice(2);
+ await page.goto(origin + "docs/" + slug);
+ await page.getByRole("heading", { name: title, exact: true }).waitFor();
+ assert.equal(await page.title(), `${title} · sql-bomb`);
+ await page.reload();
+ await page.getByRole("heading", { name: title, exact: true }).waitFor();
+ const bodySizes = await page.locator(".article .lead, .article .markdown").evaluateAll(nodes =>
+ [...new Set(nodes.map(node => getComputedStyle(node).fontSize))]);
+ assert.deepEqual(bodySizes, ["16px"]);
+ const response = await page.request.get(origin + "docs/content/" + filename);
+ assert.equal(response.status(), 200);
+ assert.equal(await response.text(), markdown);
+ await page.setViewportSize({ width: 390, height: 844 });
+ assert.equal(await page.evaluate(() => document.documentElement.scrollWidth), 390);
+ }
+ await page.setViewportSize({ width: 1440, height: 1000 });
+ await page.goto(origin + "docs/");
+ await page.getByRole("searchbox").fill("no-matching-topic");
+ await page.locator(".search-empty").waitFor();
+ await page.getByRole("searchbox").press("Escape");
+ await page.getByRole("button", { name: "Toggle color theme" }).click();
+ await page.reload();
+ await page.locator(".site.dark").waitFor();
+ await page.setViewportSize({ width: 390, height: 844 });
+ await page.getByRole("button", { name: "Toggle navigation" }).click();
+ await page.locator(".sidebar").getByRole("link", { name: "Get started", exact: true }).click();
+ await page.getByRole("heading", { name: "Get started", exact: true }).waitFor();
+ await page.locator(".sidebar").waitFor({ state: "hidden" });
+ await page.screenshot({ path: resolve(root, "apps/target/docs-mobile.png"), fullPage: true });
+ await page.setViewportSize({ width: 1440, height: 1000 });
+ await page.screenshot({ path: resolve(root, "apps/target/docs-desktop.png"), fullPage: true });
+ await page.goto(origin + "docs/missing");
+ await page.getByRole("heading", { name: "Page not found", exact: true }).waitFor();
+ await page.getByRole("link", { name: "Home", exact: true }).click();
+ await page.getByRole("heading", { name: "Ultrafast SQL Client in your Terminal" }).waitFor();
+}
diff --git a/src/site_preview.rs b/src/site_preview.rs
new file mode 100644
index 0000000..48d13e9
--- /dev/null
+++ b/src/site_preview.rs
@@ -0,0 +1,35 @@
+mod cli;
+mod client;
+mod library;
+mod results;
+#[path = "../examples/site-preview/server.rs"]
+mod server;
+#[path = "../examples/site-preview/snapshot.rs"]
+mod snapshot;
+mod terminal;
+
+fn main() -> Result<(), Box> {
+ let directory = std::env::args()
+ .nth(1)
+ .ok_or("Pass a temporary library directory or --svg/--text")?;
+ match directory.as_str() {
+ "--svg" => return snapshot::write(snapshot::Format::Svg),
+ "--text" => return snapshot::write(snapshot::Format::Text),
+ _ => {}
+ }
+ let runtime = tokio::runtime::Builder::new_multi_thread()
+ .enable_all()
+ .build()?;
+ let _runtime = runtime.enter();
+ let address = runtime.block_on(server::start())?;
+ let cli::Command::Start(startup) =
+ cli::parse([client::Client::FlightSql.profile().flag.to_owned(), address].into_iter())?
+ else {
+ cli::help();
+ return Ok(());
+ };
+ let library =
+ library::Library::open(&std::path::Path::new(&directory).join(library::DIRECTORY))?;
+ hypercmd::native::run(hypercmd::mount::((startup, library))?)?;
+ Ok(())
+}
diff --git a/vercel.json b/vercel.json
new file mode 100644
index 0000000..e64ed3b
--- /dev/null
+++ b/vercel.json
@@ -0,0 +1,34 @@
+{
+ "$schema": "https://openapi.vercel.sh/vercel.json",
+ "framework": null,
+ "git": {
+ "deploymentEnabled": false
+ },
+ "installCommand": "",
+ "buildCommand": "just site",
+ "outputDirectory": "apps/dist",
+ "redirects": [
+ {
+ "source": "/docs",
+ "destination": "/docs/",
+ "permanent": true
+ }
+ ],
+ "rewrites": [
+ {
+ "source": "/docs/:path*",
+ "destination": "/docs/index.html"
+ }
+ ],
+ "headers": [
+ {
+ "source": "/(.*)__fusor/(.*)",
+ "headers": [
+ {
+ "key": "Cache-Control",
+ "value": "public, max-age=31536000, immutable"
+ }
+ ]
+ }
+ ]
+}
From 1bc7edf1df2ed7864e8d85f5f6ae96f885f286a9 Mon Sep 17 00:00:00 2001
From: Andres Pirela <60560109+andreespirela@users.noreply.github.com>
Date: Sat, 3 Oct 2026 23:39:13 -0400
Subject: [PATCH 2/3] chore: Feedback
---
README.md | 36 ++++++++++++++++--------------------
apps/docs/public/brand.css | 2 +-
apps/docs/web/index.html | 2 +-
apps/landing/web/index.html | 9 ++++-----
docs/architecture.md | 6 ------
docs/flight-sql.md | 20 ++++++++++++--------
docs/get-started.md | 20 ++++++++------------
docs/index.md | 13 +++++++------
scripts/site.mjs | 2 +-
9 files changed, 50 insertions(+), 60 deletions(-)
diff --git a/README.md b/README.md
index 2825646..3dd5f87 100644
--- a/README.md
+++ b/README.md
@@ -8,13 +8,14 @@
# Query SQL. Watch the rows arrive.
-sql-bomb is a terminal application for running SQL and streaming results into a
-table. You can inspect complete cell values and return to queries from your local
-history or starred library. The installed executable is named `boom`.
+sql-bomb is a database-agnostic terminal application for running SQL and streaming
+results into a table. You can inspect complete cell values, reopen saved
+connections, and return to queries from your local history or starred library.
+The installed executable is named `boom`.
-Flight SQL is currently the only supported connection type. It connects to
-servers that implement Arrow Flight SQL, a protocol for running SQL over gRPC.
-Direct PostgreSQL and MySQL connections are not implemented.
+A client connects sql-bomb to a database server, and every client shares the same
+editor, results table, saved connections, and query library. The
+[client reference](#clients) lists the available clients and their settings.
The terminal interface is built with
[Hypercmd](https://github.com/fusor-rs/hypercmd) and
@@ -29,9 +30,10 @@ The terminal interface is built with
## Get started
-sql-bomb runs in a terminal on macOS or Linux. To run queries, you need the address
-of a server that supports [Arrow Flight SQL](#clients). sql-bomb connects to
-that server; it does not start a database for you.
+sql-bomb runs in a terminal on macOS or Linux. To run queries, you need a running
+database server and its address; the [client reference](#clients) lists the
+connection types sql-bomb supports. sql-bomb connects to that server; it does not
+start a database for you.
### Install with Cargo
@@ -69,7 +71,7 @@ This method requires a GitHub release with completed binary uploads.
### Connect to a server
-1. Run `boom` and choose **Flight SQL**, the only client currently available.
+1. Run `boom` and choose a client from the chooser.
2. Enter your server URL, including its scheme and port, such as
`http://localhost:50051`. This example requires a server already running at that
address. Use `https://` for a server with TLS encryption.
@@ -85,15 +87,10 @@ SELECT 1 AS value;
Rows appear below the editor as the server sends them. Press Ctrl+C to quit.
-For a connection without headers, you can skip the chooser and form:
-
-```sh
-boom --flightsql http://localhost:50051
-```
-
Once you save a connection, `boom` opens your saved connections instead. See
-[Using sql-bomb](#using-sql-bomb) for saving connections and browsing results, or
-[Flight SQL](#clients) for supported URLs and authentication.
+[Using sql-bomb](#using-sql-bomb) for saving connections and browsing results, or the
+[client reference](#clients) for supported URLs, authentication, and
+command-line shortcuts that skip the chooser and form.
### Build from source
@@ -243,8 +240,7 @@ Clients provide connection settings and query execution. The editor, result
browser, saved connections, and query library share the same workspace regardless
of the selected client.
-Flight SQL is currently the only implemented client. PostgreSQL and MySQL clients
-are not implemented.
+Available clients are listed below.
### Flight SQL
diff --git a/apps/docs/public/brand.css b/apps/docs/public/brand.css
index 9dbcf73..2f86a39 100644
--- a/apps/docs/public/brand.css
+++ b/apps/docs/public/brand.css
@@ -15,7 +15,7 @@
.article .lead,
.article .markdown {
- font-size: 16px;
+ font-size: 14px;
line-height: 1.75;
}
.article .inline-code {
diff --git a/apps/docs/web/index.html b/apps/docs/web/index.html
index 4b4aa97..0d5220e 100644
--- a/apps/docs/web/index.html
+++ b/apps/docs/web/index.html
@@ -4,7 +4,7 @@
+ content="Install sql-bomb, connect to a database, and explore streaming query results." />
sql-bomb documentation
diff --git a/apps/landing/web/index.html b/apps/landing/web/index.html
index 3262bfa..f276787 100644
--- a/apps/landing/web/index.html
+++ b/apps/landing/web/index.html
@@ -5,7 +5,7 @@
+ content="A database-agnostic SQL terminal powered by Hypercmd and Fusor." />
@@ -31,8 +31,8 @@
Ultrafast SQL Client in your Terminal
- sql-bomb is a fast SQL client for querying databases and streaming results
- in a beautiful terminal interface, powered by
+ sql-bomb is a fast, database-agnostic SQL workspace for querying databases
+ and streaming results in a beautiful terminal interface, powered by
Hypercmd
and Fusor.
@@ -74,8 +74,7 @@
Ultrafast SQL Client in your Terminal
{{ state.scene.get().description }}
- A recorded walkthrough of sql-bomb, running against a local
- Flight SQL server with sample data.
+ A recorded walkthrough of sql-bomb, running against a local server with sample data.
Hover to pause, or choose a view above to explore.
diff --git a/docs/architecture.md b/docs/architecture.md
index 11219f4..26f3147 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -15,12 +15,6 @@ The [client registry](../src/client.rs) supplies the chooser, CLI flags, and
connection setup. Network operations run in Tokio, Rust's asynchronous runtime,
so the interface can respond while results arrive.
-Each Flight SQL query opens a gRPC connection, executes a statement, and reads all
-returned endpoints in order. When an endpoint advertises multiple locations,
-sql-bomb uses the first. The optional `QueryClient::tables()` method uses the
-Flight SQL `CommandGetTables` operation with schemas included. It returns each
-table's catalog, database schema, name, type, and Arrow column schema.
-
## Terminal interface
Fusor connects the [HTML template](../ui/app.html) to
diff --git a/docs/flight-sql.md b/docs/flight-sql.md
index 3fa8ceb..76b0033 100644
--- a/docs/flight-sql.md
+++ b/docs/flight-sql.md
@@ -1,11 +1,15 @@
-# Clients and Flight SQL
+# Clients
-A client is the part of sql-bomb that connects to a server and runs queries.
-Flight SQL is currently the only client; PostgreSQL and MySQL clients are not
-implemented. Arrow Flight SQL sends SQL over gRPC and receives results in Apache
-Arrow format, which preserves each column's data type.
+A client is the part of sql-bomb that connects to a server and runs queries. The
+editor, results, saved connections, and query library work the same way with every
+client. Available clients are listed below.
-## Connection address
+## Flight SQL
+
+Arrow Flight SQL sends SQL over gRPC and receives results in Apache Arrow format,
+which preserves each column's data type.
+
+### Connection address
Choose **Flight SQL** in the client chooser, or pass its flag:
@@ -24,7 +28,7 @@ query parameters do not belong in the URL. Use `http://` or `grpc+tcp://` for an
unencrypted connection. Use `https://` or `grpc+tls://` for TLS encryption with
certificates trusted by your operating system.
-## Authentication
+### Authentication
Headers are extra name/value pairs sent with a request, often to carry a token.
Leave the field empty if your server needs none. Otherwise, enter one header per
@@ -45,7 +49,7 @@ configured server. See the
[Arrow Flight protocol](https://arrow.apache.org/docs/format/Flight.html) for the
protocol's endpoint and authentication conventions.
-## Remembering headers
+### Remembering headers
Headers stay in memory unless you check **Remember headers securely** when saving
a connection. This option is off by default. It stores headers in macOS Keychain
diff --git a/docs/get-started.md b/docs/get-started.md
index d54471a..65d0fe6 100644
--- a/docs/get-started.md
+++ b/docs/get-started.md
@@ -1,8 +1,9 @@
# Get started
-sql-bomb runs in a terminal on macOS or Linux. To run queries, you need the address
-of a server that supports [Arrow Flight SQL](flight-sql.md). sql-bomb connects to
-that server; it does not start a database for you.
+sql-bomb runs in a terminal on macOS or Linux. To run queries, you need a running
+database server and its address; the [client reference](flight-sql.md) lists the
+connection types sql-bomb supports. sql-bomb connects to that server; it does not
+start a database for you.
## Install with Cargo
@@ -40,7 +41,7 @@ This method requires a GitHub release with completed binary uploads.
## Connect to a server
-1. Run `boom` and choose **Flight SQL**, the only client currently available.
+1. Run `boom` and choose a client from the chooser.
2. Enter your server URL, including its scheme and port, such as
`http://localhost:50051`. This example requires a server already running at that
address. Use `https://` for a server with TLS encryption.
@@ -56,15 +57,10 @@ SELECT 1 AS value;
Rows appear below the editor as the server sends them. Press Ctrl+C to quit.
-For a connection without headers, you can skip the chooser and form:
-
-```sh
-boom --flightsql http://localhost:50051
-```
-
Once you save a connection, `boom` opens your saved connections instead. See
-[Using sql-bomb](workspace.md) for saving connections and browsing results, or
-[Flight SQL](flight-sql.md) for supported URLs and authentication.
+[Using sql-bomb](workspace.md) for saving connections and browsing results, or the
+[client reference](flight-sql.md) for supported URLs, authentication, and
+command-line shortcuts that skip the chooser and form.
## Build from source
diff --git a/docs/index.md b/docs/index.md
index ee7fe65..8594d7e 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,12 +1,13 @@
# sql-bomb
-sql-bomb is a terminal application for running SQL and streaming results into a
-table. You can inspect complete cell values and return to queries from your local
-history or starred library. The installed executable is named `boom`.
+sql-bomb is a database-agnostic terminal application for running SQL and streaming
+results into a table. You can inspect complete cell values, reopen saved
+connections, and return to queries from your local history or starred library.
+The installed executable is named `boom`.
-Flight SQL is currently the only supported connection type. It connects to
-servers that implement Arrow Flight SQL, a protocol for running SQL over gRPC.
-Direct PostgreSQL and MySQL connections are not implemented.
+A client connects sql-bomb to a database server, and every client shares the same
+editor, results table, saved connections, and query library. The
+[client reference](flight-sql.md) lists the available clients and their settings.
The terminal interface is built with
[Hypercmd](https://github.com/fusor-rs/hypercmd) and
diff --git a/scripts/site.mjs b/scripts/site.mjs
index 67da13c..2950b9e 100644
--- a/scripts/site.mjs
+++ b/scripts/site.mjs
@@ -111,7 +111,7 @@ async function checkDocs(page, origin) {
await page.getByRole("heading", { name: title, exact: true }).waitFor();
const bodySizes = await page.locator(".article .lead, .article .markdown").evaluateAll(nodes =>
[...new Set(nodes.map(node => getComputedStyle(node).fontSize))]);
- assert.deepEqual(bodySizes, ["16px"]);
+ assert.deepEqual(bodySizes, ["14px"]);
const response = await page.request.get(origin + "docs/content/" + filename);
assert.equal(response.status(), 200);
assert.equal(await response.text(), markdown);
From 5e610eb1d891962b0b93a9523f63b6b659390317 Mon Sep 17 00:00:00 2001
From: Andres Pirela <60560109+andreespirela@users.noreply.github.com>
Date: Sat, 3 Oct 2026 23:45:56 -0400
Subject: [PATCH 3/3] chore: fixes
---
.github/workflows/check.yml | 1 +
.github/workflows/deploy-site.yml | 1 +
2 files changed, 2 insertions(+)
diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml
index a4d7a04..7d21184 100644
--- a/.github/workflows/check.yml
+++ b/.github/workflows/check.yml
@@ -18,6 +18,7 @@ jobs:
- uses: Swatinem/rust-cache@v2
with:
workspaces: apps -> target
+ cache-targets: false
- uses: actions/setup-node@v4
with:
node-version: 22
diff --git a/.github/workflows/deploy-site.yml b/.github/workflows/deploy-site.yml
index bc0b260..8e3616e 100644
--- a/.github/workflows/deploy-site.yml
+++ b/.github/workflows/deploy-site.yml
@@ -39,6 +39,7 @@ jobs:
- uses: Swatinem/rust-cache@v2
with:
workspaces: apps -> target
+ cache-targets: false
- uses: actions/setup-node@v4
with:
node-version: 22