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
| Option | Short | Description |
|---|---|---|
--host |
-h |
Database hostname or IP |
--port |
-p |
Port number |
--type |
-t |
DB type: postgres, mysql, mongodb, redis, sqlite |
--user |
-u |
Username |
--password |
-P |
Password (prompts if omitted) |
--database |
-d |
Database name |
--ssl |
Enable SSL/TLS | |
--timeout |
Connection timeout in seconds (default: 10) | |
--ping-only |
Network diagnostics only | |
--verbose |
-v |
Show detailed output |
--version |
Show version |
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
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
License
MIT License - see LICENSE for details.
Author
Arun Sunderraj - GitHub
Metadata
Release files for db-tester-cli 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| db_tester_cli-0.1.0.tar.gz | 24.6 kB | Without provenance | Details for db_tester_cli-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| db_tester_cli-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for db_tester_cli-0.1.0-py3-none-any.whl |
Total release size: 52.4 kB
Release files / db_tester_cli-0.1.0.tar.gz
| Download URL | db_tester_cli-0.1.0.tar.gz |
|---|---|
| Size | 24.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
91e3cfe313bc4a5fe235b4cf858f850abb101e12a7f220384976668ab5f61170
|
|
BLAKE2b-256 checksum How to use checksums |
a4b349d9f6e6de27117c060f4295cd831ad5427ce8bff31a60325249e9c6aa2a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.2
|
Release files / db_tester_cli-0.1.0-py3-none-any.whl
| Download URL | db_tester_cli-0.1.0-py3-none-any.whl |
|---|---|
| Size | 27.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
34fe7241a158f51758ae9f6f2b1b7a05b78f3002ca4f7ab9344673dbc882a418
|
|
BLAKE2b-256 checksum How to use checksums |
b4ae36cc0f1ca105572de68936912bd0bab9fa64fe00a36eed24a944cb9b11b9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.2
|
Security for db-tester-cli 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.