tuible 0.0.2-alpha.1

A keyboard-driven database client for your terminal, built for both humans and AI agents.
tuible-0.0.2-alpha.1 is not a library.

tuible

TUI + table. A keyboard-driven database client for your terminal — built to be fast to navigate by hand, and scriptable/scoped enough for AI agents to perform specific database actions without full access.

Alpha: v0.0.2-alpha.1 is an early source release. Interfaces and config may change before the first stable release.

Install

Install the alpha from crates.io:

cargo install tuible --version 0.0.2-alpha.1
tuible

Prebuilt binaries are not provided for this alpha. The release is verified on Apple Silicon macOS; other Rust-supported platforms may work but are not yet part of the release gate.

To run a development checkout instead:

cargo run --release

Both commands open the connection manager. You can create named SQLite or DynamoDB profiles, or open the bundled demo without configuring a connection. Profiles store database paths and AWS profile/region selectors, never credentials.

Use tuible demo to open the sample directly, or tuible profile NAME to open a saved connection. In a development checkout, prefix those commands with cargo run --, for example cargo run -- demo.

TUI workflow

The panels are numbered lazygit-style: [1] Tables, [2] Filters | SQL, [3] Data, [4] Record. Pane 2 opens on persistent filter rows with column, operator, value, apply, remove, and add controls; switch to its SQL tab for ad-hoc queries. Press ? inside the app for the full keybinding popup. The mouse works too: click to focus a panel or pick a table/cell, scroll to move.

Keys: 1/2/3/4 focus a panel, Tab changes panels, [/] changes tabs inside Pane 2, Data, or Record, f focuses Filters, and E toggles Pane 2. In the SQL editor, completion appears while typing; use arrows to pick a suggestion and Tab to accept it. y copies quickly and Y opens the CSV/TSV/JSON copy dialog. Press Ctrl-r to search successful read-query history. On Data rows, o cycles the selected column through ascending, descending, and unsorted order for the currently loaded result or page.

Database operations run in the background so the interface remains responsive. The status bar shows elapsed time. Esc cancels a replaceable read operation; writes are never silently superseded. A canceled or timed-out remote write can have an indeterminate outcome, and tuible reports that explicitly rather than retrying it automatically.

Configuration

Configuration follows the XDG base-directory convention:

$XDG_CONFIG_HOME/tuible/config.toml
# fallback: $HOME/.config/tuible/config.toml

Generated application data, including the demo database, uses $XDG_DATA_HOME/tuible with a $HOME/.local/share/tuible fallback. Query history is state, stored under $XDG_STATE_HOME/tuible with a $HOME/.local/state/tuible fallback. Set query_history_enabled = false to disable recording. Only successful interactive read queries are recorded.

Run tuible config to print the path or tuible config --show to print the effective TOML. The file contains display preferences, validated shortcut bindings, and connection profiles. Missing settings inherit current defaults, so existing files remain usable when new options are added. Foreground database operations time out after 30 seconds by default; adjust foreground_timeout_ms when a slower environment requires it.

Safety

  • SQLite and DynamoDB connections are read-only unless write access is explicit.
  • CLI writes require both the write-capable command and confirmation.
  • Query output and TUI result sets are bounded.
  • AWS credentials are resolved by the AWS SDK and are never stored in profiles.
  • Canceled DynamoDB writes are reported as potentially indeterminate.

DynamoDB Local demo

Docker and Cargo are enough to try the DynamoDB integration without an AWS account. Start the in-memory service and seed a deterministic table:

docker compose -f compose.dynamodb.yml up -d
cargo run --example seed_dynamodb_local

The seeder recreates tuible-demo and writes 250 customer and order records with a composite key, sparse attributes, nested maps/lists, booleans, and exact DynamoDB numbers. Open it in the TUI with:

cargo run -- dynamodb open --local

The same data can exercise the machine-readable commands:

cargo run -- dynamodb tables --local
cargo run -- dynamodb describe tuible-demo --local
cargo run -- dynamodb query tuible-demo \
  --key-condition 'pk = :pk' \
  --values '{":pk":"CUSTOMER#001"}' \
  --local

To keep a launcher entry in the connection manager, add this profile through the UI or to the profiles list in the config file:

[[profiles]]
kind = "dynamodb"
name = "local-demo"
local = true
write = false

Then use cargo run -- profile local-demo. Stop the in-memory service when finished; its test data is intentionally discarded:

docker compose -f compose.dynamodb.yml down

If mise is installed, the same workflow is available through mise run dynamodb-up, mise run dynamodb-seed, mise run dynamodb-smoke, and mise run dynamodb-down. Run mise run check for the local formatting, lint, and test gate.

License

tuible is available under either the MIT license or the Apache License 2.0, at your option.