luciano (orginal) [2026-05-22T21:55:29+02:00] view original

sqltool

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

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

MariaDB or MySQL (auto-installed if missing)

Perl version: Perl 5 (pre-installed on most systems)

Nim version: Nim 1.6+ (to build from source)

Installation

Build from source (Nim)

Requires Nim 1.6 or later.


git clone https://github.com/lucianofedericopereira/sqltool.git
cd sqltool
make build         # native binary
make strip         # strip debug symbols (~172KB)
sudo make install  # install to /usr/local/bin

Or directly with the Nim compiler:


nim c -d:release --opt:size nsqltool.nim

Cross-compilation targets

Target	Command	Requirement
Linux x86_64 (static)	`make linux-static`	`musl-tools`
Linux ARM64	`make linux-arm64`	`gcc-aarch64-linux-gnu`
macOS ARM64	`make macos-arm64`	compile on macOS
macOS x86_64	`make macos-x86`	compile on macOS

Perl version (no build step)


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

macOS (Homebrew)


brew tap lucianofedericopereira/sqltool
brew install sqltool

Quick Demo

Run the included demo script to see sqltool in action:


./tryme.sh

This will:

Create a test instance called demo

Start it

Create a sample table with data

Make a backup

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).

Why Nim?

sqltool also ships as a compiled Nim binary (~172KB stripped, no runtime dependencies). Nim is the right choice when you want a single distributable file that works without any interpreter on the target machine.

Single binary - copy and run, no Perl required on the target

Same platforms - Linux x86_64/ARM64, macOS ARM64/x86_64

Identical behavior - same commands, same directory layout, same output

Cross-compilation - build a Linux ARM64 binary from your x86 laptop

Nim for Perl developers

If you know Perl, Nim will feel familiar in structure but different in discipline. Here's a quick reference:

Variables and types


# Perl - dynamic, implicit types
my $name = "myproject";
my $port = 3307;
my @dirs = ("/usr/bin", "/usr/local/bin");
my %cmds = (add => \&cmd_add, list => \&cmd_list);


# Nim - static types, inferred by compiler
let name = "myproject"
var port = 3307
var dirs = @["/usr/bin", "/usr/local/bin"]
var cmds = {"add": cmdAdd, "list": cmdList}.toTable()

String operations


my $path = $dir . "/" . $name;        # concatenation
my $lower = lc($str);                 # lowercase
$str =~ s/"//g;                       # regex replace
my @parts = split(/=/, $line, 2);     # split


let path = dir / name                 # os path join
let lower = str.toLowerAscii()        # lowercase
let clean = str.replace("\"", "")    # string replace
let parts = line.split("=", 2)        # split

String interpolation


print "Project: $project\n";
print "Port:    $port\n";

# heredoc
my $cfg = <<"EOF";
datadir=$dir/data
port=$port
EOF


echo "Project: " & project
echo "Port:    " & $port

# fmt strings (import strformat)
let cfg = fmt"""
datadir={dir}/data
port={port}
"""

File and directory operations


use File::Path qw(make_path remove_tree);
make_path("$dir/data");               # mkdir -p
remove_tree("$BASE/$project");        # rm -rf
-d $path                              # is directory?
-f $path                              # file exists?
-x $path                              # is executable?
-S $path                              # is socket?
open my $fh, '<', $file or die $!;
while (<$fh>) { ... }
close $fh;


import os, posix
createDir(dir / "data")               # mkdir -p
removeDir(BASE / project)             # rm -rf
dirExists(path)                       # is directory?
fileExists(path)                      # file exists?
fileExists(path)                      # (check permissions separately)
isSocket(path)                        # is socket? (via posix.stat)
for line in lines(file):              # read lines
  discard

Running external commands


system("mysqld --defaults-file=$cfg");     # run, wait
system("mysqld --defaults-file=$cfg &");   # run in background
my $out = `mysqld --version 2>/dev/null`;  # capture output
open my $pipe, "|-", "mysql -u root";      # pipe to process
print $pipe $sql;
close $pipe;


import osproc
discard execCmd("mysqld --defaults-file=" & cfg)      # run, wait
discard execCmd("mysqld --defaults-file=" & cfg & " &") # background
let (out, _) = execCmdEx("mysqld --version 2>/dev/null") # capture
let p = startProcess("mysql -u root",                 # pipe to process
                     options={poUsePath, poEvalCommand})
p.inputStream.write(sql)
p.inputStream.close()
discard p.waitForExit()
p.close()

Subroutines / procs


sub find_binary {
    my (@names) = @_;
    for my $name (@names) {
        return $name if -x "/usr/bin/$name";
    }
    return "";
}


proc findBinary(names: seq[string]): string =
  for name in names:
    if fileExists("/usr/bin/" & name):
      return name
  ""

Error handling


die "Project '$project' already exists.\n" if project_exists($project);
open my $fh, '>', $file or die $!;


if projectExists(project):
  quit("Project '" & project & "' already exists.\n", 1)
writeFile(file, content)   # raises IOError on failure

OS/platform detection


if ($^O eq 'darwin') { ... }   # runtime


when defined(macosx): ...      # compile-time (when, not if)

The biggest shift from Perl to Nim is that Nim resolves platform differences at compile time with when, whereas Perl checks $^O at runtime. Everything else maps closely: procs instead of subs, seq[string] instead of arrays, table instead of hashes, and fmt instead of heredoc interpolation.

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>

Mirror of forum.nim-lang.org

13940 :: nSQLtool: Local MySQL/MariaDB instance manager for development.