{"id":34751081,"url":"https://github.com/sheenazien8/sq","last_synced_at":"2026-02-24T03:10:49.072Z","repository":{"id":330049311,"uuid":"1117963653","full_name":"sheenazien8/sq","owner":"sheenazien8","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-24T04:29:40.000Z","size":30014,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-12-24T13:45:33.491Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sheenazien8.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-17T04:23:21.000Z","updated_at":"2025-12-24T04:29:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sheenazien8/sq","commit_stats":null,"previous_names":["sheenazien8/sq"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/sheenazien8/sq","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sheenazien8%2Fsq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sheenazien8%2Fsq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sheenazien8%2Fsq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sheenazien8%2Fsq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sheenazien8","download_url":"https://codeload.github.com/sheenazien8/sq/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sheenazien8%2Fsq/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28020297,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-25T02:00:05.988Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-25T05:16:30.785Z","updated_at":"2026-02-24T03:10:49.058Z","avatar_url":"https://github.com/sheenazien8.png","language":"Go","funding_links":[],"categories":["Table of Contents","Applications"],"sub_categories":["Development Tools"],"readme":"# sq\n\nA keyboard-first SQL TUI built for VIM users [Bubble Tea](https://github.com/charmbracelet/bubbletea) TUI framework for Go.\nIt focuses on speed, clarity, and terminal-native workflows—no mouse,\nno clutter, just efficient querying inside terminal but with the beautifull UI\n\n**Status**: Active development - MySQL, PostgreSQL, and SQLite support available with full CRUD operations, foreign key navigation, pagination, and SQL query editor.\n\n## Demo\n\n![Demo](https://vhs.charm.sh/vhs-md530GUinDz9OJHRgSSgq.gif)\n\n## Installation\n\n### Prerequisites\n- Go 1.22 or later\n\n### Install\n```bash\ngo install github.com/sheenazien8/sq@latest\n```\n\n### From source\n```bash\ngo mod download\ngo mod tidy\ngo build -o sq\n./sq\n```\n\n### Running\n```bash\ngo run .\n```\n\n### Command Line Options\n```bash\nsq --help                    # Show help\nsq --version                 # Show version\nsq --create-connection       # Create a new database connection\n```\n\n## Features\n\n### Current Features\n\n**Database Support:**\n- MySQL database connections with full feature support\n- PostgreSQL database connections with full feature support\n- SQLite database file connections with full feature support\n- Multiple simultaneous connections in sidebar\n- Persistent connection storage\n\n**Data Browsing:**\n- Table listing with automatic refresh\n- Data viewing with pagination (100 rows per page by default)\n- Efficient handling of large datasets\n- Cell-level data preview with `p` key\n- Copy cell data to clipboard with `y` key\n\n**Advanced Features:**\n- **Query Editor** with vim-mode support for writing and executing custom SQL queries\n  - SQL syntax highlighting (Chroma v2)\n  - SQL formatting with `Ctrl+F` (sqlfmt integration)\n  - Multi-line query support\n  - Query execution with F5 or Ctrl+E\n- **Table Structure Viewer** - View columns, indexes, relations, and triggers\n  - Column information (type, nullable, default values)\n  - Index information (unique, primary, type)\n  - Foreign key relationships\n  - Triggers and their definitions\n\n**Navigation \u0026 Filtering:**\n- **Foreign Key Navigation** - Jump to related tables with `gd` (goto definition)\n- **Advanced Filtering** - Multi-condition filter dialog with column/operator/value selection\n- Vim-like keyboard navigation (hjkl movement, gg/G jump, w/b word movement)\n- Tabbed interface for multiple tables/queries\n- Collapsible sidebar to maximize table view space\n\n**UI \u0026 Theming:**\n- 7 built-in themes (default, dracula, nord, gruvbox, tokyo-night, catppuccin, monokai)\n- Real-time theme switching with `T` key\n- Multi-pane layout with sidebar, table view, and filter dialog\n- Built-in help modal accessible with `?` key\n- Responsive design that adapts to terminal size\n\n### Planned Features\n- SQLite support\n- Detail pane for selected records\n- Edit/insert/delete operations\n- Query history\n\n## Usage\n\n### Global Shortcuts\n| Key | Action |\n|-----|--------|\n| `?` | Show help modal |\n| `q` / `Ctrl+C` | Show exit modal |\n| `Tab` | Switch focus between sidebar and main area |\n| `T` | Cycle themes |\n| `s` / `S` | Toggle sidebar visibility |\n\n### Sidebar Navigation (when focused)\n| Key | Action |\n|-----|--------|\n| `j` / `↓` | Move down |\n| `k` / `↑` | Move up |\n| `Home` | Jump to first item |\n| `End` | Jump to last item |\n| `Enter` | Select/connect to database or open table |\n| `e` | Open Query Editor (requires active connection) |\n| `d` | View table structure |\n| `n` | Create new connection |\n\n### Tab Management\n| Key | Action |\n|-----|--------|\n| `]` | Next tab |\n| `[` | Previous tab |\n| `Ctrl+W` | Close current tab |\n\n### Table Navigation (when focused)\n| Key | Action |\n|-----|--------|\n| `j` / `↓` | Move down one row |\n| `k` / `↑` | Move up one row |\n| `h` / `←` | Scroll columns left |\n| `l` / `→` | Scroll columns right |\n| `H` | Jump to first column |\n| `L` | Jump to last column |\n| `J` | Next page (pagination) |\n| `K` | Previous page (pagination) |\n| `PgUp` / `PgDn` | Page up/down |\n| `Home` / `End` | Jump to first/last row |\n| `y` | Yank (copy) selected cell content to clipboard |\n| `p` | Preview selected cell content |\n| `/` / `f` | Open filter dialog |\n| `C` | Clear all filters |\n| `d` | View table structure |\n| `e` | Open Query Editor |\n| `gd` | Go to definition (navigate to foreign key table) |\n\n### Table Structure View\n| Key | Action |\n|-----|--------|\n| `1` | View Columns |\n| `2` | View Indexes |\n| `3` | View Relations |\n| `4` | View Triggers |\n| `Tab` | Next section |\n| `Shift+Tab` | Previous section |\n\n### Query Editor\nThe query editor features full **vim-mode** support for efficient editing.\n\n#### Vim Modes\n| Mode | Description |\n|------|-------------|\n| `NORMAL` | Navigation and commands (default) |\n| `INSERT` | Text editing mode |\n\n#### Normal Mode Commands\n| Key | Action |\n|-----|--------|\n| `i` | Enter insert mode at cursor |\n| `a` | Enter insert mode after cursor |\n| `I` | Enter insert mode at beginning of line |\n| `A` | Enter insert mode at end of line |\n| `o` | Open new line below and enter insert mode |\n| `O` | Open new line above and enter insert mode |\n| `h` / `←` | Move cursor left |\n| `j` / `↓` | Move cursor down |\n| `k` / `↑` | Move cursor up |\n| `l` / `→` | Move cursor right |\n| `0` | Move to beginning of line |\n| `$` | Move to end of line |\n| `w` | Move to next word |\n| `b` | Move to previous word |\n| `g` | Go to beginning of document |\n| `G` | Go to end of document |\n| `x` | Delete character under cursor |\n| `X` | Delete character before cursor |\n| `u` | Undo |\n\n#### Insert Mode\n| Key | Action |\n|-----|--------|\n| `Esc` | Return to normal mode |\n| Any key | Type text |\n\n#### Query Execution\n| Key | Action |\n|-----|--------|\n| `F5` / `Ctrl+E` | Execute query |\n| `Ctrl+R` | Toggle focus between editor and results |\n| `Ctrl+F` | Format SQL query |\n| `Ctrl+Y` | Copy entire query to clipboard |\n\n#### Results Table (when focused)\n| Key | Action |\n|-----|--------|\n| `h/j/k/l` | Navigate cells |\n| `p` | Preview selected cell content |\n| `y` | Yank (copy) selected cell to clipboard |\n| `i` / `a` | Return to editor in insert mode |\n| `Ctrl+R` | Return to editor |\n\n### Filter Dialog (when open)\n| Key | Action |\n|-----|--------|\n| `Tab` / `→` / `l` | Next field |\n| `Shift+Tab` / `←` / `h` | Previous field |\n| `j` / `↓` | Next option (column/operator) |\n| `k` / `↑` | Previous option (column/operator) |\n| `Enter` | Apply filter and close |\n| `Esc` | Close without applying |\n| `Ctrl+C` | Clear filter |\n\n### Modal (when visible)\n| Key | Action |\n|-----|--------|\n| `←` / `→` / `h` / `l` / `Tab` | Switch button |\n| `Enter` | Confirm selection |\n| `y` / `Y` | Yes |\n| `n` / `N` / `Esc` | No |\n\n## Project Structure\n\n```\nsq/\n├── main.go              # Entry point, initializes Bubble Tea program\n├── app/                 # Main application logic (Bubble Tea Model-View-Update)\n│   ├── init.go          # Init() - initialization command\n│   ├── model.go         # Model struct and constructor\n│   ├── update.go        # Update() - handles messages and input\n│   └── view.go          # View() - renders the UI\n├── config/              # Application configuration\n│   └── config.go        # Config loading/saving (~/.config/sq/config.json)\n├── drivers/             # Database drivers\n│   ├── driver.go        # Driver interface definition\n│   ├── mysql.go         # MySQL driver implementation (with pagination support)\n│   ├── postgres.go      # PostgreSQL driver implementation (with pagination support)\n│   └── types.go         # Shared types (TableStructure, ColumnInfo, Pagination, etc.)\n├── logger/              # Logging utilities\n├── storage/             # Connection storage utilities\n├── ui/                  # UI components (separate Bubble Tea models)\n│   ├── sidebar/         # Connection and table list sidebar\n│   ├── table/           # Scrollable table widget\n│   ├── tab/             # Tabbed interface for multiple views\n│   ├── filter/          # Filter input component\n│   ├── query-editor/    # SQL query editor with vim-mode and formatter\n│   ├── syntax-editor/   # Syntax highlighting text editor component\n│   ├── modal/           # Base modal component\n│   ├── modal-exit/      # Exit confirmation modal\n│   ├── modal-cell-preview/  # Cell content preview modal\n│   ├── modal-create-connection/  # New connection modal\n│   ├── modal-help/      # Help modal with all keybindings\n│   ├── theme/           # Theme system and color definitions\n│   ├── main/            # (future) Main record view\n│   └── detail/          # (future) Detail pane\n└── demo/                # Demo files\n    └── demo.mov         # Demonstration video\n```\n\n## Architecture\n\nThe app follows Bubble Tea's Model-View-Update (MVU) architecture:\n\n- **Model**: Application state with sub-models for each UI component\n- **Update**: Event handling, routing messages to focused components\n- **View**: Rendering, composing sub-component views using Lipgloss\n- **Init**: Initial commands (currently nil)\n\nEach UI component (sidebar, table, filter, modal) follows the same pattern with own Model, Update(), and View() methods.\n\n## Configuration\n\nConfiguration is saved to `~/.config/sq/config.json`:\n\n```json\n{\n  \"theme\": \"default\"\n}\n```\n\nAvailable themes: default, dracula, nord, gruvbox, tokyo-night, catppuccin, monokai.\n\n## Database Connections\n\nConnections are stored in `~/.config/sq/storage.db`.\n\n### Quick Start - Creating Your First Connection\n\n1. Launch the application:\n   ```bash\n   ./sq\n   ```\n\n2. Press `n` to create a new connection\n\n3. Select your database driver (MySQL or PostgreSQL)\n\n4. Enter your connection details:\n   - **Name**: A descriptive name for this connection (e.g., \"Production DB\")\n   - **Host**: Database server address (default: localhost)\n   - **Port**: Database port (MySQL: 3306, PostgreSQL: 5432)\n   - **Username**: Database user (MySQL: root, PostgreSQL: postgres)\n   - **Password**: User password\n   - **Database**: Database name to connect to\n\n5. Press `Enter` to test the connection and save it\n\n6. Once saved, your connection appears in the sidebar and can be selected with `Enter`\n\n### Supported Databases\n- **MySQL** - Full support including:\n  - Table browsing and data viewing with pagination\n  - Table structure (columns, indexes, relations, triggers)\n  - Foreign key navigation (goto definition)\n  - Custom SQL query execution with syntax highlighting and formatting\n  - Filtering with multiple conditions\n  - Connection persistence\n\n- **PostgreSQL** - Full support including:\n  - Table browsing and data viewing with pagination\n  - Table structure (columns, indexes, relations, triggers)\n  - Foreign key navigation (goto definition)\n  - Custom SQL query execution with syntax highlighting and formatting\n  - Filtering with multiple conditions\n  - Connection persistence\n\n### Connection URL Format\n\n**MySQL:**\n```\nmysql://user:password@tcp(host:port)/database\n```\n\nExample:\n```\nmysql://root:password@tcp(localhost:3306)/mydb\n```\n\n**PostgreSQL:**\n```\npostgres://user:password@host:port/database?sslmode=disable\n```\n\nExample:\n```\npostgres://postgres:password@localhost:5432/mydb?sslmode=disable\n```\n\n#### PostgreSQL Schema Support\n\nsq automatically detects and uses the appropriate schema:\n\n1. **Priority Order**:\n   - First, checks if the `public` schema exists and uses it\n   - If `public` doesn't exist, uses the first user-created schema found\n   - Falls back to `public` if detection fails\n\n2. **Schema Detection**:\n   - Automatically excludes PostgreSQL system schemas (`pg_catalog`, `information_schema`, `pg_toast`)\n   - Selects the first user-accessible schema alphabetically\n   - Detection happens automatically on connection\n\n3. **Current Limitations**:\n   - Only one schema is supported per connection\n   - Tables from multiple schemas cannot be viewed simultaneously\n   - To work with tables in different schemas, create separate connections for each schema\n\nIf you need to work with a specific non-public schema, the schema is automatically detected on connection. If detection doesn't find your schema, ensure:\n- The schema exists in the database\n- Your user has permissions to access it\n- The schema is not a PostgreSQL system schema\n\n## Troubleshooting\n\n### Connection Issues\n\n**Error: \"invalid database scheme\"**\n- Make sure you're using the correct URI format for your database type\n- MySQL: `mysql://user:password@host:port/database`\n- PostgreSQL: `postgres://user:password@host:port/database?sslmode=disable`\n\n**PostgreSQL: \"relation not found\"**\n- Check that your tables exist in the detected schema (see logs for which schema was selected)\n- Verify the table names match exactly (PostgreSQL is case-sensitive for unquoted identifiers)\n- If using a non-public schema, ensure:\n  - The schema exists in your database\n  - Your user has SELECT permissions on the schema\n  - The schema is not a PostgreSQL system schema (`pg_catalog`, `information_schema`, `pg_toast`)\n- Check `debug.log` to see which schema was automatically detected\n\n**Connection refused**\n- Check that the database server is running and accessible\n- Verify host and port are correct\n- Check firewall rules if connecting to remote servers\n- Ensure username and password are correct\n\n### Debugging\n\nDebug logs are written to `debug.log` in the current directory. This can be helpful for troubleshooting connection issues or unexpected behavior.\n\nTo enable detailed logging:\n1. Check the `debug.log` file in your current directory after launching sq\n2. Look for error messages related to your specific operation\n3. Common issues like schema problems, query errors, and connection failures are logged here\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run tests (when implemented)\n5. Submit a pull request\n\n## License\n\nThis project is open source. See LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsheenazien8%2Fsq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsheenazien8%2Fsq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsheenazien8%2Fsq/lists"}