{"id":28146192,"url":"https://github.com/open-technology-foundation/dbh","last_synced_at":"2025-05-14T23:12:17.801Z","repository":{"id":288236420,"uuid":"967258346","full_name":"Open-Technology-Foundation/dbh","owner":"Open-Technology-Foundation","description":null,"archived":false,"fork":false,"pushed_at":"2025-05-14T04:39:23.000Z","size":129,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-14T06:06:59.573Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Open-Technology-Foundation.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2025-04-16T07:13:17.000Z","updated_at":"2025-05-14T04:39:26.000Z","dependencies_parsed_at":"2025-04-16T11:37:15.385Z","dependency_job_id":null,"html_url":"https://github.com/Open-Technology-Foundation/dbh","commit_stats":null,"previous_names":["open-technology-foundation/dbh"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fdbh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fdbh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fdbh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fdbh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Open-Technology-Foundation","download_url":"https://codeload.github.com/Open-Technology-Foundation/dbh/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254243332,"owners_count":22038046,"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","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-05-14T23:12:15.719Z","updated_at":"2025-05-14T23:12:17.793Z","avatar_url":"https://github.com/Open-Technology-Foundation.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dbh - Interactive MySQL Database Helper\n\nA powerful, intuitive MySQL database explorer with an interactive command interface, colorized output, and comprehensive database management capabilities.\n\n![Version](https://img.shields.io/badge/Version-3.7.1-blue)\n![License](https://img.shields.io/badge/License-GPL--3.0-green)\n![Bash](https://img.shields.io/badge/Language-Bash-yellow)\n\n## Overview\n\n`dbh` (version 3.7.1) is a MySQL database helper utility designed to streamline database interaction through a hierarchical command interface. It combines the power of the MySQL command-line client with an intuitive, context-aware interface that maintains your working environment as you navigate between databases and tables.\n\n### Why Use dbh?\n\n- **Reduce Repetitive Typing** - No need to retype database and table names\n- **Faster Exploration** - Navigate databases and tables with intuitive slash commands\n- **Interactive Query Building** - Build complex queries step-by-step without typing full SQL\n- **Avoid SQL Syntax Errors** - Commands help construct properly formatted queries\n- **Maintain Context** - Keep your database and table selection across operations\n- **Enhanced Security** - Built-in protections against SQL injection\n- **Seamless Shell Integration** - Run system commands without losing database context\n\n### Key Features\n\n- **Interactive Navigation** - Navigate databases and tables through menu-driven interfaces\n- **Context Awareness** - Maintains your selection context as you move between operations\n- **Color-Coded Interface** - Differentiated colors for prompts, messages, and errors\n- **Query Building** - Construct SELECT queries interactively with intuitive commands\n- **Direct SQL** - Execute SQL statements directly without prefixes\n- **Shell Integration** - Execute shell commands while maintaining database context\n- **Command History** - Persistent history across sessions with arrow key navigation\n- **Security-Focused** - Prevents SQL injection with proper parameter escaping\n- **Export Capabilities** - Export query results in CSV, JSON, or SQL formats\n- **Table Analysis** - Examine schema, indexes, foreign keys and relationships\n\n## Installation\n\n### Prerequisites\n\n- Bash 5.0+ (4.0+ will work with reduced functionality)\n- MySQL client (`mysql` command in PATH)\n- MySQL server (local or remote)\n- `less` pager (optional, for improved viewing of wide results)\n\n### Setup\n\n1. **Download the script:**\n   ```bash\n   curl -o dbh https://raw.githubusercontent.com/Open-Technology-Foundation/dbh/main/dbh\n   chmod +x dbh\n   ```\n\n2. **Create a MySQL config file** (default: `~/.mylocalhost.cnf`):\n   ```ini\n   [client]\n   host=localhost\n   user=your_username\n   password=your_password\n   ```\n\n   This approach keeps your credentials secure and avoids exposing them on the command line.\n\n3. **Create a configuration file** (optional):\n   ```bash\n   mkdir -p ~/.config/dbh\n   cp config.example ~/.config/dbh/config\n   ```\n\n4. **Add to your PATH** (optional):\n   ```bash\n   echo 'export PATH=\"$PATH:/path/to/dbh/directory\"' \u003e\u003e ~/.bashrc\n   source ~/.bashrc\n   ```\n\n## Quick Start\n\n```bash\n# Start with a specific database and table\ndbh mydb users\n\n# Interactive navigation\n[dbh]\u003e /databases             # List and select database\n[dbh:mydb]\u003e /tables           # List and select table\n[dbh:mydb:users]\u003e /describe   # Show table structure\n\n# Building queries\n[dbh:mydb:users]\u003e /columns id,name,email\n[dbh:mydb:users]\u003e /where active=1\n[dbh:mydb:users]\u003e /limit 10\n[dbh:mydb:users]\u003e /select\n\n# Direct SQL (no prefix needed)\n[dbh:mydb:users]\u003e SELECT COUNT(*) FROM users WHERE status='active'\n\n# Shell access\n[dbh:mydb:users]\u003e !ls -la     # Run shell command\n[dbh:mydb:users]\u003e !           # Launch interactive shell\n```\n\n## Usage\n\n```\ndbh v3.7.1 - Interactive MySQL client with slash commands, shell access, and direct SQL\n\nUsage:\n  dbh [Options] [database [table [command]]]\n\n  database  Optional: Initial database to connect to\n  table     Optional: Initial table to select\n  command   Optional: Initial command to execute\n\nOptions:\n  -p, --profile PROFILE  MySQL config file (Default: ~/.mylocalhost.cnf)\n  -v, --verbose   Increase verbosity\n  -q, --quiet     Suppress non-error messages\n  -V, --version   Print version and exit\n  -h, --help      Display this help\n```\n\n### Command Types\n\n- `/command` - Database operations (prefixed with `/`)\n- `!command` - Shell commands (prefixed with `!`)\n- `SQL query` - Direct SQL execution (no prefix needed)\n- `!number` - Repeat command from history by number\n\n### Prompt Format\n\nThe prompt always shows your current context:\n\n- `[dbh]` - No database selected\n- `[dbh:mysql]` - Database \"mysql\" selected\n- `[dbh:sakila:film]` - Database \"sakila\" and table \"film\" selected\n\n### Key Commands\n\n#### Navigation\n\n| Command | Description |\n|---------|-------------|\n| `/databases` | List and select a database |\n| `/database \u003cdb\u003e` | Directly select database |\n| `/tables` | List and select a table |\n| `/table \u003cn\u003e` | Directly select table |\n| `/..` or `/back` or `/0` | Go back one level |\n| `/q` or `/quit` or `/exit` | Exit the program |\n\n#### Query Building\n\n| Command | Description |\n|---------|-------------|\n| `/columns [cols]` | Set columns (shows interactive menu if no arguments) |\n| `/where [clause]` | Set WHERE clause |\n| `/order [cols]` | Set ORDER BY columns |\n| `/asc` or `/desc` | Set sort order direction |\n| `/limit [num]` | Set LIMIT |\n| `/select` | Execute query with current state |\n| `/state` | Show current query state |\n\n#### Table Operations\n\n| Command | Description |\n|---------|-------------|\n| `/describe` | Show table structure |\n| `/structure [v]` | Detailed column info (v=vertical format) |\n| `/status` | Show table status |\n| `/create` | Show CREATE TABLE statement |\n| `/count` | Show row count |\n| `/sample [n]` | Show n sample rows (default: 10) |\n| `/primary-key` | Show primary key columns |\n| `/indexes` | Show all indexes |\n| `/foreign-keys` | Show foreign key relationships |\n| `/find \u003ctext\u003e` | Search for text in all columns |\n| `/backup [file]` | Backup table to SQL file |\n\n#### Database Operations\n\n| Command | Description |\n|---------|-------------|\n| `/schema [v]` | Show database schema with relationships |\n| `/charset` | Show character set information |\n| `/engines` | List available storage engines |\n| `/backup [file]` | Backup current database to SQL file |\n\n#### Administration\n\n| Command | Description |\n|---------|-------------|\n| `/whoami` | Show current MySQL user and privileges |\n| `/whois [user]` | Show information about a specific MySQL user |\n| `/users` | Show MySQL users and privileges |\n| `/processes` | Show active MySQL processes |\n| `/variables [filter]` | Display MySQL system variables |\n| `/stats` | Show database/table statistics |\n| `/export [file]` | Export query results to file (CSV/SQL/JSON) |\n| `/sql \u003cSQL\u003e` | Execute arbitrary SQL |\n| `/prompt` | Open MySQL prompt |\n\n#### Configuration and History\n\n| Command | Description |\n|---------|-------------|\n| `/config show` | Display current configuration |\n| `/config create` | Create default config file |\n| `/config edit` | Open config file in editor |\n| `/config reload` | Reload configuration |\n| `/history [n]` | Show command history (last n entries) |\n| `↑/↓` | Navigate history with arrow keys |\n\nSee the [COMMANDS.md](COMMANDS.md) file for a complete command reference and [USAGE.md](USAGE.md) for more detailed examples and advanced usage scenarios.\n\n## Configuration\n\nThe configuration file is stored at `~/.config/dbh/config` and supports these options:\n\n```ini\n# Default MySQL configuration file\nDEFAULT_PROFILE=~/.mylocalhost.cnf\n\n# Default database on startup\n# DEFAULT_DATABASE=mysql\n\n# Default limit for SELECT queries\nDEFAULT_LIMIT=100\n\n# Maximum history entries\nMAX_HISTORY=1000\n\n# Pager program\n# PAGER=less -S\n```\n\nYou can create and manage this file using the `/config` commands within dbh.\n\n## Advanced Usage Examples\n\n### Interactive Query Building\n\n```bash\n# Start building a query\n[dbh:mydb:users]\u003e /columns    # Opens multi-select menu for columns\n[dbh:mydb:users]\u003e /where created_at \u003e '2023-01-01'\n[dbh:mydb:users]\u003e /order last_login\n[dbh:mydb:users]\u003e /desc       # Sort descending\n[dbh:mydb:users]\u003e /limit 50\n[dbh:mydb:users]\u003e /select     # Execute the query\n```\n\n### Export and Backup\n\n```bash\n# Export query results\n[dbh:mydb:users]\u003e /export users_export.csv\n[dbh:mydb:users]\u003e /export --format json users.json\n\n# Backup table or database\n[dbh:mydb:users]\u003e /backup users_backup.sql\n[dbh:mydb]\u003e /backup mydb_full.sql\n```\n\n### Shell Integration\n\n```bash\n# Run single shell command\n[dbh:mydb]\u003e !ls -la\n\n# Launch interactive shell\n[dbh:mydb]\u003e !\n$ echo \"Do something in shell\"\n$ exit\n[dbh:mydb]\u003e # Back to dbh\n```\n\n### Command History\n\n```bash\n# Show history\n[dbh]\u003e /history 20    # Show last 20 commands\n\n# Recall command by number\n[dbh]\u003e !5             # Execute history command #5\n\n# Use arrow keys to navigate previous commands\n# Press Up/Down arrows to cycle through history\n```\n\n## Security Features\n\n- **SQL Injection Prevention** - All user inputs are properly escaped using proven techniques\n- **Secure Credential Handling** - Uses MySQL configuration files instead of command-line passwords\n- **Temporary File Security** - Creates temp files with secure permissions (0600)\n- **Proper Cleanup** - Removes temporary files on exit\n- **Error Handling** - Properly catches and reports errors without exposing sensitive information\n- **Safe Defaults** - Conservative default settings to prevent accidental data exposure\n\n## Documentation\n\n- **[USAGE.md](USAGE.md)** - Comprehensive usage examples and advanced techniques\n- **[DEVELOPMENT.md](DEVELOPMENT.md)** - Information for developers interested in contributing\n- **[PURPOSE-FUNCTIONALITY-USAGE.md](PURPOSE-FUNCTIONALITY-USAGE.md)** - Detailed explanation of the tool's purpose and design principles\n\n## License\n\nGNU General Public License v3.0 (GPL-3.0)\n\ndbh is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.\n\nThe full text of the license can be found in the [LICENSE](LICENSE) file.\n\n## Contributing\n\nContributions are welcome! Please submit pull requests to the [official repository](https://github.com/Open-Technology-Foundation/dbh). See [DEVELOPMENT.md](DEVELOPMENT.md) for guidelines on development and contribution.\n\n## Support\n\nIf you encounter issues or have questions, please open an issue on the [GitHub repository](https://github.com/Open-Technology-Foundation/dbh/issues).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-technology-foundation%2Fdbh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-technology-foundation%2Fdbh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-technology-foundation%2Fdbh/lists"}