{"id":37063318,"url":"https://github.com/k4kratik/smart-rds-viewer","last_synced_at":"2026-01-14T07:05:12.686Z","repository":{"id":307331763,"uuid":"1029169888","full_name":"k4kratik/smart-rds-viewer","owner":"k4kratik","description":"Terminal-based RDS viewer because your terminal deserves better RDS monitoring than `aws rds describe-db-instances`","archived":false,"fork":false,"pushed_at":"2025-08-11T02:53:42.000Z","size":3502,"stargazers_count":3,"open_issues_count":6,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-06T04:40:39.735Z","etag":null,"topics":["aurora","aws","boto3","mysql","python","rds","rds-database"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/smart-rds-viewer/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/k4kratik.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}},"created_at":"2025-07-30T16:15:28.000Z","updated_at":"2025-08-12T17:45:28.000Z","dependencies_parsed_at":"2025-07-30T18:57:06.009Z","dependency_job_id":"e11b4c4f-ca66-47f2-9018-fd1b471ba60f","html_url":"https://github.com/k4kratik/smart-rds-viewer","commit_stats":null,"previous_names":["k4kratik/smart-rds-viewer"],"tags_count":57,"template":false,"template_full_name":null,"purl":"pkg:github/k4kratik/smart-rds-viewer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k4kratik%2Fsmart-rds-viewer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k4kratik%2Fsmart-rds-viewer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k4kratik%2Fsmart-rds-viewer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k4kratik%2Fsmart-rds-viewer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/k4kratik","download_url":"https://codeload.github.com/k4kratik/smart-rds-viewer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k4kratik%2Fsmart-rds-viewer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28412502,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T05:26:33.345Z","status":"ssl_error","status_checked_at":"2026-01-14T05:21:57.251Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["aurora","aws","boto3","mysql","python","rds","rds-database"],"created_at":"2026-01-14T07:05:11.946Z","updated_at":"2026-01-14T07:05:12.677Z","avatar_url":"https://github.com/k4kratik.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Smart RDS Viewer\n\n\u003e **Your terminal companion for monitoring Amazon RDS instances with real-time data, pricing, and interactive insights!**\n\n\u003c!-- markdownlint-disable MD033 --\u003e\n\u003cimg src=\"https://github.com/k4kratik/smart-rds-viewer/raw/main/docs/smart-rds-viewer-logo.png\" alt=\"Smart RDS Viewer\" width=\"100\"\u003e\n\u003c!-- markdownlint-enable MD033 --\u003e\n\nA powerful, full-screen terminal CLI that fetches and displays all your Amazon RDS instances with live metrics, pricing, and interactive sorting - all from the comfort of your terminal.\n\n![Smart RDS Viewer Demo](https://github.com/k4kratik/smart-rds-viewer/raw/main/docs/image.png)\n\n![Smart RDS Viewer Demo - Help Menu](https://github.com/k4kratik/smart-rds-viewer/raw/main/docs/image-help.png)\n\n![Smart RDS Viewer Demo - RI Utilization](https://github.com/k4kratik/smart-rds-viewer/raw/main/docs/image-ri.png)\n\n## ✨ Features\n\n- **🔧 Backup \u0026 Maintenance View**: Complete operational monitoring with backup windows, retention policies, and maintenance schedules\n- **🎯 Smart Column Sorting**: Intuitive 1-9 then a-z shortcuts with visual indicators for active sort column and direction\n- **🎨 Visual Sort Feedback**: Colorful underlines and directional arrows show exactly what's being sorted and how\n- **📏 Dynamic Responsive Design**: Adaptive column widths that automatically optimize for your terminal size\n- **🕐 Intelligent Time Handling**: Local timezone conversion and chronological sorting for time-based columns\n- **⚡ Enhanced Performance**: Optimized sorting algorithms for numeric, time-based, and special value handling\n\n## ✨ Core Features\n\n### 🔍 **Real-time Data Fetching**\n\n- **RDS Metadata**: Fetches all RDS instances using `boto3`\n- **CloudWatch Metrics**: Live storage usage from CloudWatch APIs\n- **Live Pricing**: On-demand hourly and monthly pricing from AWS Pricing API\n- **Smart Caching**: 24-hour pricing cache in `/tmp` for faster subsequent runs\n\n### 📊 **Rich Interactive Table**\n\n- **Full-screen Terminal**: Professional full-screen interface like `eks-node-viewer`\n- **Comprehensive Columns**: 12+ metrics including all pricing components\n- **Smart Highlighting**: Targeted red highlighting for storage issues (≥80% usage)\n- **Multi-AZ Support**: 👥 indicators with accurate 2x pricing for Multi-AZ instances\n- **Aurora Compatible**: Special handling for Aurora instances and pricing\n- **Real-time Updates**: Live data refresh with loading spinners\n\n### 🎮 **Interactive Controls**\n\n- **Intuitive Shortcuts**: Simple 1-9 then a-z keys for column sorting (1=Name, 2=Class, etc.)\n- **Visual Sort Indicators**: Colorful underlines and arrows (↑↓) show active sort column and direction\n- **Smart Sorting**: Toggle ascending/descending with same key, handles time-based and numeric data intelligently\n- **Multi-View Interface**: Three integrated views accessible via keyboard shortcuts\n  - **Pricing View** (`V`): Cost analysis with hourly/monthly toggle\n  - **Backup \u0026 Maintenance View** (`B`): Backup windows, retention, maintenance schedules\n  - **RI Utilization View** (`R`): Reserved Instance coverage and utilization\n- **Dynamic Spacing**: Responsive column widths that adapt to terminal size\n- **Pricing Toggle**: Press `m` to switch between hourly and monthly cost views\n- **Help System**: Press `?` for interactive help overlay with context-aware shortcuts\n- **Clean Exit**: `q` or `Ctrl+C` to exit with terminal cleanup\n- **Arrow Key Navigation**: Use `←`/`→` or `Tab`/`Shift+Tab` for seamless view cycling\n\n### 📈 **Comprehensive Metrics**\n\n- **Instance Details**: Name, class, Multi-AZ indicators (👥)\n- **Storage Analytics**: Used percentage, free space in GiB\n- **Performance**: IOPS, EBS throughput (with GP2/GP3 awareness)\n- **Complete Cost Breakdown**: Instance, Storage, IOPS, and EBS Throughput pricing\n- **Flexible Cost Views**: Toggle between hourly and monthly pricing with daily/monthly estimates\n- **Backup \u0026 Maintenance**: Backup windows, retention periods, maintenance schedules with local timezone display\n- **Operational Insights**: Next maintenance timing, pending actions, and maintenance urgency indicators\n\n### 💰 **Reserved Instance (RI) Analysis**\n\n- **Comprehensive RI Support**: Automatic RI discovery with size flexibility matching\n- **Cost Optimization**: Real-time coverage analysis and savings calculations\n- **Visual Indicators**: Color-coded instance names based on RI coverage\n\n\u003e 📖 **Detailed RI Documentation**: See [docs/RESERVED-INSTANCES.md](docs/RESERVED-INSTANCES.md) for complete RI feature documentation, size flexibility algorithms, and implementation details.\n\n## 🛠️ Installation\n\n### Prerequisites\n\n- Python 3.8+\n- AWS credentials configured (environment variables or IAM profile)\n- Required AWS permissions for RDS, CloudWatch, Pricing, and Reserved Instance APIs\n\n### AWS Configuration\n\nSet your AWS profile and region (recommended):\n\n```bash\nexport AWS_PROFILE=your-profile-name\nexport AWS_REGION=your-region  # e.g., us-east-1, ap-south-1\n```\n\n**Required AWS Permissions:**\n\n- `rds:DescribeDBInstances` - Fetch RDS instance metadata\n- `rds:DescribeReservedDBInstances` - Reserved Instance information\n- `rds:DescribePendingMaintenanceActions` - Maintenance and backup information\n- `cloudwatch:GetMetricStatistics` - Storage usage metrics\n- `pricing:GetProducts` - Live pricing data\n\n### Quick Start\n\n#### Option 1: Install via pip (Recommended)\n\n```bash\n# Install the package\npip install smart-rds-viewer\n\n# Run the viewer\nsmart-rds-viewer\n```\n\n#### Option 2: Development/Local Installation\n\n```bash\n# Clone and setup\ngit clone \u003cyour-repo\u003e\ncd smart-rds-viewer\n\n# Create virtual environment\npython3 -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install in development mode\npip install -e .\n\n# Run the viewer\nsmart-rds-viewer\n```\n\n#### Option 3: Run as Python Script\n\n```bash\n# Clone and setup\ngit clone \u003cyour-repo\u003e\ncd smart-rds-viewer\n\n# Create virtual environment\npython3 -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install dependencies\npip install -r requirements.txt\n\n# Run the viewer\npython rds_viewer.py\n```\n\n## 🎯 Usage\n\n### Basic Usage\n\n```bash\n# Standard run\nsmart-rds-viewer\n\n# Alternative command (shorter)\nrds-viewer\n\n# Check version\nsmart-rds-viewer --version\n\n# Force fresh pricing data (bypass cache)\nsmart-rds-viewer --nocache\n\n# Legacy method (if running from source)\npython rds_viewer.py --nocache\n```\n\n### Interactive Controls\n\n- **Column Sorting**: Press number keys (1-9) then letters (a-z) to sort by any column\n- **Visual Feedback**: Active sort column shows colorful underline and direction arrows (↑↓)\n- **View Navigation**:\n  - `Shift+V` - Pricing View (main cost analysis)\n  - `Shift+B` - Backup \u0026 Maintenance View\n  - `Shift+R` - Reserved Instance Utilization View\n- **Pricing Toggle**: Press `m` to switch between hourly and monthly costs\n- **Help**: Press `?` to toggle context-aware help overlay\n- **Quit**: Press `q` or `Ctrl+C` to exit\n\n### Column Shortcuts (Consistent across all views)\n\n#### Pricing View\n\n| Key | Column                        | Description                           |\n| --- | ----------------------------- | ------------------------------------- |\n| `1` | Name                          | Instance identifier (👥 = Multi-AZ)   |\n| `2` | Class                         | Instance type (db.r5.large, etc.)     |\n| `3` | Storage (GB)                  | Allocated storage                     |\n| `4` | % Used                        | Storage utilization percentage        |\n| `5` | Free (GiB)                    | Available storage space               |\n| `6` | IOPS                          | Provisioned IOPS                      |\n| `7` | EBS Throughput                | Storage throughput (MB/s)             |\n| `8` | Instance ($/hr or $/mo)       | Instance pricing (toggles with `m`)   |\n| `9` | Storage ($/hr or $/mo)        | Storage pricing (toggles with `m`)    |\n| `a` | IOPS ($/hr or $/mo)           | IOPS pricing (toggles with `m`)       |\n| `b` | EBS Throughput ($/hr or $/mo) | Throughput pricing (toggles with `m`) |\n| `c` | Total ($/hr or $/mo)          | Total cost (toggles with `m`)         |\n\n#### Backup \u0026 Maintenance View\n\n| Key | Column             | Description                          |\n| --- | ------------------ | ------------------------------------ |\n| `1` | Name               | Instance identifier (👥 = Multi-AZ)  |\n| `2` | Class              | Instance type                        |\n| `3` | Engine             | Database engine (MySQL, PostgreSQL)  |\n| `4` | Storage            | Allocated storage                    |\n| `5` | Backup Window      | Daily backup time window (local TZ)  |\n| `6` | Retention          | Backup retention period (days)       |\n| `7` | Maintenance Window | Weekly maintenance window (local TZ) |\n| `8` | Next               | Next maintenance timing              |\n| `9` | Pending Actions    | Pending maintenance actions          |\n\n### Special Controls\n\n| Key       | Function       | Description                        |\n| --------- | -------------- | ---------------------------------- |\n| `m`       | Pricing Toggle | Switch between hourly/monthly view |\n| `Shift+V` | Pricing View   | Go to main pricing/cost view       |\n| `Shift+B` | Backup View    | Go to backup \u0026 maintenance view    |\n| `Shift+R` | RI View        | Go to Reserved Instance view       |\n| `?`       | Help           | Show/hide interactive help overlay |\n| `q`       | Quit           | Exit application                   |\n\n### Navigation Controls\n\n| Key         | Function       | Description                         |\n| ----------- | -------------- | ----------------------------------- |\n| `←`         | Previous Tab   | Cycle to previous view (infinite)   |\n| `→`         | Next Tab       | Cycle to next view (infinite)       |\n| `Tab`       | Cycle Forward  | Navigate between views sequentially |\n| `Shift+Tab` | Cycle Backward | Navigate between views in reverse   |\n\n### Visual Indicators\n\n- **🔵 Cyan Underline ↑**: Column sorted ascending\n- **🟣 Magenta Underline ↓**: Column sorted descending\n- **👥**: Multi-AZ instance (2x pricing)\n- **🟢 Green**: Low urgency maintenance (\u003e7 days)\n- **🟡 Yellow**: Medium urgency maintenance (1-7 days)\n- **🔴 Red**: High urgency maintenance (overdue/today)\n\n## 🔧 Technical Details\n\n### Architecture\n\n- **Modular Design**: Separate modules for fetching, metrics, pricing, and UI\n- **Error Handling**: Graceful fallbacks for API failures\n- **Caching**: Smart pricing cache with 24-hour expiration\n- **Full-screen UI**: Rich-based terminal interface\n\n### AWS APIs Used\n\n- **RDS**: `describe_db_instances` for metadata, `describe_reserved_db_instances` for RI data, `describe_pending_maintenance_actions` for maintenance info\n- **CloudWatch**: `get_metric_statistics` for storage metrics\n- **Pricing**: `get_products` for live pricing data\n\n### Cache System\n\n- **Location**: `/tmp/rds_pricing_cache.json`\n- **Duration**: 24 hours\n- **Auto-refresh**: Expired cache triggers fresh API calls\n- **Manual override**: Use `--nocache` flag to force fresh data\n- **Error Recovery**: Corrupted cache falls back to API\n\n## 🤖 Built with AI Assistance\n\nThis tool was collaboratively developed with the help of **Claude Sonnet 4**, an AI coding assistant. The development process involved:\n\n- **Architecture Design**: Modular structure with separate modules for different concerns\n- **Feature Implementation**: Real-time data fetching, caching, interactive UI\n- **Problem Solving**: Debugging pricing API issues, fixing cache serialization\n- **User Experience**: Full-screen terminal interface, dynamic shortcuts, help system\n- **Documentation**: Comprehensive README with all features and future roadmap\n\nThe AI assistant helped transform a simple concept into a comprehensive, production-ready RDS monitoring tool with advanced features like smart caching, interactive sorting, and professional terminal UI.\n\n## 📁 Project Structure\n\nThe project follows a modular architecture with separate modules for different concerns:\n\n- **Core modules**: `rds_viewer.py`, `ui.py`, `fetch.py`, `metrics.py`, `pricing.py`\n- **Documentation**: Comprehensive docs in `docs/` directory\n- **Development tools**: Debug scripts in `scripts/` and performance benchmarks in `benchmarks/`\n\n\u003e 📖 **Performance Details**: See [docs/BENCHMARKING.md](docs/BENCHMARKING.md) for detailed performance optimizations, benchmarking results, and optimization techniques.\n\n## 🛠️ Development \u0026 Contributing\n\nThe project includes comprehensive development tools and documentation:\n\n- **Debug Tools**: Pricing analysis and debugging scripts in `scripts/` directory\n- **Performance Testing**: Benchmarking tools in `benchmarks/` directory\n- **Development Setup**: Complete setup instructions and guidelines\n\n\u003e 📖 **Development Documentation**:\n\u003e\n\u003e - [CONTRIBUTING.md](CONTRIBUTING.md) - Contribution guidelines and development setup\n\u003e - [docs/BENCHMARKING.md](docs/BENCHMARKING.md) - Performance testing and optimization\n\u003e - [docs/PUBLISHING.md](docs/PUBLISHING.md) - PyPI publishing workflow\n\u003e - [SECURITY.md](SECURITY.md) - Security policy and vulnerability reporting\n\n## 📦 Publishing to PyPI\n\nFor maintainers: To publish this package to PyPI, see the detailed publishing guide in [docs/PUBLISHING.md](docs/PUBLISHING.md) with complete workflows, testing procedures, and troubleshooting tips.\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on development setup, code standards, and contribution workflows.\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## 🙏 Acknowledgments\n\n- Built with [Rich](https://github.com/Textualize/rich) for beautiful terminal UI\n- Powered by [boto3](https://github.com/boto/boto3) for AWS integration\n- Inspired by modern CLI tools like `eks-node-viewer`\n- **AI Development Partner**: Claude Sonnet 4 for collaborative coding and problem-solving\n- [@sachincool](https://github.com/sachincool) for the cool logo 🫡\n- [@kutumbtech](https://github.com/kutumbtech) for everything 🙏\n\n---\n\n## Happy RDS monitoring! 🎉\n\n_Your terminal is now your RDS command center!_\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk4kratik%2Fsmart-rds-viewer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fk4kratik%2Fsmart-rds-viewer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk4kratik%2Fsmart-rds-viewer/lists"}