trinops 0.1.0

Trino query monitoring: CLI, TUI dashboard, and progress library

trinops

Trino query monitoring from the terminal. CLI commands for listing and inspecting queries, a live TUI dashboard, and a progress-tracking library for use in Python scripts.

Installation

pip install trinops

The default install includes the CLI and TUI dashboard. For tqdm progress bars in library usage:

pip install trinops[tqdm]

Quick Start

Configure your Trino connection:

trinops config init

Or pass the server directly:

trinops queries --server trino.example.com:443

Or set environment variables:

export TRINOPS_SERVER=trino.example.com:443
export TRINOPS_USER=myuser
export TRINOPS_AUTH=basic

CLI Usage

List queries

# Your recent queries
trinops queries

# All users' queries
trinops queries --query-user all

# Filter by state
trinops queries --state RUNNING

# JSON output (pipe to jq, etc.)
trinops queries --json

# Select specific fields
trinops queries --select query_id,state,user,elapsed_time

Inspect a single query

# Rich formatted detail
trinops query <query-id>

# Full REST API response as JSON
trinops query <query-id> --json

# Select specific fields from the raw response
trinops query <query-id> --select queryId,state,queryStats.elapsedTime,queryStats.peakUserMemoryReservation

TUI dashboard

trinops tui
trinops top  # alias

The dashboard shows a live-updating table of queries with sorting, detail pane, and configurable refresh interval. Keybindings: r refresh, u toggle user filter, a show all, -/+ adjust refresh rate, q quit.

Configuration

Config file lives at ~/.config/trinops/config.toml:

[default]
server = "trino.example.com:443"
scheme = "https"
user = "myuser"
auth = "none"
query_limit = 50

[profiles.prod]
server = "trino-prod.example.com:443"
auth = "oauth2"

Authentication

Supported methods: none, basic, jwt, oauth2, kerberos.

# Check auth status
trinops auth status

# Run OAuth2 flow
trinops auth login

For basic auth, trinops uses the system keyring to store passwords securely.

Library Usage

Wrap a trino cursor or connection to get live progress display during query execution:

import trino
from trinops import TrinoProgress

conn = trino.dbapi.connect(host="trino.example.com", port=443, user="myuser")
cursor = conn.cursor()

with TrinoProgress(cursor) as tp:
    tp.execute("SELECT * FROM catalog.schema.table")
    rows = tp.fetchall()

You can also monitor an already-running query by passing a connection and query ID:

with TrinoProgress(conn, query_id="20260310_143549_08022_abc") as tp:
    tp.start()
    tp.wait()

Requirements

• Python 3.10+
• A running Trino cluster with the REST API accessible

License

PolyForm Shield 1.0.0