sqltool

Local MySQL/MariaDB instance manager for development. No containers, no systemd services - just isolated database instances that run when you need them.

Features

• No containers - runs mysqld directly as your user
• Isolated instances - each project gets its own data directory, socket, port, and logs
• No auto-start - databases only run when you start them
• Multi-distro support - auto-detects your distro and installs MariaDB if needed
• Simple workflow - add, start, stop, backup, restore, clone

Requirements

• Perl 5 (pre-installed on most systems)
• MariaDB or MySQL (auto-installed if missing)

Installation

macOS (Homebrew)

brew tap lucianofedericopereira/sqltool
brew install sqltool

Linux

git clone https://github.com/lucianofedericopereira/sqltool.git
cd sqltool
chmod +x sqltool
sudo cp sqltool /usr/local/bin/

Or just run it from anywhere:

./sqltool help

Quick Demo

Run the included demo script to see sqltool in action:

./tryme.sh

This will:

1. Create a test instance called demo
2. Start it
3. Create a sample table with data
4. Make a backup
5. Stop the instance

After the demo, clean up with ./sqltool remove demo.

Usage

# Create a new database instance
sqltool add myproject

# Start it
sqltool start myproject

# Connect
mysql -u myproject -p -S ~/sql/myproject/data/mysql.sock
# or via TCP
mysql -u myproject -p -h 127.0.0.1 -P 3307

# Stop when done
sqltool stop myproject

# See all instances
sqltool list

Commands

| Command | Description | |---------|-------------| | add <project> | Create new database instance | | remove <project> | Delete instance and all data | | start <project> | Start instance | | stop <project> | Stop instance | | list | List all instances | | info <project> | Show instance details | | port <project> | Show port number | | logs <project> | Show recent error logs | | backup <project> | Create SQL backup | | restore <project> <file.sql> | Restore from backup | | clone <src> <dst> | Clone an instance | | status <project> | Quick status check | | help | Show help |

Directory Structure

All data is stored in ~/sql/:

~/sql/
├── myproject/
│   ├── data/          # MySQL data files
│   │   └── mysql.sock # Unix socket
│   ├── etc/
│   │   └── my.cnf     # Instance config
│   ├── logs/
│   │   └── error.log  # Error log
│   └── scripts/
│       ├── start      # Start script
│       └── stop       # Stop script
├── anotherproject/
│   └── ...
└── backups/           # SQL backups

Supported Systems

Auto-detection and installation works on:

• macOS: via Homebrew (Apple Silicon and Intel)
• Debian/Ubuntu family: Debian, Ubuntu, Linux Mint, Pop!_OS, elementary OS
• Red Hat family: Fedora, RHEL, CentOS, Rocky Linux, AlmaLinux
• Arch family: Arch Linux, Manjaro
• SUSE family: openSUSE, SUSE
• Others: Void Linux, Alpine Linux

For other systems, install MariaDB manually first.

Why Perl?

Perl is the right tool for this job:

• Pre-installed everywhere - available on virtually every GNU/Linux system out of the box, from Debian to Arch to Alpine
• No setup required - no pip install, no npm install, no cargo build, no virtual environments, no dependency hell
• Uses only core modules - File::Path, File::Basename, POSIX are part of Perl's standard library since forever
• Single file distribution - copy one file, make it executable, done
• Battle-tested stability - Perl scripts written 20 years ago still run today without modification
• Fast startup - instant execution, no JIT warm-up, no interpreter initialization overhead
• Excellent for system tasks - process management, file operations, and text processing are Perl's bread and butter

The Unix tradition

Perl follows the Unix philosophy that shaped GNU/Linux: small, focused tools that do one thing well. Like grep, awk, and sed before it, Perl was designed for text processing and system administration - the same tasks this tool performs.

Classic sysadmin tools have always been scripts:

• autoconf, automake - Perl and shell
• git-send-email - Perl
• debhelper - Perl
• Countless system utilities in /usr/bin - Perl, shell, awk

This isn't legacy - it's proven engineering. These tools have managed millions of servers for decades. Perl is part of the GNU/Linux ecosystem in a way that newer languages simply aren't.

Why this matters today

In 2026, installing a simple CLI tool often means:

• Python: create venv, pip install dependencies, hope nothing conflicts with system Python
• Node: npm install, node_modules bloat, version conflicts
• Rust/Go: compile step, or trust pre-built binaries

With Perl:

chmod +x sqltool
./sqltool add myproject

That's it. Works on a fresh Debian install. Works on a minimal Alpine container. Works on your colleague's Fedora laptop. No pyproject.toml, no package.json, no build artifacts.

For a CLI tool that manages system processes and files, Perl hits the sweet spot between shell scripts (too limited for complex logic) and heavier languages (unnecessary complexity for this use case).

Default Credentials

Each instance creates:

• Database: <project>
• User: <project>
• Password: admin1234
• Port: 3307 (increments for each new instance)

Security Note

The default password admin1234 is meant for local development only. These instances bind to 127.0.0.1 by default and are not accessible from the network.

If you need to change the password or create additional users, connect as root:

mysql -u root -S ~/sql/myproject/data/mysql.sock

Then run:

ALTER USER 'myproject'@'localhost' IDENTIFIED BY 'your_secure_password';
FLUSH PRIVILEGES;

Never expose these instances to the network without proper security configuration.

License

LGPL-2.1 - See source file for details.

Author

Luciano Federico Pereira lucianopereira@posteo.es