🗃️ DBCrab 🦀

DBCrab is a modern REPL-first PostgreSQL client.

Screenshots

REPL view:

TUI view:

Quick Start

Installation:

• Local: cargo install --path .

Start DBCrab with a PostgreSQL connection string:

dbcrab postgres://user@localhost/database

After connecting, DBCrab loads database metadata for completion and object inspection. Type SQL at the > prompt and end each statement with a semicolon.

select *
from users
limit 10;

Main Features

Smart SQL REPL

DBCrab is built for interactive database work:

• Write single-line or multi-line SQL statements.
• Run several complete statements from one input.
• Use syntax highlighting for keywords, strings, identifiers, comments, and numbers.
• Keep typing until the statement is complete, DBCrab waits for the final semicolon.
• See clearer PostgreSQL errors, including query positions and helpful hints when possible.

Autocomplete

DBCrab uses loaded database metadata to suggest useful completions:

• SQL keywords.
• Schema-aware completion: Schemas, tables, views, and other relations.
• Context-aware completion: Columns, including qualified column completion.
• Command names and command flags in command mode.

Use Tab or Ctrl-Space to open completion suggestions.

Command Mode

Press : on an empty SQL prompt to enter command mode. Commands do not need a semicolon.

Press Esc or Ctrl-D to return to the SQL prompt. With edit_mode = "vi", command mode uses Vi editing too, so Esc first leaves insert mode and a second Esc returns to the SQL prompt.

Common commands:

• help, show all commands.
• connection, show safe connection and session details.
• refresh, reload metadata used by autocomplete.
• schemas, list schemas.
• databases, list databases.
• roles, list roles.
• extensions, list installed extensions.
• tables, list tables, partitioned tables, and foreign tables.
• views, list views and materialized views.
• functions, list functions and procedures.
• types, list PostgreSQL data types.
• privileges, list explicit object privileges.
• describe users, inspect a database object.
• source active_users, show a function, procedure, or view definition.
• quit, exit DBCrab.

Most list commands accept a filter, for example tables user. Some commands can include system objects with the -x flag, for example tables pg_catalog -x. Use help describe or help source for command-specific examples.

Result Display

DBCrab shows small results directly in the terminal. For larger or wider results, it can open a full-screen table viewer.

In the table viewer:

• Move with arrow keys or h, j, k, l.
• Press Enter to preview the selected cell.
• Press Tab to switch focus between the table and preview.
• Press q, Esc, or Ctrl-C to close the viewer.

Press Alt-v in the SQL prompt to cycle result display modes:

• auto, let DBCrab choose inline output or the table viewer.
• full (TUI), prefer the table viewer for row results.
• inline, print results directly in the terminal.

Agent Mode

DBCrab can run without the interactive REPL for coding agents and scripts. The output is token and context efficient. Use -e for --execute and -: for --command; -c remains --context.

Suggested prompt for AGENTS.md or other coding-agent instructions:

For PostgreSQL work, prefer DBCrab over psql.
Run `dbcrab --agent-guide` before using it.

History And Contexts

DBCrab keeps a persistent SQL history when a state directory is available. By default, history is stored under your user state directory.

Use a named history context when you want separate histories for different projects or databases:

dbcrab postgres://user@localhost/app -c my_app

Configuration

DBCrab reads configuration from dbcrab/config.toml in your user configuration directory. Use --config PATH to load a specific file.

Print the default keybinding configuration with:

dbcrab --default-keybindings

Choose the prompt editing mode with:

edit_mode = "emacs" # or "vi"

Keybindings are merged with DBCrab and Reedline defaults. A plain assignment replaces an action's bindings, while .add, .remove, and .set patch the existing defaults.

[keybindings.remap]
# Remaps navigation/action input. Plain character swaps are skipped while typing.
j.swap = "n"
# Modified remaps still apply in typing modes.
ctrl-h.swap = "ctrl-i"

[keybindings.prompt]
complete.add = ["ctrl-y"]
complete.remove = ["ctrl-space"]
cycle_display = ["alt-v"]
command_mode = [":"]

[keybindings.prompt.insert]
ClearScreen = ["ctrl-l"]
HistoryMenu = ["ctrl-r"]

[keybindings.prompt.vi_normal]
# Reedline's built-in vi grammar still handles h/j/k/l, w, b, d, c, y, etc.

[keybindings.command]
complete = ["tab", "ctrl-space"]
cancel = ["esc", "ctrl-d"]

[keybindings.tui]
left = ["left", "h"]
up = ["up", "k"]
right = ["right", "l"]
down = ["down", "j"]
edit_preview = ["c"]
stage_preview = ["ctrl-s"]
set_null = ["ctrl-x"]
update_row = ["ctrl-u"]
quit.add = ["q"]

Prompt line-editor sections use Reedline action names such as ClearScreen, MoveToLineStart, BackspaceWord, Undo, and PasteCutBufferBefore. Plain character remaps also apply to shifted input in non-typing contexts, so j.swap = "n" maps j <-> n and J <-> N in TUI and Vi normal mode. While typing SQL in Emacs/Vi insert mode or entering meta-commands, unmodified and Shift-only characters are left unchanged. Modified keys such as ctrl-j are only remapped when listed explicitly and still apply in typing modes.