claude-configs/skills/paper-dynasty/workflows/database-sync.md

Database Sync - Production to Dev

Sync production Paper Dynasty database to development environment for testing, debugging, or local development with real data.

Quick Start

# Basic sync (with backup and confirmation prompt)
~/.claude/skills/paper-dynasty/scripts/sync_prod_to_dev.sh

# Auto-confirm sync (skip prompt)
~/.claude/skills/paper-dynasty/scripts/sync_prod_to_dev.sh --yes

# Dry run (see what would happen)
~/.claude/skills/paper-dynasty/scripts/sync_prod_to_dev.sh --dry-run

# Skip backup (faster, use with caution)
~/.claude/skills/paper-dynasty/scripts/sync_prod_to_dev.sh --no-backup --yes

What It Does

1. Verifies connectivity to both production and dev databases
2. Shows database statistics (size, table count) for comparison
3. Creates backup of current dev database (unless --no-backup)
4. Dumps production database using pg_dump
5. Restores to dev database replacing all existing data
6. Verifies restoration with updated statistics
7. Cleans up temporary dump files

Database Environments

Production (akamai)

• Container: sba_postgres
• Database: pd_master
• User: pd_admin
• Access: Via SSH to akamai host

Development (pd-database / 10.10.0.42)

• Container: sba_postgres
• Database: paperdynasty_dev
• User: sba_admin
• Access: Via SSH to pd-database host

When to Use

Scenario	Recommended Approach
Testing migrations	Sync with --no-backup for speed
Debugging production issues	Full sync to reproduce exact state
Local development setup	First-time sync with backup
QA testing	Regular syncs before testing cycles
Schema comparison	Use --dry-run to see database stats

Backups

Backups of the dev database are stored in:

~/.paper-dynasty/db-backups/paperdynasty_dev_YYYYMMDD_HHMMSS.sql

Restoring from Backup

If you need to restore a dev database backup:

# List available backups
ls -lh ~/.paper-dynasty/db-backups/

# Restore a specific backup
BACKUP_FILE=~/.paper-dynasty/db-backups/paperdynasty_dev_20260203_143022.sql
ssh pd-database "docker exec -i sba_postgres psql -U sba_admin -d paperdynasty_dev" < "$BACKUP_FILE"

Manual Steps (Alternative to Script)

If you prefer to run steps manually:

1. Create Production Dump

ssh akamai "docker exec sba_postgres pg_dump -U pd_admin -d pd_master --clean --if-exists" > /tmp/pd_prod_dump.sql

2. Backup Current Dev (Optional)

ssh pd-database "docker exec sba_postgres pg_dump -U sba_admin -d paperdynasty_dev --clean --if-exists" > ~/.paper-dynasty/db-backups/paperdynasty_dev_backup.sql

3. Restore to Dev

ssh pd-database "docker exec -i sba_postgres psql -U sba_admin -d paperdynasty_dev" < /tmp/pd_prod_dump.sql

4. Clean Up

rm /tmp/pd_prod_dump.sql

Troubleshooting

Connection Issues

Problem: Cannot connect to production/dev database

# Test production connection
ssh akamai "docker exec sba_postgres psql -U pd_admin -d pd_master -c 'SELECT version();'"

# Test dev connection
ssh pd-database "docker exec sba_postgres psql -U sba_admin -d paperdynasty_dev -c 'SELECT version();'"

Permission Errors

Problem: Permission denied errors during restore

Solution: Ensure the dev user has proper permissions:

ssh pd-database "docker exec sba_postgres psql -U sba_admin -d paperdynasty_dev -c 'GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO sba_admin;'"

Disk Space Issues

Problem: Not enough disk space for dump file

# Check available space on local machine
df -h /tmp

# Check available space on dev server
ssh pd-database "df -h /var/lib/docker"

Solution: Use compression:

# Create compressed dump
ssh akamai "docker exec sba_postgres pg_dump -U pd_admin -d pd_master --clean --if-exists | gzip" > /tmp/pd_prod_dump.sql.gz

# Restore compressed dump
gunzip -c /tmp/pd_prod_dump.sql.gz | ssh pd-database "docker exec -i sba_postgres psql -U sba_admin -d paperdynasty_dev"

Restore Failures

Problem: Errors during restore (foreign key constraints, etc.)

Solution: The script uses --clean --if-exists which should handle most cases. If issues persist:

1. Check the error messages for specific constraint violations
2. Try restoring with single-transaction mode:

   ssh pd-database "docker exec -i sba_postgres psql -U sba_admin -d paperdynasty_dev --single-transaction" < /tmp/pd_prod_dump.sql
   

Safety Features

• Confirmation prompt: Requires explicit "yes" before making changes
• Dry run mode: Preview operations without making changes
• Automatic backups: Dev database is backed up by default
• Backup retention: Backups are timestamped and never auto-deleted
• Error handling: Script exits on any error, preventing partial syncs

Performance Notes

• Dump time: ~10-30 seconds for typical database
• Transfer time: Depends on database size (usually < 1 minute)
• Restore time: ~20-60 seconds depending on data volume
• Total time: Typically 1-2 minutes for full sync

Add --no-backup to save ~30 seconds if dev database backup isn't needed.

Security Notes

• Database credentials are hardcoded in the script (stored in skill directory)
• Dump files contain sensitive production data
• Temporary dumps are created in /tmp and automatically deleted
• Backups are stored in user home directory (~/.paper-dynasty/db-backups/)
• Consider encrypting backups for long-term storage

Integration with Other Workflows

This sync workflow pairs well with:

• Migration Testing: Sync prod data, then test migrations on dev
• API Development: Work with realistic data locally
• Bug Reproduction: Sync prod state to reproduce issues
• Performance Testing: Test queries against production-sized datasets

---

Last Updated: 2026-02-03