# Database Backup Tool
A command-line tool for backing up MySQL databases to local storage or AWS S3.
## Quick start
1. Install
```bash
pip install database-backup
```
1. See options
```bash
db-backup --help
```
1. Create/edit config
```bash
# Interactive init
db-backup --init
# or edit the file manually afterward
nano ~/.config/database-backup/.env
```
1. Run
```bash
db-backup --local # store on filesystem
db-backup --s3 # store on S3
```
## Features
- Back up all MySQL databases, excluding system databases.
- Store backups in a local directory or an AWS S3 bucket.
- Create a separate folder for each database.
- Timestamped backups for easy identification.
- Automatic cleanup of old backups based on a retention policy.
- Configuration via a `.env` file.
- Command-line interface for easy operation.
- Cron setup for automatic backups.
## Requirements
- Python 3.10+
- `mysql-connector-python`
- `boto3`
- `python-dotenv`
- `click`
- MySQL client tools (provides `mysqldump`)
On macOS (Homebrew):
```bash
brew install mysql-client
# Typical binary path: /opt/homebrew/opt/mysql-client/bin/mysqldump (Apple Silicon)
```
## Installation
From PyPI (recommended):
```bash
pip install database-backup
```
From source (optional):
```bash
git clone https://github.com/magicstack-llp/db-backup.git
cd db-backup
pip install -r requirements.txt
```
## Configuration
By default, the CLI loads config from:
- macOS/Linux: `~/.config/database-backup/.env` (or `${XDG_CONFIG_HOME}/database-backup/.env`)
Override with `--config` or `DATABASE_BACKUP_CONFIG` env.
Example `.env`:
```env
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=password
BACKUP_DIR=/Users/<USER>/backups/databases
## CLI usage
S3_BUCKET=mybucket
S3_PATH=backups
AWS_ACCESS_KEY_ID=XXXXXXX
AWS_SECRET_ACCESS_KEY=YYYYYYY
RETENTION_COUNT=5
MYSQLDUMP_PATH=/opt/homebrew/opt/mysql-client/bin/mysqldump
BACKUP_DRIVER=local # local, s3
EXCLUDED_DATABASES=db_1,db_2
```
After installation as a package, use the short command:
```bash
db-backup --local
# or
database-backup --s3
```
Options:
- `--compress/--no-compress` (default: `--compress`): gzip the dump and keep `.gz`.
- `--mysqldump PATH`: override mysqldump path.
- `--config FILE`: override config file path.
- `--init`: interactively create/update the config file and exit.
You can still run the module directly:
```bash
python -m db_backup --local
```
### Cron setup
You can set up cron jobs interactively:
```bash
db-backup --cron
```
- You can enter either:
- A full cron expression (5 fields), e.g. `0 3,15 * * *`
- Or a comma-separated list of 24h times, e.g. `03:00,15:00`
- Default schedule: `0 3,15 * * *` (daily at 03:00 and 15:00)
- You can choose to force `--local`, `--s3`, or use whatever `BACKUP_DRIVER` is in your `.env` by selecting `config`.
- The CLI writes a managed block to your user crontab between `# BEGIN db-backup (managed)` and `# END db-backup (managed)`.
- It will pass `--config ~/.config/database-backup/.env` by default (or whatever you provide with `--config`).
Helpful: You can use a cron expression generator like [it-tools crontab generator](https://it-tools.tech/crontab-generator) to craft schedules.
You can also initialize your config first:
```bash
db-backup --init
```
## Usage
Preferred: run as a module from the project root (this works reliably regardless of relative imports):
```bash
python -m db_backup --config .env --local
```
Or run the script directly (works after the import fallback fix):
```bash
python db_backup/main.py --config .env --local
```
You can override `mysqldump` path via CLI:
```bash
python -m db_backup --config .env --local --mysqldump /opt/homebrew/opt/mysql-client/bin/mysqldump
```
To store your backups in an S3 bucket:
```bash
python -m db_backup --config .env --s3
```
You can also override the retention count and backup directory using the command-line options:
```bash
python -m db_backup --config .env --retention 10 --local --backup-dir /path/to/backups
```
## Architecture
The database backup tool is built using a Clean Architecture approach, which separates the code into four layers:
- Domain: Contains the core business logic and entities of the application.
- Data: Contains the data access layer, which is responsible for interacting with the database and storage.
- App: Contains the application logic, which orchestrates the backup process.
- Interface: Contains the user interface, which is responsible for handling user input and displaying output.
This separation of concerns makes the application more modular, testable, and maintainable.
## Environment variables reference
All configuration is read from your .env file unless overridden by CLI flags. Defaults are shown where applicable.
- MYSQL_HOST: MySQL server host.
- Example: 127.0.0.1
- MYSQL_PORT: MySQL port. Default: 3306
- Example: 3306
- MYSQL_USER: MySQL username with privileges to dump all databases.
- Example: root
- MYSQL_PASSWORD: Password for MYSQL_USER.
- Example: changeme
- BACKUP_DRIVER: Where to store backups. One of: local, s3
- Example: local
- Note: You can also pass --local or --s3 on the CLI.
- BACKUP_DIR: Base directory for local backups (used when BACKUP_DRIVER=local or with --local).
- Example: /Users/alex/backups/databases
- S3_BUCKET: S3 bucket name (used when BACKUP_DRIVER=s3 or with --s3).
- Example: my-bucket
- S3_PATH: Prefix/path inside the bucket to store backups (folders are created per database).
- Example: backups
- AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY: AWS credentials to access the bucket.
- Example: AWS_ACCESS_KEY_ID=AKIA... / AWS_SECRET_ACCESS_KEY=...
- Tip: If using instance/profile or environment credentials, these can be left empty; boto3 will try the default credential chain.
- RETENTION_COUNT: Number of most recent backups to keep per database. Older ones are removed automatically.
- Default: 5
- Example: 10
- MYSQLDUMP_PATH: Full path or command name to mysqldump. If not set, the tool tries to resolve mysqldump from PATH.
- Example (macOS/Homebrew on Apple Silicon): /opt/homebrew/opt/mysql-client/bin/mysqldump
- EXCLUDED_DATABASES: Comma-separated list of additional databases to skip. System DBs are always excluded: mysql, information_schema, performance_schema, sys.
- Example: db_1,db_2
- DATABASE_BACKUP_CONFIG: Optional env var to point the CLI to a different .env file.
- Example: /etc/database-backup/.env
## Examples
- Local backup with custom mysqldump and retention:
```bash
db-backup --local --mysqldump /opt/homebrew/opt/mysql-client/bin/mysqldump --retention 10
```
- S3 backup using settings from .env:
```bash
db-backup --s3
```
## Contributing
Contributions are welcome! Please feel free to submit a pull request or open an issue if you have any suggestions or feedback.
## License
This project is licensed under the MIT License.
Raw data
{
"_id": null,
"home_page": null,
"name": "database-backup",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "backup, database, mysql, mysqldump, s3, cli, aws",
"author": "Kuldip Satpute",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/6c/30/9f355a10d4837511187ca18434bc7279e98643db6ebcef3193dc461b43cf/database_backup-0.1.12.tar.gz",
"platform": null,
"description": "# Database Backup Tool\n\nA command-line tool for backing up MySQL databases to local storage or AWS S3.\n\n## Quick start\n\n1. Install\n\n```bash\npip install database-backup\n```\n\n1. See options\n\n```bash\ndb-backup --help\n```\n\n1. Create/edit config\n\n```bash\n# Interactive init\ndb-backup --init\n\n# or edit the file manually afterward\nnano ~/.config/database-backup/.env\n```\n\n1. Run\n\n```bash\ndb-backup --local # store on filesystem\ndb-backup --s3 # store on S3\n```\n\n## Features\n\n- Back up all MySQL databases, excluding system databases.\n- Store backups in a local directory or an AWS S3 bucket.\n- Create a separate folder for each database.\n- Timestamped backups for easy identification.\n- Automatic cleanup of old backups based on a retention policy.\n- Configuration via a `.env` file.\n- Command-line interface for easy operation.\n- Cron setup for automatic backups.\n\n## Requirements\n\n- Python 3.10+\n- `mysql-connector-python`\n- `boto3`\n- `python-dotenv`\n- `click`\n- MySQL client tools (provides `mysqldump`)\n\n On macOS (Homebrew):\n\n ```bash\n brew install mysql-client\n # Typical binary path: /opt/homebrew/opt/mysql-client/bin/mysqldump (Apple Silicon)\n ```\n\n## Installation\n\nFrom PyPI (recommended):\n\n```bash\npip install database-backup\n```\n\nFrom source (optional):\n\n```bash\ngit clone https://github.com/magicstack-llp/db-backup.git\ncd db-backup\npip install -r requirements.txt\n```\n\n## Configuration\n\nBy default, the CLI loads config from:\n\n- macOS/Linux: `~/.config/database-backup/.env` (or `${XDG_CONFIG_HOME}/database-backup/.env`)\n\nOverride with `--config` or `DATABASE_BACKUP_CONFIG` env.\n\nExample `.env`:\n\n```env\nMYSQL_HOST=127.0.0.1\nMYSQL_PORT=3306\nMYSQL_USER=root\nMYSQL_PASSWORD=password\nBACKUP_DIR=/Users/<USER>/backups/databases\n## CLI usage\nS3_BUCKET=mybucket\nS3_PATH=backups\nAWS_ACCESS_KEY_ID=XXXXXXX\nAWS_SECRET_ACCESS_KEY=YYYYYYY\nRETENTION_COUNT=5\nMYSQLDUMP_PATH=/opt/homebrew/opt/mysql-client/bin/mysqldump\nBACKUP_DRIVER=local # local, s3\nEXCLUDED_DATABASES=db_1,db_2\n```\n\nAfter installation as a package, use the short command:\n\n```bash\ndb-backup --local\n# or\ndatabase-backup --s3\n```\n\nOptions:\n\n- `--compress/--no-compress` (default: `--compress`): gzip the dump and keep `.gz`.\n- `--mysqldump PATH`: override mysqldump path.\n- `--config FILE`: override config file path.\n- `--init`: interactively create/update the config file and exit.\n\nYou can still run the module directly:\n\n```bash\npython -m db_backup --local\n```\n\n### Cron setup\n\nYou can set up cron jobs interactively:\n\n```bash\ndb-backup --cron\n```\n\n- You can enter either:\n - A full cron expression (5 fields), e.g. `0 3,15 * * *`\n - Or a comma-separated list of 24h times, e.g. `03:00,15:00`\n- Default schedule: `0 3,15 * * *` (daily at 03:00 and 15:00)\n- You can choose to force `--local`, `--s3`, or use whatever `BACKUP_DRIVER` is in your `.env` by selecting `config`.\n- The CLI writes a managed block to your user crontab between `# BEGIN db-backup (managed)` and `# END db-backup (managed)`.\n- It will pass `--config ~/.config/database-backup/.env` by default (or whatever you provide with `--config`).\n\nHelpful: You can use a cron expression generator like [it-tools crontab generator](https://it-tools.tech/crontab-generator) to craft schedules.\n\nYou can also initialize your config first:\n\n```bash\ndb-backup --init\n```\n\n## Usage\n\nPreferred: run as a module from the project root (this works reliably regardless of relative imports):\n\n```bash\npython -m db_backup --config .env --local\n```\n\nOr run the script directly (works after the import fallback fix):\n\n```bash\npython db_backup/main.py --config .env --local\n```\n\nYou can override `mysqldump` path via CLI:\n\n```bash\npython -m db_backup --config .env --local --mysqldump /opt/homebrew/opt/mysql-client/bin/mysqldump\n```\n\nTo store your backups in an S3 bucket:\n\n```bash\npython -m db_backup --config .env --s3\n```\n\nYou can also override the retention count and backup directory using the command-line options:\n\n```bash\npython -m db_backup --config .env --retention 10 --local --backup-dir /path/to/backups\n```\n\n## Architecture\n\nThe database backup tool is built using a Clean Architecture approach, which separates the code into four layers:\n\n- Domain: Contains the core business logic and entities of the application.\n- Data: Contains the data access layer, which is responsible for interacting with the database and storage.\n- App: Contains the application logic, which orchestrates the backup process.\n- Interface: Contains the user interface, which is responsible for handling user input and displaying output.\n\nThis separation of concerns makes the application more modular, testable, and maintainable.\n\n## Environment variables reference\n\nAll configuration is read from your .env file unless overridden by CLI flags. Defaults are shown where applicable.\n\n- MYSQL_HOST: MySQL server host.\n - Example: 127.0.0.1\n- MYSQL_PORT: MySQL port. Default: 3306\n - Example: 3306\n- MYSQL_USER: MySQL username with privileges to dump all databases.\n - Example: root\n- MYSQL_PASSWORD: Password for MYSQL_USER.\n - Example: changeme\n- BACKUP_DRIVER: Where to store backups. One of: local, s3\n - Example: local\n - Note: You can also pass --local or --s3 on the CLI.\n- BACKUP_DIR: Base directory for local backups (used when BACKUP_DRIVER=local or with --local).\n - Example: /Users/alex/backups/databases\n- S3_BUCKET: S3 bucket name (used when BACKUP_DRIVER=s3 or with --s3).\n - Example: my-bucket\n- S3_PATH: Prefix/path inside the bucket to store backups (folders are created per database).\n - Example: backups\n- AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY: AWS credentials to access the bucket.\n - Example: AWS_ACCESS_KEY_ID=AKIA... / AWS_SECRET_ACCESS_KEY=...\n - Tip: If using instance/profile or environment credentials, these can be left empty; boto3 will try the default credential chain.\n- RETENTION_COUNT: Number of most recent backups to keep per database. Older ones are removed automatically.\n - Default: 5\n - Example: 10\n- MYSQLDUMP_PATH: Full path or command name to mysqldump. If not set, the tool tries to resolve mysqldump from PATH.\n - Example (macOS/Homebrew on Apple Silicon): /opt/homebrew/opt/mysql-client/bin/mysqldump\n- EXCLUDED_DATABASES: Comma-separated list of additional databases to skip. System DBs are always excluded: mysql, information_schema, performance_schema, sys.\n - Example: db_1,db_2\n- DATABASE_BACKUP_CONFIG: Optional env var to point the CLI to a different .env file.\n - Example: /etc/database-backup/.env\n\n## Examples\n\n- Local backup with custom mysqldump and retention:\n\n```bash\ndb-backup --local --mysqldump /opt/homebrew/opt/mysql-client/bin/mysqldump --retention 10\n```\n\n- S3 backup using settings from .env:\n\n```bash\ndb-backup --s3\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a pull request or open an issue if you have any suggestions or feedback.\n\n## License\n\nThis project is licensed under the MIT License.\n",
"bugtrack_url": null,
"license": null,
"summary": "A CLI tool for backing up databases to cloud storage.",
"version": "0.1.12",
"project_urls": {
"Homepage": "https://github.com/magicstack-llp/db-backup",
"Issues": "https://github.com/magicstack-llp/db-backup/issues",
"Repository": "https://github.com/magicstack-llp/db-backup"
},
"split_keywords": [
"backup",
" database",
" mysql",
" mysqldump",
" s3",
" cli",
" aws"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0a1172db1c26ec23499112fbc9ebf9201cd83e7abdbb534f4efa6e93302b7fdb",
"md5": "3ac9ed9d1ea097d4fd3cfe7e56462ccf",
"sha256": "2db6e532a62a39aa51a9f428188725fd1e795f3a85e5bff9ceb914dc169e49ce"
},
"downloads": -1,
"filename": "database_backup-0.1.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3ac9ed9d1ea097d4fd3cfe7e56462ccf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 14189,
"upload_time": "2025-09-11T10:21:03",
"upload_time_iso_8601": "2025-09-11T10:21:03.700546Z",
"url": "https://files.pythonhosted.org/packages/0a/11/72db1c26ec23499112fbc9ebf9201cd83e7abdbb534f4efa6e93302b7fdb/database_backup-0.1.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6c309f355a10d4837511187ca18434bc7279e98643db6ebcef3193dc461b43cf",
"md5": "20fac62a72c9679e25a3a62ef47deb80",
"sha256": "d370893831c15d83c051f5917e5520c9b6b86e4b6599476c6908ba52b67decd2"
},
"downloads": -1,
"filename": "database_backup-0.1.12.tar.gz",
"has_sig": false,
"md5_digest": "20fac62a72c9679e25a3a62ef47deb80",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 12142,
"upload_time": "2025-09-11T10:21:05",
"upload_time_iso_8601": "2025-09-11T10:21:05.620486Z",
"url": "https://files.pythonhosted.org/packages/6c/30/9f355a10d4837511187ca18434bc7279e98643db6ebcef3193dc461b43cf/database_backup-0.1.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-11 10:21:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "magicstack-llp",
"github_project": "db-backup",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "python-dotenv",
"specs": []
},
{
"name": "mysql-connector-python",
"specs": []
},
{
"name": "boto3",
"specs": []
},
{
"name": "click",
"specs": []
}
],
"lcname": "database-backup"
}
JSON
