|
| 1 | +--- |
| 2 | +description: How to backup and restore your YugabyteDB database for Curio |
| 3 | +--- |
| 4 | + |
| 5 | +# YugabyteDB Backup |
| 6 | + |
| 7 | +Maintaining regular backups of your YugabyteDB database is critical for disaster recovery and before performing operations like software downgrades. This guide covers the essential backup and restore procedures for your Curio cluster's database. |
| 8 | + |
| 9 | +{% hint style="danger" %} |
| 10 | +**Always create a backup before running `curio toolbox downgrade`** or performing any major cluster operations. Database schema changes during upgrades may not be reversible without a backup. |
| 11 | +{% endhint %} |
| 12 | + |
| 13 | +## Prerequisites |
| 14 | + |
| 15 | +- Access to your YugabyteDB cluster |
| 16 | +- The `ysql_dump` and `ysqlsh` utilities (included with YugabyteDB installation) |
| 17 | +- Sufficient disk space for backup files |
| 18 | + |
| 19 | +## Backup Methods |
| 20 | + |
| 21 | +### Method 1: Using ysql_dump (Recommended) |
| 22 | + |
| 23 | +The `ysql_dump` utility creates a logical backup of your database that can be restored to any YugabyteDB cluster. |
| 24 | + |
| 25 | +#### Full Database Backup |
| 26 | + |
| 27 | +```bash |
| 28 | +ysql_dump -h <yugabyte-host> -p 5433 -U <username> -d <database> -F c -f curio_backup_$(date +%Y%m%d_%H%M%S).dump |
| 29 | +``` |
| 30 | + |
| 31 | +**Parameters:** |
| 32 | +- `-h`: YugabyteDB host address |
| 33 | +- `-p`: YSQL port (default: 5433) |
| 34 | +- `-U`: Database username |
| 35 | +- `-d`: Database name (typically `curio` or your configured database name) |
| 36 | +- `-F c`: Custom format (compressed, supports parallel restore) |
| 37 | +- `-f`: Output filename |
| 38 | + |
| 39 | +#### Example with typical Curio configuration |
| 40 | + |
| 41 | +```bash |
| 42 | +ysql_dump -h 127.0.0.1 -p 5433 -U yugabyte -d curio -F c -f curio_backup_$(date +%Y%m%d_%H%M%S).dump |
| 43 | +``` |
| 44 | + |
| 45 | +#### Schema-Only Backup |
| 46 | + |
| 47 | +To backup only the database schema without data: |
| 48 | + |
| 49 | +```bash |
| 50 | +ysql_dump -h <yugabyte-host> -p 5433 -U <username> -d <database> --schema-only -f curio_schema_$(date +%Y%m%d_%H%M%S).sql |
| 51 | +``` |
| 52 | + |
| 53 | +### Method 2: Using ysqlsh with COPY |
| 54 | + |
| 55 | +For smaller databases or specific tables: |
| 56 | + |
| 57 | +```bash |
| 58 | +ysqlsh -h <yugabyte-host> -p 5433 -U <username> -d <database> -c "\COPY <table_name> TO 'table_backup.csv' WITH CSV HEADER" |
| 59 | +``` |
| 60 | + |
| 61 | +## Restore Procedures |
| 62 | + |
| 63 | +### Restore from ysql_dump backup |
| 64 | + |
| 65 | +#### Full Restore |
| 66 | + |
| 67 | +{% hint style="warning" %} |
| 68 | +Ensure all Curio nodes are **stopped** before restoring a backup. |
| 69 | +{% endhint %} |
| 70 | + |
| 71 | +```bash |
| 72 | +# First, drop and recreate the database if needed |
| 73 | +ysqlsh -h <yugabyte-host> -p 5433 -U <username> -c "DROP DATABASE IF EXISTS curio;" |
| 74 | +ysqlsh -h <yugabyte-host> -p 5433 -U <username> -c "CREATE DATABASE curio;" |
| 75 | + |
| 76 | +# Restore from backup |
| 77 | +pg_restore -h <yugabyte-host> -p 5433 -U <username> -d curio -F c curio_backup_YYYYMMDD_HHMMSS.dump |
| 78 | +``` |
| 79 | + |
| 80 | +#### Restore from SQL dump |
| 81 | + |
| 82 | +```bash |
| 83 | +ysqlsh -h <yugabyte-host> -p 5433 -U <username> -d curio -f curio_backup.sql |
| 84 | +``` |
| 85 | + |
| 86 | +## Automated Backup Script |
| 87 | + |
| 88 | +Create a backup script for regular automated backups: |
| 89 | + |
| 90 | +```bash |
| 91 | +#!/bin/bash |
| 92 | +# curio-db-backup.sh |
| 93 | + |
| 94 | +BACKUP_DIR="/path/to/backups" |
| 95 | +YB_HOST="127.0.0.1" |
| 96 | +YB_PORT="5433" |
| 97 | +YB_USER="yugabyte" |
| 98 | +YB_DB="curio" |
| 99 | +RETENTION_DAYS=7 |
| 100 | + |
| 101 | +# Create backup directory if it doesn't exist |
| 102 | +mkdir -p "$BACKUP_DIR" |
| 103 | + |
| 104 | +# Create backup |
| 105 | +BACKUP_FILE="$BACKUP_DIR/curio_backup_$(date +%Y%m%d_%H%M%S).dump" |
| 106 | +ysql_dump -h "$YB_HOST" -p "$YB_PORT" -U "$YB_USER" -d "$YB_DB" -F c -f "$BACKUP_FILE" |
| 107 | + |
| 108 | +if [ $? -eq 0 ]; then |
| 109 | + echo "Backup created successfully: $BACKUP_FILE" |
| 110 | + |
| 111 | + # Remove backups older than retention period |
| 112 | + find "$BACKUP_DIR" -name "curio_backup_*.dump" -mtime +$RETENTION_DAYS -delete |
| 113 | + echo "Cleaned up backups older than $RETENTION_DAYS days" |
| 114 | +else |
| 115 | + echo "Backup failed!" |
| 116 | + exit 1 |
| 117 | +fi |
| 118 | +``` |
| 119 | + |
| 120 | +Make the script executable and add it to cron: |
| 121 | + |
| 122 | +```bash |
| 123 | +chmod +x curio-db-backup.sh |
| 124 | + |
| 125 | +# Add to crontab for daily backups at 2 AM |
| 126 | +crontab -e |
| 127 | +# Add: 0 2 * * * /path/to/curio-db-backup.sh >> /var/log/curio-backup.log 2>&1 |
| 128 | +``` |
| 129 | + |
| 130 | +## Best Practices |
| 131 | + |
| 132 | +1. **Regular Backups**: Schedule automated daily backups, especially for production clusters |
| 133 | +2. **Test Restores**: Periodically verify your backups by performing test restores |
| 134 | +3. **Off-site Storage**: Store backup copies in a different location or cloud storage |
| 135 | +4. **Pre-upgrade Backups**: Always create a fresh backup before upgrading or downgrading Curio |
| 136 | +5. **Monitor Backup Size**: Track backup sizes to ensure adequate storage capacity |
| 137 | + |
| 138 | +## Troubleshooting |
| 139 | + |
| 140 | +### Connection Issues |
| 141 | + |
| 142 | +If you encounter connection errors: |
| 143 | + |
| 144 | +```bash |
| 145 | +# Verify YugabyteDB is running |
| 146 | +yugabyted status |
| 147 | + |
| 148 | +# Check connectivity |
| 149 | +ysqlsh -h <host> -p 5433 -U yugabyte -c "SELECT version();" |
| 150 | +``` |
| 151 | + |
| 152 | +### Permission Errors |
| 153 | + |
| 154 | +Ensure your database user has sufficient privileges: |
| 155 | + |
| 156 | +```sql |
| 157 | +GRANT ALL PRIVILEGES ON DATABASE curio TO <username>; |
| 158 | +``` |
| 159 | + |
| 160 | +## Additional Resources |
| 161 | + |
| 162 | +- [YugabyteDB Backup and Restore Documentation](https://docs.yugabyte.com/preview/manage/backup-restore/) |
| 163 | +- [ysql_dump Reference](https://docs.yugabyte.com/preview/admin/ysql-dump/) |
| 164 | +- [YugabyteDB Best Practices](https://docs.yugabyte.com/preview/develop/best-practices-ysql/) |
0 commit comments