Database Backup

Flow ID: SY-08 | Module(s): job | Complexity: Low

Business Overview

Database backup management provides automated MySQL dump creation and retention cleanup. Two jobs form a lifecycle pair: AdvBackUpDataBase creates timestamped database dumps (gzip or raw SQL) with support for Docker-containerized MySQL, while AdvCleanBackUps removes backups older than a configurable retention period. Together they ensure disaster recovery capability without unbounded disk consumption.

Architecture

AdvBackUpDataBase (job)           AdvCleanBackUps (job)
       |                                |
       v                                v
Dbutils_model::backupDatabase()   Dbutils_model::cleanBackups()
       |                                |
       v                                v
  Build mysqldump command          scandir() backup path
  (optional Docker exec prefix)    Parse timestamps from filenames
       |                                |
       v                                v
  system() shell execution         Delete files older than
  Output: {db}-{timestamp}.gz/.sql   backup_max_days

Key Components

Component	Path	Role
AdvBackUpDataBase	ecommercen/job/libraries/AdvBackUpDataBase.php	Job: triggers database backup
AdvCleanBackUps	ecommercen/job/libraries/AdvCleanBackUps.php	Job: removes expired backups
Dbutils_model	application/models/Dbutils_model.php	Model: backup creation and cleanup logic
Config	application/config/dbutils.php	Backup output format, retention, paths, table exclusions
Client stubs	application/modules/job/libraries/BackUpDataBase.php, CleanBackUps.php	Empty extension points

Code Flow

AdvBackUpDataBase

1. Entry: Constructor loads dbutils config and dbutils_model.
2. Path resolution: getBackupPath() computes the backup directory as two levels above FCPATH (the web root). For example, if FCPATH is /var/www/html/public/, backups go to /var/www/.
3. Table exclusion: Reads ignore_tables config array; builds --ignore-table={db}.{table} flags for each.
4. Command assembly:
   • Base: mysqldump -u {username} [-p"{password}"] {ignore_flags} {database}
   • Optional Docker prefix: docker exec -i {container_name} prepended when mysql_docker_container_name is configured.
   • Custom path prefix: mysqldump_path config prepended to the command.
5. Output piping (based on backup_output config):
   • 'gzip': pipes through | gzip > with .gz extension.
   • 'sql' (default): direct redirect > with .sql extension.
6. Filename format: {database_name}-{Y-m-d-H-i-s}.{gz|sql}
7. Execution: system($dumpCommand) runs the assembled shell command.

AdvCleanBackUps

1. Entry: Constructor loads dbutils config and dbutils_model.
2. Retention calculation: Reads backup_max_days config, subtracts that many days from current date.
3. File extension: Determined by backup_output config (.gz for gzip, .sql otherwise).
4. Directory scan: scandir() on the backup path.
5. Filename parsing: For each file, extracts the timestamp portion by stripping the database name prefix and file extension. Parses with DateTime::createFromFormat('Y-m-d-H-i-s', ...).
6. Deletion: If the parsed date is older than the retention threshold, deletes with @unlink() (error-suppressed).

Data Model

No database tables are used for tracking backups. Backup files are stored on the filesystem with their timestamp embedded in the filename.

Backup File Naming Convention

{database_name}-{YYYY}-{MM}-{DD}-{HH}-{mm}-{ss}.{gz|sql}

Example: adveshop_production-2026-04-04-03-00-00.gz

Configuration

Config File: application/config/dbutils.php

Key	Default	Dev Override	Description
mysqldump_path	env('APP_MYSQL_PATH')	--	Path prefix for mysqldump binary
backup_output	'gzip'	'sql'	Output format: gzip or sql
backup_max_days	15	7	Retention period in days
mysql_docker_container_name	env(...), false	--	Docker container name for mysqldump; false to run locally
ignore_tables	['softone_view', 'softone_view_products', 'shop_prices_view']	--	Tables excluded from dump
no_sessions_ignore_tables	Above + ['ci_sessions']	--	Extended exclusion list (available but not used by default)

Environment Variables

Variable	Description
APP_MYSQL_PATH	Path to mysqldump binary (empty for system PATH)
APP_MYSQL_DOCKER_CONTAINER_NAME	Docker container name for MySQL; false for local
ENVIRONMENT	Switches config between development and testing profiles

Job Options

Both AdvBackUpDataBase and AdvCleanBackUps accept no options.

Client Extension Points

• Job override: Create BackUpDataBase or CleanBackUps in application/modules/job/libraries/ extending the Adv* base class to add pre/post backup hooks, custom paths, or notification logic.
• Table exclusion: Modify ignore_tables array in application/config/dbutils.php to exclude client-specific large or transient tables.
• Docker support: Set APP_MYSQL_DOCKER_CONTAINER_NAME in .env when MySQL runs in a Docker container alongside the application.

Business Rules

1. Backup location: Files are written two directory levels above FCPATH, outside the web root for security.
2. Gzip by default: Production uses gzip compression; development uses raw SQL for easier inspection.
3. Retention period: Default 15 days in production, 7 days in development. Cleanup relies on filename timestamp parsing, not filesystem metadata.
4. Docker awareness: When mysql_docker_container_name is set, the dump command is wrapped in docker exec -i to access the containerized MySQL server.
5. Table exclusion: ERP view tables (softone_view, softone_view_products, shop_prices_view) are always excluded as they are regenerated from the ERP system.
6. No password handling: If the database user has no password, the -p flag is omitted entirely.
7. Error handling: The system() call provides no error handling; failures are silent at the application level but may produce shell output.

Related Flows

• SY-01 Cron Framework -- Job registration and scheduling infrastructure
• AD-13 Settings -- Admin panel settings where backup configuration may be managed