DB CLI

A command-line interface tool for managing PostgreSQL databases with a focus on simplicity, security, and user experience. Features interactive prompts, beautiful terminal output, secure credential storage, and multi-connection management.

A JavaScript CLI tool that helps you configure multiple database connections and create new databases with ease.

Features

• 🔧 Interactive configuration system
• 🗄️ PostgreSQL database management
• 🌐 Multiple named connections - manage different database environments
• 🎯 Default connection support for streamlined workflows
• 🗃️ Configurable database names with defaults
• 🎨 Beautiful terminal output with colors and boxes
• 🔐 Secure password storage using system keychain
• 💾 Connection string generation
• 📋 List and manage all saved connections

Prerequisites

• PostgreSQL server installed and running
• Node.js 16.x or higher
• npm or yarn package manager
• sudo access (for global installation)
• System keychain (recommended for enhanced security):
  • Linux: libsecret and gnome-keyring (sudo apt-get install gnome-keyring on Ubuntu/Debian)
  • macOS: Keychain Access (built-in)
  • Windows: Credential Manager (built-in)
  • Note: If keychain is unavailable, passwords will be stored encrypted locally

Installation

You can install the CLI tool in two ways:

1. Via npm (Recommended)

npm install -g https://github.com/paulgeorge35/db-cli

2. From Source

# Clone the repository
git clone https://github.com/paulgeorge35/db-cli
cd db-cli

# Install dependencies
npm install

# Link the package globally
npm link

Usage

Configure Database Connections

Create named connections for different environments:

# Configure a production connection
db-cli config production

# Configure and set as default
db-cli config development --default

This interactive command will help you set up your database connection:

? Enter database host: localhost
? Enter database port: (5432)
? Enter database user: (root)
? Enter database name: (postgres)
? Enter connection description (optional): Development database
? Enter database password: [hidden]

List All Connections

View all saved connections:

db-cli list

Example output:

┌ Connections ──────────────────────────────────────────────────────┐
│                                                                   │
│ Saved Connections:                                                │
│                                                                   │
│ • production                                                      │
│   Host: prod-db.example.com:5432                                  │
│   User: app_user                                                  │
│   Database: myapp_prod                                            │
│   Description: Production database                                │
│   Password: ✓ Stored                                              │
│                                                                   │
│ • development (default)                                           │
│   Host: localhost:5432                                            │
│   User: dev_user                                                  │
│   Database: myapp_dev                                             │
│   Password: ✓ Stored                                              │
│                                                                   │
└───────────────────────────────────────────────────────────────────┘

View Connection Details

View connection details and connection strings:

# View default connection
db-cli view

# View specific connection
db-cli view production

# Show password in connection string
db-cli view production --show-password

Set Default Connection

Set a connection as the default:

db-cli default production

Create New Database

Create a new database using a connection:

# Use default connection
db-cli add db

# Use specific connection
db-cli add db production

Example output:

? Enter the database name: myapp_staging
✔ Database created successfully!

Connection string:
postgresql://app_user:****@prod-db.example.com:5432/myapp_staging

Delete Connection

Remove a saved connection:

db-cli delete staging

Reset All Connections

Remove all saved connections:

db-cli reset

Help

Get help on available commands:

db-cli --help

# Get help for specific commands
db-cli config --help
db-cli view --help

Configuration Storage

The tool uses two secure storage mechanisms:

1. Connection configurations (host, port, username, database, description) are stored using the conf package in:

   • macOS: ~/Library/Preferences/db-cli-nodejs
   • Windows: %APPDATA%/db-cli-nodejs/Config
   • Linux: ~/.config/db-cli-nodejs

2. Passwords are securely stored using a two-tier approach:

   • Primary: System's native keychain (most secure)
     • macOS: Keychain Access
     • Windows: Credential Manager
     • Linux: Secret Service API (GNOME Keyring/KWallet)
   • Fallback: Encrypted local storage when keychain is unavailable
     • Uses AES-256 encryption with machine-specific keys
     • Automatically used on headless servers or systems without keyring services

Each connection is stored independently, allowing you to manage multiple database environments securely. The tool will automatically use the most secure storage method available on your system.

Command Reference

Command	Description	Example
config <name>	Configure a named connection	db-cli config production
config <name> --default	Configure and set as default	db-cli config dev --default
list	List all saved connections	db-cli list
view [name]	View connection details	db-cli view production
view [name] -p	View with password shown	db-cli view production -p
default <name>	Set default connection	db-cli default production
add db [name]	Create new database	db-cli add db staging
delete <name>	Delete connection	db-cli delete old-connection
reset	Remove all connections	db-cli reset

Example Workflow

# Set up different environments
db-cli config production
db-cli config staging
db-cli config development --default

# List all connections
db-cli list

# Create databases in different environments
db-cli add db production    # Creates DB using production connection
db-cli add db               # Creates DB using default (development) connection

# Switch default environment
db-cli default staging

# View connection details
db-cli view production --show-password

Dependencies

Core dependencies:

• boxen (^8.0.1): Create boxes in terminal
• chalk (^5.4.1): Terminal string styling
• yargs (^18.0.0): Command-line argument parsing
• inquirer (^12.9.4): Interactive command prompts
• pg (^8.11.3): PostgreSQL client
• conf (^14.0.0): Configuration storage
• keytar (^7.9.0): Secure password storage

Troubleshooting

Keychain/Keyring Issues on Linux

If you encounter errors like [Error: Object does not exist at path "/org/freedesktop/secrets/collection/login"] on Ubuntu/Debian systems:

1. Install the required packages:

   sudo apt-get update
   sudo apt-get install gnome-keyring libsecret-1-dev

2. For headless servers (VPS/Docker): The CLI will automatically use encrypted local storage as a fallback. You'll see a security notice when this happens.

3. Manual keyring setup (if needed):

   # Start the keyring daemon
   eval $(gnome-keyring-daemon --start)
   export GNOME_KEYRING_CONTROL
   export SSH_AUTH_SOCK
   export GNOME_KEYRING_PID

Other Common Issues

• Permission errors: Ensure you have proper permissions to access the keychain/keyring
• Network connectivity: Verify your database server is accessible
• Node.js version: Ensure you're using Node.js 16.x or higher

Debug Mode

If you're experiencing issues with password storage/retrieval, you can enable debug mode:

DB_CLI_DEBUG=1 db-cli view <connection-name>

This will show additional information about keyring availability and fallback storage status.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contact

Paul George - contact@paulgeorge.dev

Project Link: https://github.com/paulgeorge35/db-cli