Download the PHP package amitdugar/db-tools without Composer

db-tools

MySQL/MariaDB backup, restore, and recovery toolkit.

Installation

Quick Start

Setup

If your project already has a .env file (Laravel, Symfony, etc.)

You're done! db-tools automatically reads DB_* variables from your .env file.

If your .env doesn't have database variables yet, run setup:

This will prompt for credentials and add them to your .env file.

If you're starting fresh

Choose where to save config:

• .env file (recommended) - adds DB_HOST, DB_DATABASE, etc.
• Profile file - saves to ~/.config/db-tools/profiles.php

Verify your setup

Commands

Backup & Restore

Backup Management

Database Maintenance

Point-in-Time Recovery

Configuration

Profiles (Multiple Databases)

If you manage multiple databases, use profiles. Each profile is a named database configuration that you can switch between.

When to use profiles

• You have separate databases (e.g., main app + analytics)
• You need different backup settings per database
• You want to manage multiple projects from one machine

Quick setup with profiles

Using profiles

How profiles are stored

In .env file (default) - profiles use prefixed variable names:

In db-tools.php - profiles are array keys:

Cron Jobs

db-tools is designed for cron. Just cd to your project and run:

No environment setup needed in cron - db-tools reads directly from your project's .env file.

Non-Interactive Setup

For deploy scripts and CI/CD pipelines, use --no-prompt mode:

Config Files

Most projects don't need a config file - db-tools reads your .env automatically. Use config files when you need:

• Multiple databases or profiles
• Custom output_dir, retention, or other options
• Non-standard environment variable names

db-tools.php (commit to repo)

db-tools.local.php (gitignore, local overrides)

Configuration Reference

Auto-detected environment variables

db-tools automatically reads these from your .env file:

Config file locations (first found wins)

1. DBTOOLS_CONFIG env var
2. db-tools.local.php (project root)
3. db-tools.php (project root)
4. ~/.config/db-tools/profiles.php

Profile options

Command-line overrides

Any option can be overridden via CLI or environment:

MySQL and MariaDB

Both are supported. Two things adapt automatically:

Client binaries. MariaDB 11.0 renamed its client tools (mysql → mariadb, mysqldump → mariadb-dump, and so on) and deprecated the old mysql* symlinks. db-tools looks for the classic name first and falls back to the MariaDB name, so it works on either install without configuration. Override any of them if your tools live somewhere unusual:

Server flavour. db:test reports which server it reached, and the collation command picks its default collation accordingly — see Collation Conversion.

Note: a MySQL 8.4 client cannot authenticate against a MariaDB server at all (they no longer share an auth plugin). Use the MariaDB client for MariaDB servers; the fallback above picks it up automatically when it is installed.

Host option files

When you configure a password, db-tools passes --no-defaults to the client tools so that ~/.my.cnf and /etc/my.cnf cannot override the credentials you gave it.

Without it, a password in an option file silently wins. MySQL ranks option files above environment variables, and MYSQL_PWD is where a password belongs because it stays out of ps. The connection is then attempted with the user you configured and a password you did not, and it is refused.

Configure no password and nothing changes. Option files are still read, which is what socket authentication and operator-maintained ~/.my.cnf setups depend on.

--no-defaults also drops non-credential tuning such as max_allowed_packet and default-character-set. If your option file carries settings you need:

That reads option files as before, credentials included, so use it only where the option file is the intended source.

Encrypted Backups

All compression backends support encryption using GPG with AES-256. There are two ways to encrypt:

Auto-generated password (recommended)

Use --encrypt to automatically generate a secure password. The password is derived from your database password plus a random string embedded in the filename:

How it works: The encryption password is DB_PASSWORD + randomString. Since the random string is embedded in the filename, restore automatically derives the correct password when you provide your database credentials.

Manual password

Use --encryption-password to specify your own password:

Store the password securely (e.g., in environment variable):

How encryption works

• ZIP (--compression=zip): Native ZIP encryption (AES-256)
• Other backends (zstd, gzip, pigz): File is compressed, then encrypted with GPG symmetric AES-256 → .sql.zst.gpg

Collation Conversion

The collation command converts database tables and columns to utf8mb4, picking the default collation from the detected server flavour and version:

• MySQL 8+: Uses utf8mb4_0900_ai_ci
• MySQL 5.x: Uses utf8mb4_unicode_ci
• MariaDB (all versions): Uses utf8mb4_unicode_ci

MariaDB is detected from VERSION() rather than inferred from the version number, because MariaDB 10.x and 11.x both compare greater than 8.0 while only MariaDB 11.4+ recognises utf8mb4_0900_ai_ci — on 10.5/10.6/10.11 it fails with ERROR 1273 Unknown collation. MariaDB's own utf8mb4_uca1400_ai_ci (10.10+) is not selected automatically, since adopting it changes sort order; pass --collation utf8mb4_uca1400_ai_ci if you want it.

The command preserves all column attributes: NULL/NOT NULL, DEFAULT values, AUTO_INCREMENT, COMMENT, etc.

Import Formats

The import command handles various file formats:

Requirements

• PHP 8.4+ (tested on 8.4 and 8.5)
• mysqldump, mysql CLI tools
• Compression: zstd (preferred), pigz, or gzip
• Encryption: gpg (for non-ZIP encrypted backups)

License

MIT