SQL TUI Explorer

A Terminal User Interface for exploring PostgreSQL databases via SQL API.

Features

• Load connections from config.yaml
• Support for Basic, Bearer, and Custom Header authentication
• Database Browsing: List Schemas, Tables, and View Data
• Table Metadata: View Columns, Indexes, Keys, and generated DDL
• Data Exploration:
  • Pagination (Next/Previous pages)
  • Filtering (WHERE clause input)
  • Sorting (ORDER BY clause input)
  • Row limits adjustment
  • Horizontal column scrolling
  • Detailed row view
• Custom SQL: Execute arbitrary SQL queries with Ctrl+E
• Themes: Built-in support for "Rose Pine Dawn" and "Rose Pine Moon"
• Export: Interactive HTML table export with browser auto-open

Configuration

Create a config.yaml file in the same directory as the executable. The file format is a map where keys are host names:

local_db:
  host: "http://localhost:8080"
  auth_type: "none"

prod_db:
  host: "https://api.example.com"
  auth_type: "bearer_token"
  token_value: "your-token-here"

dev_db:
  host: "https://dev.example.com"
  auth_type: "basic_auth"
  username: "user"
  password: "password"

staging_db:
  host: "https://staging.example.com"
  auth_type: "custom_header"
  header: "X-API-Key"
  header_value: "your-api-key"

Backend Requirements

To use this TUI, your backend must implement the following API endpoints:

Endpoints

• POST /api/v1/dev/query-sql: For SELECT queries.
• POST /api/v1/dev/execute-sql: For INSERT, UPDATE, DELETE, and other DDL/DML queries.

Request Format

{
  "sql": "SELECT * FROM users"
}

Success Response Format

{
  "rows": 10,  // Number of rows affected or returned
  "data": [   // Array of objects representing rows
    {
      "id": 1,
      "username": "admin",
      "email": "admin@example.com"
    },
    ...
  ]
}

Note: The TUI attempts to preserve column order by manually parsing the keys from the first object in the JSON data array. For consistent results, it is recommended that the backend returns JSON keys in the desired display order.

Error Response Format

{
  "message": "Short error description",
  "error": "Detailed database error message"
}

Installation

cd sql-tui
go mod tidy
go build

Usage

Run the application:

./sql-tui [-c path/to/config.yaml]

Global Controls

• ctrl+t: Open Theme selection
• ctrl+c: Quit application

List Views (Hosts, Schemas, Tables)

• enter: Select / Connect
• i: View Table Info (when a table is selected)
• ctrl+e: Enter Custom SQL mode
• esc / backspace: Go back

Data Explorer (Table View / Query Results)

• enter: View row details
• n / p: Next / Previous page
• f / /: Enter Filter (WHERE clause)
• s: Enter Sort (ORDER BY clause)
• l: Set row Limit
• h: Export current view to HTML
• left / right: Scroll columns horizontally
• esc: Go back / Cancel input

SQL Mode

• ctrl+e: Execute query
• esc: Cancel and return to previous state

Table Info View

• tab / shift+tab: Switch between Columns, Indexes, Keys, and DDL tabs
• esc: Close info view