pytorchia-codecron-mysql-backup

Zero-downtime, sequential MySQL / MariaDB dumps with cron scheduling,
disk-space self-healing, retention policy & SMTP alerts – ready for Node 18 +

---

✨ Features

✓	Description
Sequential multi-DB dumps	Never run two mysqldump at once – next DB starts only when the previous one is OK.
Pluggable cron (node-cron)	Any cron expression ('* * * * *' etc.).
Smart retention	Keep N newest dumps per DB.
Automatic low-disk pruning	Ensures at least 10 % free space (uses native fs.statfs or check-disk-space fallback).
SMTP pool with Nodemailer	One TLS connection reused for every notification.
Success / failure e-mails	Optional OK/KO messages, configurable frequency.
Pure options API	No dotenv dependency – bring your own config loader.
ESM + CommonJS	import { scheduleBackups } or const { scheduleBackups } = require(...).
TypeScript ready	Inline JSDoc types – no external @types/* needed.

---

🛠️ Installation

npm  i  pytorchia-codecron-mysql-backup
# or
yarn add pytorchia-codecron-mysql-backup

---

🚀 Quick start

import { scheduleBackups } from 'pytorchia-codecron-mysql-backup';

scheduleBackups({
  // ➊ What to dump
  databases: ['shop', 'analytics'],

  // ➋ When
  cron: '0 * * * *',               // every hour at minute 0

  // ➌ MySQL / MariaDB credentials
  mysql: { host: 'db', user: 'root', password: 'secret' },

  // ➍ Where to store
  directoryRoot: './dumps',

  // ➎ Retention
  maxBackups: 24 * 7,              // keep one week of hourly dumps

  // ➏ Notifications (optional)
  smtp: {
    host: 'smtp.sendgrid.net',
    port: 465,
    secure: true,
    auth: { user: 'apikey', pass: process.env.SENDGRID_KEY }
  },
  notifyTo: '[e-mail]',
  successEvery: 12                 // send an OK mail every 12 dumps
});

The first dump starts immediately, then repeats according to the cron expression. If a dump fails:

• remaining DBs will not run for that cycle;
• a single failure e-mail is sent (if SMTP is configured).

---

🧩 Full option reference

Key	Type / Default	Description
databases	string[] (required)	List of DB names to dump in order.
cron	string – '0 * * * *'	Standard cron 5-field expression.
mysql	{ host, user, password } required	Shared connection params; the lib appends database.
directoryRoot	./dumps	Root folder; one sub-folder per DB.
maxBackups	168	Max files per DB (e.g. 24 * 7).
smtp	see example	SMTP pool options (host, port, secure, auth).
notifyTo	string | string[]	Recipient(s).
successEvery	number – 24	Send OK mail every N successful dumps (0 = never).
diskFreeRatio	0.10	Minimum free space fraction before pruning.

---

🛡️ Security tips

• Create a dedicated DB user with LOCK TABLES, SELECT only.
• Store SMTP credentials in a secrets manager / CI variable, not in code.
• Consider using GPG or client-side encryption for the .sql files.

---

🤝 Contributing

1. git clone https://github.com/fgirolami29/codecron-mysql-backup.git
2. npm i
3. npm run lint && npm test
4. PRs & issues welcome!

---

📜 License

MIT © PyTorchia™ Community See LICENSE for details.