dbngin-sync

Sync remote MySQL databases to local Dbngin instances over SSH with streaming pipes.

A lightweight terminal tool designed for macOS users who use Dbngin to manage their local databases. This script allows you to securely sync a remote MySQL database to your local environment over SSH using efficient streaming pipes.

✨ Features

• TUI Driven: Interactive selection for remote databases and local Dbngin instances powered by fzf (fuzzy search, keyboard navigation).
• Zero Dependencies: Pure Bash script, no Node.js or Python required (just fzf and ssh).
• Auto-Config: Saves your credentials in a .env file for faster subsequent runs.
• Efficient Syncing: Streams mysqldump directly into mysql via SSH pipes (no giant temp files).
• Dbngin Aware: Automatically detects your Dbngin MySQL binaries and lets you choose a version when multiple exist.
• Automatic Backups: Offers to create a compressed backup before overwriting an existing local database.
• SSH Multiplexing: Reuses a single SSH connection for the entire session (faster, fewer auth prompts).
• Error Diagnostics: Captures and displays real error output to help troubleshoot failures.
• Graceful Interrupts: Safe Ctrl+C handling with automatic cleanup.

🚀 Getting Started

Prerequisites

1. macOS (Apple Silicon or Intel).
2. Dbngin installed and running.
3. fzf installed (brew install fzf).
4. SSH access to your remote server.
5. MySQL/MariaDB running on the remote server.

Installation

1. Clone or download this repository.
2. Ensure the script is executable:

   chmod +x sync-db.sh

Usage

Run the script from your terminal:

./sync-db.sh

The script will:

1. Ask for your SSH and database credentials (if not already in .env).
2. Test the SSH connection and establish a multiplexed session.
3. List all databases on your remote server.
4. Let you choose which database to sync (fuzzy-searchable via fzf).
5. Let you specify the local database name (defaults to remote name).
6. Detect Dbngin MySQL binaries and let you pick one if multiple exist.
7. Show a summary and ask for confirmation.
8. If the target exists: warn you, offer to overwrite, and optionally create a backup first.
9. Stream the remote dump directly into your local database with live progress spinner.
10. Display a completion summary with table count.

Keyboard Shortcuts

During fzf selection menus:

Key	Action
↑ / ↓	Navigate options
/	Fuzzy search
Enter	Select
Esc	Quit

At any prompt:

Input	Action
q / Q	Quit (at credential prompts)
Ctrl+C	Interrupt with cleanup

⚙️ Configuration

Your credentials are saved in .env. You can edit this file manually at any time.

Variable	Description
SSH_IP	Remote server IP address or hostname.
SSH_USER	SSH username for the remote server.
SSH_PORT	SSH port (default is 22).
REMOTE_DB_USER	MySQL username on the remote server.
REMOTE_DB_PASS	MySQL password on the remote server.
LOCAL_DB_USER	Local MySQL username (usually root).
LOCAL_DB_PASS	Local MySQL password (usually empty).
LOCAL_DB_PORT	Local MySQL port (usually 3306).

📁 Directory Structure

.
├── sync-db.sh          # Main executable script
├── .env                # Saved credentials (gitignored)
├── .env.example        # Template for .env
├── .profiles/          # Named profiles (e.g., school.env)
├── backups/            # Automatic pre-sync backups
├── README.md           # This file
└── QWEN.md             # Project documentation

Profiles

You can store named profiles in .profiles/ (e.g., .profiles/school.env) to quickly switch between different remote configurations. Source a profile before running the script:

set -a; source .profiles/school.env; set +a
./sync-db.sh

⚠️ Important Note

Warning

This tool will overwrite tables in your target local database. Please ensure you have backed up any critical local data before performing a sync.

🐛 Troubleshooting

Issue	Solution
fzf is not installed	Run brew install fzf
SSH connection failed	Verify IP, port, username, and SSH key/password
Failed to fetch remote databases	Check remote MySQL credentials and user permissions
Failed to import into local database	Ensure Dbngin is running, port is correct, and disk space is available
No Dbngin mysql binaries found	Verify Dbngin is installed at /Users/Shared/DBngin/mysql

---

Created with ❤️ by Antigravity