diff --git a/README.md b/README.md index 2c9500a..db62ca0 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ It supports a variety of storage options and ensures data security through GPG e ## Use Cases - **Automated Recurring Backups:** Schedule regular backups for MySQL databases. -- **Cross-Environment Migration:** Easily migrate your MySQL databases across different environments using supported storage options. +- **Cross-Environment Migration:** Easily migrate MySQL databases across different environments using `migration` feature. - **Secure Backup Management:** Protect your data with GPG encryption. @@ -65,52 +65,75 @@ Successfully tested on: - SSH remote storage server - FTP remote storage server - Azure Blob storage + ## Quickstart -### Simple backup using Docker CLI +### Simple Backup Using Docker CLI -To run a one time backup, bind your local volume to `/backup` in the container and run the `backup` command: +To perform a one-time backup, bind your local volume to `/backup` in the container and run the `backup` command: ```shell - docker run --rm --network your_network_name \ - -v $PWD/backup:/backup/ \ - -e "DB_HOST=dbhost" \ - -e "DB_PORT=3306" \ - -e "DB_USERNAME=username" \ - -e "DB_PASSWORD=password" \ - jkaninda/mysql-bkup backup -d database_name +docker run --rm --network your_network_name \ + -v $PWD/backup:/backup/ \ + -e "DB_HOST=dbhost" \ + -e "DB_PORT=3306" \ + -e "DB_USERNAME=username" \ + -e "DB_PASSWORD=password" \ + jkaninda/mysql-bkup backup -d database_name ``` -Alternatively, pass a `--env-file` in order to use a full config as described below. - -```yaml - docker run --rm --network your_network_name \ - --env-file your-env-file \ - -v $PWD/backup:/backup/ \ - jkaninda/mysql-bkup backup -d database_name -``` -### Simple restore using Docker CLI - -To restore a database, bind your local volume to `/backup` in the container and run the `restore` command: +Alternatively, use an environment file (`--env-file`) for configuration: ```shell - docker run --rm --network your_network_name \ - -v $PWD/backup:/backup/ \ - -e "DB_HOST=dbhost" \ - -e "DB_PORT=3306" \ - -e "DB_USERNAME=username" \ - -e "DB_PASSWORD=password" \ - jkaninda/mysql-bkup restore -d database_name -f backup_file.sql.gz +docker run --rm --network your_network_name \ + --env-file your-env-file \ + -v $PWD/backup:/backup/ \ + jkaninda/mysql-bkup backup -d database_name ``` -### Simple backup in docker compose file + +### Backup All Databases + +To back up all databases on the server, use the `--all-databases` or `-a` flag. By default, this creates individual backup files for each database. + +```shell +docker run --rm --network your_network_name \ + -v $PWD/backup:/backup/ \ + -e "DB_HOST=dbhost" \ + -e "DB_PORT=3306" \ + -e "DB_USERNAME=username" \ + -e "DB_PASSWORD=password" \ + jkaninda/mysql-bkup backup --all-databases --disable-compression +``` + +> **Note:** Use the `--all-in-one` or `-A` flag to combine backups into a single file. + +--- + +### Simple Restore Using Docker CLI + +To restore a database, bind your local volume to `/backup` and run the `restore` command: + +```shell +docker run --rm --network your_network_name \ + -v $PWD/backup:/backup/ \ + -e "DB_HOST=dbhost" \ + -e "DB_PORT=3306" \ + -e "DB_USERNAME=username" \ + -e "DB_PASSWORD=password" \ + jkaninda/mysql-bkup restore -d database_name -f backup_file.sql.gz +``` + +--- + +### Backup with Docker Compose + +Below is an example of a `docker-compose.yml` file for running a one-time backup: ```yaml services: - mysql-bkup: - # In production, it is advised to lock your image tag to a proper - # release version instead of using `latest`. - # Check https://github.com/jkaninda/mysql-bkup/releases - # for a list of available releases. + pg-bkup: + # In production, pin your image tag to a specific release version instead of `latest`. + # See available releases: https://github.com/jkaninda/mysql-bkup/releases image: jkaninda/mysql-bkup container_name: mysql-bkup command: backup @@ -123,29 +146,39 @@ services: - DB_USERNAME=bar - DB_PASSWORD=password - TZ=Europe/Paris - # mysql-bkup container must be connected to the same network with your database networks: - web + networks: web: ``` -### Docker recurring backup + +--- + +### Recurring Backups with Docker + +You can schedule recurring backups using the `--cron-expression` or `-e` flag: ```shell - docker run --rm --network network_name \ - -v $PWD/backup:/backup/ \ - -e "DB_HOST=hostname" \ - -e "DB_USERNAME=user" \ - -e "DB_PASSWORD=password" \ - jkaninda/mysql-bkup backup -d dbName --cron-expression "@every 15m" #@midnight +docker run --rm --network network_name \ + -v $PWD/backup:/backup/ \ + -e "DB_HOST=hostname" \ + -e "DB_USERNAME=user" \ + -e "DB_PASSWORD=password" \ + jkaninda/mysql-bkup backup -d dbName --cron-expression "@every 15m" ``` -See: https://jkaninda.github.io/mysql-bkup/reference/#predefined-schedules + +For predefined schedules, refer to the [documentation](https://jkaninda.github.io/mysql-bkup/reference/#predefined-schedules). + +--- ## Deploy on Kubernetes -For Kubernetes, you don't need to run it in scheduled mode. You can deploy it as Job or CronJob. +For Kubernetes, you can deploy `mysql-bkup` as a Job or CronJob. Below are examples for both. -### Simple Kubernetes backup Job : +### Kubernetes Backup Job + +This example defines a one-time backup job: ```yaml apiVersion: batch/v1 @@ -158,10 +191,8 @@ spec: spec: containers: - name: mysql-bkup - # In production, it is advised to lock your image tag to a proper - # release version instead of using `latest`. - # Check https://github.com/jkaninda/mysql-bkup/releases - # for a list of available releases. + # Pin the image tag to a specific release version in production. + # See available releases: https://github.com/jkaninda/mysql-bkup/releases image: jkaninda/mysql-bkup command: - /bin/sh @@ -184,10 +215,52 @@ spec: volumes: - name: backup hostPath: - path: /home/toto/backup # directory location on host - type: Directory # this field is optional + path: /home/toto/backup # Directory location on the host + type: Directory # Optional field restartPolicy: Never ``` + +### Kubernetes CronJob for Scheduled Backups + +For scheduled backups, use a `CronJob`: + +```yaml +apiVersion: batch/v1 +kind: CronJob +metadata: + name: pg-bkup-cronjob +spec: + schedule: "0 2 * * *" # Runs daily at 2 AM + jobTemplate: + spec: + template: + spec: + containers: + - name: pg-bkup + image: jkaninda/mysql-bkup + command: + - /bin/sh + - -c + - backup -d dbname + env: + - name: DB_HOST + value: "mysql" + - name: DB_USERNAME + value: "user" + - name: DB_PASSWORD + value: "password" + volumeMounts: + - mountPath: /backup + name: backup + volumes: + - name: backup + hostPath: + path: /home/toto/backup + type: Directory + restartPolicy: OnFailure +``` + +--- ## Available image registries This Docker image is published to both Docker Hub and the GitHub container registry. diff --git a/docs/how-tos/backup-all.md b/docs/how-tos/backup-all.md index a1f7355..1c75bba 100644 --- a/docs/how-tos/backup-all.md +++ b/docs/how-tos/backup-all.md @@ -7,7 +7,7 @@ nav_order: 12 # Backup All Databases -MySQL-Bkup supports backing up all databases on the server using the `--all-databases` (`-a`) flag. By default, this creates separate backup files for each database. If you prefer a single backup file, you can use the `--all-in-on`e (`-A`) flag. +MySQL-Bkup supports backing up all databases on the server using the `--all-databases` (`-a`) flag. By default, this creates separate backup files for each database. If you prefer a single backup file, you can use the `--all-in-one` (`-A`) flag. Backing up all databases is useful for creating a snapshot of the entire database server, whether for disaster recovery or migration purposes. ## Backup Modes @@ -21,7 +21,7 @@ Using --all-databases without --all-in-one creates individual backup files for e - Can be more manageable in cases where different databases have different retention policies. - Might take slightly longer due to multiple file operations. - It is the default behavior when using the `--all-databases` flag. -- It does not backup system databases (`information_schema`, `performance_schema`, `mysql`, `sys`, `innodb`). +- It does not backup system databases (`information_schema`, `performance_schema`, `mysql`, `sys`, `innodb`,...). **Command:** diff --git a/docs/how-tos/mutli-backup.md b/docs/how-tos/mutli-backup.md index 49d367c..5fb2593 100644 --- a/docs/how-tos/mutli-backup.md +++ b/docs/how-tos/mutli-backup.md @@ -19,7 +19,7 @@ The configuration file can be mounted into the container at `/config/config.yaml ### Key Features: - **Global Environment Variables**: Use these for databases that share the same configuration. -- **Database-Specific Overrides**: Override global settings for individual databases by specifying them in the configuration file or using the database name as a suffix in the variable name (e.g., `DB_HOST_DATABASE1`). +- **Database-Specific Overrides**: Override global settings for individual databases by specifying them in the configuration file or using the database name as a prefix or suffix in the variable name (e.g., `DB_HOST_DATABASENAME` or `DATABASENAME_DB_HOST`). - **Global Cron Expression**: Define a global `cronExpression` in the configuration file to schedule backups for all databases. If omitted, backups will run immediately. - **Configuration File Path**: Specify the configuration file path using: - The `BACKUP_CONFIG_FILE` environment variable. @@ -89,7 +89,7 @@ services: environment: ## Specify the path to the configuration file - BACKUP_CONFIG_FILE=/backup/config.yaml - # Ensure the pg-bkup container is connected to the same network as your database + # Ensure the mysql-bkup container is connected to the same network as your database networks: - web diff --git a/docs/index.md b/docs/index.md index f3b6051..135090b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -42,7 +42,7 @@ It supports a variety of storage options and ensures data security through GPG e ## Use Cases - **Automated Recurring Backups:** Schedule regular backups for MySQL databases. -- **Cross-Environment Migration:** Easily migrate MySQL databases across different environments using supported storage options. +- **Cross-Environment Migration:** Easily migrate MySQL databases across different environments using `migration` feature. - **Secure Backup Management:** Protect your data with GPG encryption. --- diff --git a/docs/quickstart/index.md b/docs/quickstart/index.md index 6437152..7638aad 100644 --- a/docs/quickstart/index.md +++ b/docs/quickstart/index.md @@ -10,11 +10,11 @@ This guide provides quick examples for running backups using Docker CLI, Docker --- -## Simple Backup Using Docker CLI +### Simple Backup Using Docker CLI -To run a one-time backup, bind your local volume to `/backup` in the container and execute the `backup` command: +To perform a one-time backup, bind your local volume to `/backup` in the container and run the `backup` command: -```bash +```shell docker run --rm --network your_network_name \ -v $PWD/backup:/backup/ \ -e "DB_HOST=dbhost" \ @@ -24,41 +24,58 @@ docker run --rm --network your_network_name \ jkaninda/mysql-bkup backup -d database_name ``` -### Using an Environment File +Alternatively, use an environment file (`--env-file`) for configuration: -Alternatively, you can use an `--env-file` to pass a full configuration: - -```bash +```shell docker run --rm --network your_network_name \ --env-file your-env-file \ -v $PWD/backup:/backup/ \ jkaninda/mysql-bkup backup -d database_name ``` -### Simple restore using Docker CLI +### Backup All Databases -To restore a database, bind your local volume to `/backup` in the container and run the `restore` command: +To back up all databases on the server, use the `--all-databases` or `-a` flag. By default, this creates individual backup files for each database. ```shell - docker run --rm --network your_network_name \ - -v $PWD/backup:/backup/ \ - -e "DB_HOST=dbhost" \ - -e "DB_PORT=3306" \ - -e "DB_USERNAME=username" \ - -e "DB_PASSWORD=password" \ - jkaninda/mysql-bkup restore -d database_name -f backup_file.sql.gz +docker run --rm --network your_network_name \ + -v $PWD/backup:/backup/ \ + -e "DB_HOST=dbhost" \ + -e "DB_PORT=3306" \ + -e "DB_USERNAME=username" \ + -e "DB_PASSWORD=password" \ + jkaninda/mysql-bkup backup --all-databases --disable-compression ``` + +> **Note:** Use the `--all-in-one` or `-A` flag to combine backups into a single file. + --- -## Simple Backup Using Docker Compose +### Simple Restore Using Docker CLI -Below is an example `docker-compose.yml` configuration for running a backup: +To restore a database, bind your local volume to `/backup` and run the `restore` command: + +```shell +docker run --rm --network your_network_name \ + -v $PWD/backup:/backup/ \ + -e "DB_HOST=dbhost" \ + -e "DB_PORT=3306" \ + -e "DB_USERNAME=username" \ + -e "DB_PASSWORD=password" \ + jkaninda/mysql-bkup restore -d database_name -f backup_file.sql.gz +``` + +--- + +### Backup with Docker Compose + +Below is an example of a `docker-compose.yml` file for running a one-time backup: ```yaml services: - mysql-bkup: - # In production, lock the image tag to a specific release version. - # Check https://github.com/jkaninda/mysql-bkup/releases for available releases. + pg-bkup: + # In production, pin your image tag to a specific release version instead of `latest`. + # See available releases: https://github.com/jkaninda/mysql-bkup/releases image: jkaninda/mysql-bkup container_name: mysql-bkup command: backup @@ -71,7 +88,6 @@ services: - DB_USERNAME=bar - DB_PASSWORD=password - TZ=Europe/Paris - # Ensure the mysql-bkup container is connected to the same network as your database. networks: - web @@ -81,11 +97,11 @@ networks: --- -## Recurring Backup with Docker +### Recurring Backups with Docker -To schedule recurring backups, use the `--cron-expression` flag: +You can schedule recurring backups using the `--cron-expression` or `-e` flag: -```bash +```shell docker run --rm --network network_name \ -v $PWD/backup:/backup/ \ -e "DB_HOST=hostname" \ @@ -98,9 +114,13 @@ For predefined schedules, refer to the [documentation](https://jkaninda.github.i --- -## Backup Using Kubernetes +## Deploy on Kubernetes -Below is an example Kubernetes `Job` configuration for running a backup: +For Kubernetes, you can deploy `mysql-bkup` as a Job or CronJob. Below are examples for both. + +### Kubernetes Backup Job + +This example defines a one-time backup job: ```yaml apiVersion: batch/v1 @@ -113,8 +133,8 @@ spec: spec: containers: - name: mysql-bkup - # In production, lock the image tag to a specific release version. - # Check https://github.com/jkaninda/mysql-bkup/releases for available releases. + # Pin the image tag to a specific release version in production. + # See available releases: https://github.com/jkaninda/mysql-bkup/releases image: jkaninda/mysql-bkup command: - /bin/sh @@ -128,7 +148,7 @@ spec: - name: DB_HOST value: "mysql" - name: DB_USERNAME - value: "postgres" + value: "user" - name: DB_PASSWORD value: "password" volumeMounts: @@ -137,11 +157,51 @@ spec: volumes: - name: backup hostPath: - path: /home/toto/backup # Directory location on the host - type: Directory # Optional field + path: /home/toto/backup # Directory location on the host + type: Directory # Optional field restartPolicy: Never ``` +### Kubernetes CronJob for Scheduled Backups + +For scheduled backups, use a `CronJob`: + +```yaml +apiVersion: batch/v1 +kind: CronJob +metadata: + name: pg-bkup-cronjob +spec: + schedule: "0 2 * * *" # Runs daily at 2 AM + jobTemplate: + spec: + template: + spec: + containers: + - name: pg-bkup + image: jkaninda/mysql-bkup + command: + - /bin/sh + - -c + - backup -d dbname + env: + - name: DB_HOST + value: "mysql" + - name: DB_USERNAME + value: "user" + - name: DB_PASSWORD + value: "password" + volumeMounts: + - mountPath: /backup + name: backup + volumes: + - name: backup + hostPath: + path: /home/toto/backup + type: Directory + restartPolicy: OnFailure +``` + --- ## Key Notes diff --git a/pkg/backup.go b/pkg/backup.go index 3c45164..68034ef 100644 --- a/pkg/backup.go +++ b/pkg/backup.go @@ -117,6 +117,9 @@ func createBackupTask(db *dbConfig, config *BackupConfig) { if config.all && !config.allInOne { backupAll(db, config) } else { + if db.dbName == "" && !config.all { + utils.Fatal("Database name is required, use DB_NAME environment variable or -d flag") + } backupTask(db, config) } } @@ -249,8 +252,10 @@ func BackupDatabase(db *dbConfig, backupFileName string, disableCompression, all dumpArgs := []string{fmt.Sprintf("--defaults-file=%s", mysqlClientConfig)} if all && singleFile { + utils.Info("Backing up all databases...") dumpArgs = append(dumpArgs, "--all-databases", "--single-transaction", "--routines", "--triggers") } else { + utils.Info("Backing up %s database...", db.dbName) dumpArgs = append(dumpArgs, db.dbName) } diff --git a/pkg/config.go b/pkg/config.go index c6a40e7..64ccda3 100644 --- a/pkg/config.go +++ b/pkg/config.go @@ -251,12 +251,10 @@ func initBackupConfig(cmd *cobra.Command) *BackupConfig { utils.GetEnv(cmd, "cron-expression", "BACKUP_CRON_EXPRESSION") utils.GetEnv(cmd, "path", "REMOTE_PATH") utils.GetEnv(cmd, "config", "BACKUP_CONFIG_FILE") - utils.GetEnv(cmd, "dbname", "DB_NAME") // Get flag value and set env remotePath := utils.GetEnvVariable("REMOTE_PATH", "SSH_REMOTE_PATH") storage = utils.GetEnv(cmd, "storage", "STORAGE") prune := false - configFile := os.Getenv("BACKUP_CONFIG_FILE") backupRetention := utils.GetIntEnv("BACKUP_RETENTION_DAYS") if backupRetention > 0 { prune = true @@ -281,10 +279,6 @@ func initBackupConfig(cmd *cobra.Command) *BackupConfig { encryption = true usingKey = false } - dbName := os.Getenv("DB_NAME") - if dbName == "" && !all && configFile == "" { - utils.Fatal("Database name is required, use DB_NAME environment variable or -d flag") - } // Initialize backup configs config := BackupConfig{} config.backupRetention = backupRetention