DB Tester CLI

A Python CLI tool for database connectivity testing, network diagnostics, and health monitoring.

Supports PostgreSQL, MySQL/MariaDB, MongoDB, Redis, and SQLite.

Installation

pip install db-tester-cli

From Source

git clone https://github.com/Legolasan/db-tester.git
cd db-tester
pip install -e .

Quick Start

# Test with connection string
db-tester postgres://user:pass@localhost:5432/mydb

# Test with flags
db-tester --host localhost --port 5432 --type postgres --user admin

# Network check only (no DB connection)
db-tester --host 192.168.1.100 --port 5432 --ping-only

# Interactive mode
db-tester

Features

Network Diagnostics

• DNS resolution with timing
• TCP port connectivity check
• Round-trip latency measurement (3 samples)
• Firewall detection (closed vs filtered ports)

Database Connection Testing

• Authentication verification
• SSL/TLS status check
• Connection time measurement
• Server version detection

Health Monitoring

• Database version and uptime
• Active vs max connections
• Database size
• Replication status (primary/replica/standalone)
• Database-specific metrics (slow queries, memory usage, etc.)

Troubleshooting

Auto-detects common issues and provides suggestions:

• Connection refused → Service running? Firewall?
• Authentication failed → Credentials correct? User exists?
• SSL required → Add ?sslmode=require
• Too many connections → Increase max or use pooling
• Timeout → Network issues, server load

Usage

Connection String Format

# PostgreSQL
db-tester postgres://user:pass@host:5432/database
db-tester postgresql://user:pass@host:5432/database?sslmode=require

# MySQL / MariaDB
db-tester mysql://user:pass@host:3306/database

# MongoDB
db-tester mongodb://user:pass@host:27017/database

# Redis
db-tester redis://:password@host:6379/0

# SQLite
db-tester sqlite:///path/to/database.db
db-tester /path/to/database.db

Command Line Options

Examples

# Test local PostgreSQL
db-tester postgres://postgres@localhost:5432/postgres

# Test remote MySQL with SSL
db-tester --host db.example.com --port 3306 --type mysql --user admin --ssl

# Quick network check to see if port is open
db-tester --host 195.35.22.87 --port 5432 --ping-only

# Verbose output for debugging
db-tester postgres://user:pass@host/db -v

# Test Redis with password
db-tester redis://:mypassword@localhost:6379/0

Output Examples

Successful Connection

╔═══════════════════════════════════════════════╗
║     🔌 DB Tester - Database Diagnostics       ║
╚═══════════════════════════════════════════════╝

   Connection Configuration
   Host     localhost
   Port     5432
   Type     postgres
   SSL      Disabled

   Network Diagnostics
   ┌────────────────┬────────┬─────────────────────┐
   │ Check          │ Status │ Details             │
   ├────────────────┼────────┼─────────────────────┤
   │ DNS Resolution │ ✓ OK   │ 127.0.0.1 (0.5ms)   │
   │ Port Check     │ ✓ OK   │ Port 5432 open      │
   │ Latency        │ ✓ OK   │ avg=1.2ms           │
   └────────────────┴────────┴─────────────────────┘

   ✓ Connected successfully in 45.3ms
     SSL disabled
     Version: PostgreSQL 15.3

   ╭──────────────── POSTGRES Health ────────────────╮
   │ Version             15.3                        │
   │ Uptime              5 days, 3:42:15             │
   │ Active Connections  12 / 100                    │
   │ Database Size       256 MB                      │
   │ Replication Role    standalone                  │
   ╰─────────────────────────────────────────────────╯

   ✓ All tests passed!

Connection Failure

   ✗ Connection failed: password authentication failed

   ╭──────────────── Troubleshooting ────────────────╮
   │ Authentication failed - invalid credentials     │
   │                                                 │
   │ Suggestions:                                    │
   │   • Verify the username and password            │
   │   • Check if the user exists in the database    │
   │   • For PostgreSQL: Check pg_hba.conf           │
   ╰─────────────────────────────────────────────────╯

Development

# Clone the repository
git clone https://github.com/Legolasan/db-tester.git
cd db-tester

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

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

# Run tests
pytest

# Run tests with coverage
pytest --cov=db_tester --cov-report=term-missing

Building & Publishing

# Install build tools
pip install build twine

# Build the package
python -m build

# Check the package
twine check dist/*

# Upload to TestPyPI (for testing)
twine upload --repository testpypi dist/*

# Upload to PyPI
twine upload dist/*

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE for details.

Author

Arun Sunderraj - GitHub