LazyDatabricks 🧱

A keyboard-first TUI for Databricks — lazygit for your data platform.

Status → Logs → Action in seconds, not clicks.

Design Principles

• Read-first, act-second. Default is safe visibility; destructive actions require explicit arming.
• Spark-true, not API-true. "Is my cluster usable?" matters more than "does the API say RUNNING?"
• Logs are the primary artifact. One keystroke, not seven clicks.

Quick Start

# Install
pip install lazydatabricks

# Or from source
pip install -e ".[dev]"

# Configure (uses same env vars / .databrickscfg as Databricks SDK)
export DATABRICKS_HOST=https://adb-xxx.azuredatabricks.net
export DATABRICKS_TOKEN=dapi...

# Launch TUI (default)
lazydatabricks

# Or use specific profile
lazydatabricks --profile staging

# CLI mode (non-interactive)
lazydatabricks health      # Health snapshot
lazydatabricks clusters    # List clusters
lazydatabricks jobs        # List jobs
lazydatabricks test        # Test connection

TUI Overview

LazyDatabricks provides a keyboard-driven interface with five main screens:

• Home (h) — Health dashboard showing workspace identity, Spark connectivity, cluster/job/warehouse summaries
• Clusters (c) — List and manage compute clusters with start/terminate/restart actions
• Jobs (j) — Three-pane hierarchy: Jobs → Runs → Detail with run now/cancel/rerun actions
• Warehouses (w) — SQL warehouse management with start/stop actions
• Config — Profile switching and connection testing

Safety Model: Armed Mode

LazyDatabricks defaults to READ-ONLY mode. All destructive actions require explicitly arming:

1. Press A to arm (30-second timer starts)
2. Header shows red "ARMED (Xs)" countdown
3. Execute destructive action (e.g., t to terminate cluster)
4. System auto-disarms after 30 seconds

Destructive actions include:

• Cluster: start, terminate, restart
• Job: run now, cancel, rerun
• Warehouse: start, stop

Keybindings

Global Navigation

Home Screen

Clusters Screen

Jobs Screen

Logs Screen

Warehouses Screen

Config Screen

Architecture

src/lazydatabricks/
├── models/       # Data models — stable internal structs
│   ├── cluster.py    # ClusterSummary, ClusterState, ClusterFlag
│   ├── job.py        # JobSummary, RunSummary, RunDetail
│   ├── warehouse.py  # WarehouseSummary, WarehouseState
│   ├── health.py     # HealthSnapshot, SparkStatus
│   └── config.py     # LazyDatabricksConfig, DatabricksProfile
├── api/          # API client layer
│   ├── client.py     # DatabricksClient (SDK wrapper)
│   ├── clusters.py   # ClusterOps
│   ├── jobs.py       # JobOps
│   ├── warehouses.py # WarehouseOps
│   ├── health.py     # HealthBuilder
│   ├── logs.py       # LogOps
│   └── guard.py      # ArmedGuard (safety model)
└── tui/          # Textual TUI
    ├── app.py        # LazyDatabricksApp main class
    ├── theme.py      # Colors and CSS
    ├── screens/      # Screen implementations
    │   ├── home.py
    │   ├── clusters.py
    │   ├── jobs.py
    │   ├── logs.py
    │   ├── warehouses.py
    │   └── config.py
    └── widgets/      # Reusable widgets
        ├── header.py
        ├── status_bar.py
        ├── help_overlay.py
        └── confirm_dialog.py

Configuration

LazyDatabricks uses the same configuration as the Databricks SDK:

1. Environment variables (highest priority)

   export DATABRICKS_HOST=https://adb-xxx.azuredatabricks.net
   export DATABRICKS_TOKEN=dapi...
   export DATABRICKS_CLUSTER_ID=0123-456789-abcdef  # optional
   

2. ~/.databrickscfg profiles

   [DEFAULT]
   host = https://adb-xxx.azuredatabricks.net
   token = dapi...
   cluster_id = 0123-456789-abcdef
   
   [staging]
   host = https://adb-yyy.azuredatabricks.net
   token = dapi...
   

3. CLI flags

   lazydatabricks --host https://... --token dapi... --cluster-id 0123...
   lazydatabricks --profile staging
   

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Type checking
mypy src/lazydatabricks

# Linting
ruff check src/lazydatabricks

Requirements

• Python 3.10+
• Databricks workspace with API access

License

MIT