NAME

sqltool - Local MySQL/MariaDB instance manager for development

VERSION

Version 1.0.0

SYNOPSIS

sqltool add <project>              # Create new database instance
sqltool remove <project>           # Delete instance and data
sqltool start <project>            # Start instance
sqltool stop <project>             # Stop instance
sqltool list                       # List all instances
sqltool info <project>             # Show instance details
sqltool port <project>             # Show port number
sqltool logs <project>             # Show recent logs
sqltool backup <project>           # Backup database
sqltool restore <project> <file>   # Restore from backup
sqltool clone <src> <dst>          # Clone instance
sqltool status <project>           # Quick status check
sqltool debug                      # Show detected binaries
sqltool help                       # Show help

DESCRIPTION

sqltool is a local MySQL/MariaDB instance manager for development environments. It provides a simple, containerless approach to managing isolated database instances on a single developer's machine.

Each project gets its own:

• Data directory

• Socket file

• Port number

• Log files

• Configuration

No root access, systemd, or containers required. Instances run as your user.

COMMANDS

add project

Creates a new database instance. Initializes the data directory, creates a database and user with the project name, and sets up start/stop scripts.

remove project

Deletes an instance and all its data. Prompts for confirmation.

start project

Starts the database instance in the background.

stop project

Stops the running database instance.

list

Lists all instances with their port numbers and status.

info project

Shows detailed information about an instance including paths, credentials, and data size.

port project

Outputs just the port number (useful for scripts).

logs project

Shows the last 100 lines of the error log.

backup project

Creates a timestamped SQL backup in ~/sql/backups/.

restore project file.sql

Restores a backup file into the project database.

clone source destination

Creates a new instance that's a copy of an existing one.

status project

Quick status check showing if instance is running.

debug

Shows detected MySQL/MariaDB binaries and paths.

help

Shows the help message.

DIRECTORY STRUCTURE

All data is stored under ~/sql/:

~/sql/
├── <project>/
│   ├── data/           # MySQL data files
│   │   └── mysql.sock  # Socket file
│   ├── etc/
│   │   └── my.cnf      # Configuration
│   ├── logs/
│   │   └── error.log   # Error log
│   └── scripts/
│       ├── start       # Start script
│       └── stop        # Stop script
├── backups/            # SQL backups
└── bin/                # Reserved for future use

DEFAULT CREDENTIALS

• Database name: project name

• Username: project name

• Password: admin1234

• Port: Starting from 3307, incremented per instance

REQUIREMENTS

• Perl 5.10 or later

• MySQL 5.7+ or MariaDB 10.x/11.x

If MySQL/MariaDB is not installed, sqltool will offer to install it automatically on supported systems (Debian, Ubuntu, Fedora, Arch, macOS, etc.).

EXAMPLES

Create and start a new instance:

sqltool add myapp
sqltool start myapp

Connect to it:

mysql -u myapp -p -S ~/sql/myapp/data/mysql.sock

Or via TCP:

mysql -u myapp -p -h 127.0.0.1 -P $(sqltool port myapp)

Backup and restore:

sqltool backup myapp
sqltool restore myapp ~/sql/backups/myapp-20240115-120000.sql

Clone for testing:

sqltool clone production test_copy

AUTHOR

Luciano Federico Pereira <lucianopereira@posteo.es>

COPYRIGHT AND LICENSE

Copyright (C) 2026 Luciano Federico Pereira

This program is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

SEE ALSO

mysql(1), mysqld(1), mariadbd(1)

cpanm sqltool

perl -MCPAN -e shell
install sqltool