Textualite

A full-featured SQLite client for the terminal, built with Textual.

Features

Core Features

Open and view SQLite database files (.db, .sqlite, .sqlite3)
List all tables with properties (row counts, columns, indexes, foreign keys)
Interactive SQL query editor with syntax highlighting
Query results displayed in a paginated data table
Horizontal split view: query editor (top) and results (bottom)
Navigate database schema and relationships

Data Management

View all rows in a table with pagination
Configurable page sizes: 10, 25, 50, 100, 500, 1000 rows per page
Create, update, and delete tables
Execute SELECT, INSERT, UPDATE, DELETE queries
Transaction support for write operations

Advanced Features

Export query results to CSV and JSON formats
Schema visualization with table relationships
Foreign key and index information display
Query history tracking (planned)
Dark and light theme toggle with persistent preferences
Fully keyboard-navigable interface (no mouse required)
Panel navigation with Tab cycling and Alt+number shortcuts
Comprehensive keyboard shortcuts using Alt+letter combinations
File picker for easy database selection
Settings persistence in ~/.textualite/settings.json

Installation

Requirements

Python 3.10 or higher
pip

Install Dependencies

# Clone or navigate to the project directory
cd textualite

# Create and activate virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install the package in development mode
pip install -e .

Optional: SQL Syntax Highlighting

For SQL syntax highlighting in the query editor, install Textual with syntax support:

# Activate virtual environment if not already active
source venv/bin/activate

# Install syntax highlighting dependencies
pip install 'textual[syntax]'

This includes tree-sitter-sql and other language parsers for beautiful SQL syntax highlighting.

Usage

Quick Start

# Run with the included sample database
./run.sh tests/fixtures/sample.db

# Or run without arguments (opens file picker)
./run.sh

# Run with light theme
./run.sh --theme light tests/fixtures/sample.db

Alternative: Using PYTHONPATH

# Run with PYTHONPATH environment variable
PYTHONPATH=src python3 -m textualite tests/fixtures/sample.db

# Or without a database file
PYTHONPATH=src python3 -m textualite

After Installing with pip

# Install the package
pip install -e .

# Then run normally
textualite tests/fixtures/sample.db
textualite --theme light

Keyboard Shortcuts

Main Actions

Shortcut	Action
`Alt+O`	Open database file
`Alt+C`	Close database
`Alt+T`	Toggle dark/light theme
`Alt+E`	Export query results
`Alt+S`	Show schema visualization
`Alt+Q`	Quit application
`F1`	Show help screen
`Ctrl+Enter`	Execute SQL query
`Ctrl+P`	Open command palette
`Escape`	Cancel/Close dialog

Panel Navigation

Shortcut	Action
`Tab`	Cycle to next panel (Sidebar → Query → Results)
`Shift+Tab`	Cycle to previous panel
`Alt+1`	Jump to sidebar (table list)
`Alt+2`	Jump to query editor
`Alt+3`	Jump to results view

Note for macOS Users: The Alt key is the Option key on Mac. You must enable "Use Option as Meta key" in Terminal → Settings → Profiles → Keyboard for Alt shortcuts to work.

macOS Terminal Setup

To enable keyboard shortcuts on macOS Terminal:

Open Terminal application
Go to Terminal → Settings (or press Cmd+,)
Click on the Profiles tab
Select your active profile (usually "Basic" or "Default")
Click the Keyboard tab
Check the box: "Use Option as Meta key"
Close the Settings window
Restart your terminal for changes to take effect

Alternatively, use iTerm2 which has better keyboard handling by default.

User Interface

Main Screen Layout

┌─────────────────────────────────────────────────────────────┐
│ Header: Textualite v0.1.0 - database.db                    │
├──────────────┬──────────────────────────────────────────────┤
│              │ SQL Query Editor                             │
│  Table List  │ (Ctrl+Enter to execute)                     │
│              │                                              │
│  • authors   │ SELECT * FROM books                          │
│  • books     │ WHERE author_id = 1                         │
│  • reviews   │                                              │
│              ├──────────────────────────────────────────────┤
│              │ Results View                                 │
│              │                                              │
│              │ [DataTable with query results]              │
│              │                                              │
│              │ [First] [Prev] Page 1 of 5 [Next] [Last]   │
├──────────────┴──────────────────────────────────────────────┤
│ Footer: Keyboard shortcuts                                   │
└─────────────────────────────────────────────────────────────┘

Features Overview

1. Table List (Sidebar)

Displays all tables in the database
Shows row count for each table
Filter tables by name
Click to view table data
Expandable to show columns, foreign keys, and indexes

2. Query Editor

SQL syntax highlighting (with optional dependencies)
Multi-line editing
Execute queries with Ctrl+Enter
Load queries from history

3. Results View

Paginated data table
Column headers from query
NULL value highlighting
Navigation controls (First, Previous, Next, Last)
Page size selector
Row count display

4. Schema Viewer

Table structure display
Column types and constraints
Foreign key relationships
Index information
CREATE TABLE statements
Database-wide relationship diagram

5. Data Export

Export to CSV format
Export to JSON format
Suggested filenames based on query
Progress notifications

Project Structure

textualite/
├── src/textualite/
│   ├── __init__.py
│   ├── __main__.py          # Entry point
│   ├── app.py               # Main application class
│   ├── config.py            # Configuration constants
│   ├── settings.py          # User preferences persistence
│   ├── models/              # Data models
│   │   ├── database.py      # Table, Column, ForeignKey models
│   │   └── query_history.py # Query history model
│   ├── database/            # Database logic layer
│   │   ├── connection.py    # SQLite connection management
│   │   ├── schema.py        # Schema inspection
│   │   ├── query_executor.py # Query execution with pagination
│   │   └── exporter.py      # CSV/JSON export
│   ├── widgets/             # Custom Textual widgets
│   │   ├── table_list.py    # Table list sidebar
│   │   ├── query_editor.py  # SQL query editor
│   │   ├── results_view.py  # Results display with pagination
│   │   ├── schema_viewer.py # Schema visualization
│   │   ├── file_picker.py   # Database file picker
│   │   └── dialogs.py       # Modal dialogs
│   ├── screens/             # Application screens
│   │   ├── main_screen.py   # Main 3-panel layout
│   │   ├── table_screen.py  # Table data viewing
│   │   └── schema_screen.py # Schema visualization screen
│   └── themes/
│       └── custom.tcss      # Custom CSS styling
├── tests/
│   └── fixtures/
│       └── sample.db        # Sample database for testing
├── pyproject.toml           # Project configuration
├── requirements.txt         # Dependencies
└── README.md               # This file

Development

Running Tests

pip install -e ".[dev]"
pytest

Development Mode

For live reloading during development:

textual run --dev src/textualite/__main__.py

Code Style

The project follows PEP 8 guidelines with type hints throughout.

Technical Details

Database Operations

Uses Python's built-in sqlite3 module
Single connection per database with automatic cleanup
LIMIT/OFFSET pagination for query results
Foreign key constraints enabled
Transaction support for write operations

Architecture

Reactive attributes for state management
Message passing for component communication
Modular widget design with focus management
Panel navigation system with Tab cycling and direct shortcuts
Textual's built-in DataTable and TextArea widgets
Context manager pattern for database connections
Settings persistence with reactive theme watching
Alt+letter keyboard shortcuts (macOS Terminal compatible)

Performance Considerations

Lazy loading of table metadata
Paginated queries to limit memory usage
Maximum display limit of 10,000 rows
Efficient schema caching

Limitations

Read-only mode for BLOB data (displays byte count)
Limited to single database connection at a time
No visual query builder (SQL knowledge required)
Pagination uses LIMIT/OFFSET (not optimal for very large tables)

Future Enhancements

Multi-tab support for multiple databases
Query autocomplete and suggestions
Visual query builder
Full CRUD operations in table view
Import data from CSV/JSON
Database comparison tools
Backup and restore functionality
Plugin system for extensions

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

Built with Textual by Textualize
Uses textual-fspicker for file picking
Inspired by various database clients

Support

For issues, questions, or suggestions, please open an issue on the GitHub repository.

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
src/textualite		src/textualite
tests		tests
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
README.md		README.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
run.sh		run.sh

skyeroad/textualite

Folders and files

Latest commit

History

Repository files navigation