jkaninda/mysql-bkup
1
1
Fork 0
mirror of https://github.com/jkaninda/mysql-bkup.git synced 2025-12-07 22:19:42 +01:00
Code Issues Actions Projects Releases Wiki Activity

Merge branch 'docs' into nightly

Browse Source
This commit is contained in:
Jonas Kaninda
2025-03-17 09:05:16 +01:00
parent 23cce10e8c cb299a35bf
commit 4110ff4e64
7 changed files with 226 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files

175
README.md
View File

@@ -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.

4
docs/how-tos/backup-all.md
View File

@@ -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:**

4
docs/how-tos/mutli-backup.md
View File

@@ -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

2
docs/index.md
View File

@@ -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.
---

124
docs/quickstart/index.md
View File

@@ -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

5
pkg/backup.go
View File

@@ -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)
}

6
pkg/config.go
View File

@@ -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