Skip to content

yugabyte-backup.md

Latest commit

 

History

History
207 lines (141 loc) · 6.24 KB

yugabyte-backup.md

File metadata and controls

207 lines (141 loc) · 6.24 KB
Raw
description How to backup and restore your YugabyteDB database for Curio

YugabyteDB Backup

Maintaining regular backups of your YugabyteDB database is critical for disaster recovery and before performing operations like software downgrades. This guide covers essential backup and restore procedures for your Curio cluster's database.

{% hint style="danger" %} 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. {% endhint %}

Important: Curio uses a DB and a schema

Curio connects to YugabyteDB over YSQL (Postgres protocol). Two configuration values matter:

  • Database name (CURIO_DB_NAME / --db-name) – default is yugabyte
  • Schema inside that database – Curio uses schema curio by default

So, on a default setup, you typically want to back up the yugabyte database (and it will include the curio schema).

Before running backups, confirm what Curio is configured to use:

# If you run Curio with env vars
echo "$CURIO_DB_NAME"

# If Curio is installed on PATH, you can inspect flags/defaults
curio --help | grep -E "db-(name|host|port)"

If you’re running Curio via systemd or containers, check the env/flags there:

# systemd (example)
systemctl cat curio | sed -n '1,200p'

# docker compose (example)
docker compose config | sed -n '1,200p'

Prerequisites

  • Access to your YugabyteDB cluster
  • The ysql_dump and ysqlsh utilities (included with YugabyteDB installation)
  • Sufficient disk space for backup files

Backup Methods

Method 1: Using ysql_dump (Recommended)

The ysql_dump utility creates a logical backup of your database that can be restored to any YugabyteDB cluster.

Full database backup

ysql_dump -h <yugabyte-host> -p 5433 -U <username> -d <database> -F c -f curio_backup_$(date +%Y%m%d_%H%M%S).dump

Parameters:

  • -h: YugabyteDB host address
  • -p: YSQL port (default: 5433)
  • -U: Database username
  • -d: Database name (often yugabyte for Curio defaults)
  • -F c: Custom format (compressed, supports parallel restore)
  • -f: Output filename

Example with typical Curio defaults

ysql_dump -h 127.0.0.1 -p 5433 -U yugabyte -d yugabyte -F c -f curio_backup_$(date +%Y%m%d_%H%M%S).dump

Curio schema backup

If you want to back up only Curio’s schema (and its data), not other schemas in the DB:

ysql_dump -h <yugabyte-host> -p 5433 -U <username> -d <database> --schema=curio -F c -f curio_schema_$(date +%Y%m%d_%H%M%S).dump

If you want schema-only (DDL only) for Curio (no data):

ysql_dump -h <yugabyte-host> -p 5433 -U <username> -d <database> --schema=curio --schema-only -f curio_schema_$(date +%Y%m%d_%H%M%S).sql

Method 2: Using ysqlsh with COPY

For smaller exports or specific tables:

ysqlsh -h <yugabyte-host> -p 5433 -U <username> -d <database> -c "\COPY <table_name> TO 'table_backup.csv' WITH CSV HEADER"

Restore Procedures

Restore from ysql_dump backup

{% hint style="warning" %} Ensure all Curio nodes are stopped before restoring a backup. {% endhint %}

Full restore (entire database)

# Drop and recreate the database (ONLY if you intend to restore the full DB)
ysqlsh -h <yugabyte-host> -p 5433 -U <username> -c "DROP DATABASE IF EXISTS <database>;"
ysqlsh -h <yugabyte-host> -p 5433 -U <username> -c "CREATE DATABASE <database>;"

# Restore from backup
pg_restore -h <yugabyte-host> -p 5433 -U <username> -d <database> -F c curio_backup_YYYYMMDD_HHMMSS.dump

Restore only the Curio schema

If you created a Curio-schema dump (--schema=curio), restore into the existing DB:

pg_restore -h <yugabyte-host> -p 5433 -U <username> -d <database> -F c curio_schema_YYYYMMDD_HHMMSS.dump

If you created a Curio schema-only SQL file (--schema-only), apply it with ysqlsh:

ysqlsh -h <yugabyte-host> -p 5433 -U <username> -d <database> -f curio_schema_YYYYMMDD_HHMMSS.sql

Automated Backup Script (example)

#!/bin/bash
# curio-db-backup.sh

BACKUP_DIR="/path/to/backups"
YB_HOST="127.0.0.1"
YB_PORT="5433"
YB_USER="yugabyte"
YB_DB="yugabyte"     # Curio default DB name
RETENTION_DAYS=7

mkdir -p "$BACKUP_DIR"

BACKUP_FILE="$BACKUP_DIR/curio_backup_$(date +%Y%m%d_%H%M%S).dump"
ysql_dump -h "$YB_HOST" -p "$YB_PORT" -U "$YB_USER" -d "$YB_DB" -F c -f "$BACKUP_FILE"

if [ $? -eq 0 ]; then
  echo "Backup created successfully: $BACKUP_FILE"
  find "$BACKUP_DIR" -name "curio_backup_*.dump" -mtime +$RETENTION_DAYS -delete
else
  echo "Backup failed!"
  exit 1
fi

Best Practices

  1. Regular backups: schedule automated daily backups for production clusters
  2. Test restores: periodically verify backups by performing test restores
  3. Off-site storage: store backup copies in a different location or cloud storage
  4. Pre-upgrade backups: always create a fresh backup before upgrading or downgrading Curio
  5. Monitor backup size: ensure adequate storage capacity

Troubleshooting

Connection issues

# Verify YugabyteDB is running
yugabyted status

# Check connectivity
ysqlsh -h <host> -p 5433 -U yugabyte -c "SELECT version();"

Permission errors

Ensure your database user has sufficient privileges:

GRANT ALL PRIVILEGES ON DATABASE <database> TO <username>;

You may also need privileges on the curio schema and its objects depending on how your cluster is secured.

Additional Resources

Multi-node cluster caveats (practical ops notes)

If you run a multi-node Yugabyte cluster:

  • Validate that your backup method matches your recovery goal.
    • Logical dumps (ysql_dump) are typically easiest for portability.
    • If you rely on Yugabyte-native distributed backups/snapshots, ensure you test restores.

Before a restore/downgrade:

  • stop all Curio writers
  • confirm no nodes are still writing tasks/metrics

See also:

  • documentation/en/administration/yugabyte-troubleshooting.md