Database Migrations & Backups

Database Migrations

JChat manages its relational database schema with automated, transactional migrations that evolve alongside the application codebase.

Automated On-the-Go Migrations (Default)

When JChat starts or restarts:

1. Schema Check: JChat inspects the database schema migration history to determine the current state.
2. Transactional Migration: Any unapplied SQL migration files are executed sequentially within a safe database transaction.
3. Traffic Readiness: Once migrations complete successfully, the Elysia HTTP server and WebSocket gateway begin accepting inbound traffic.

Manual Migrations (Maintenance & Updates)

If running in a standalone bare-metal environment or applying manual maintenance updates:

# Apply pending database migrations:
bun run db:migrate

Database Backups

Regular database backups protect your data against catastrophic hardware failure, VPS corruption, or operator error.

Recommended Backup Strategies

Select your deployment architecture to view the recommended automated backup workflow:

#!/bin/bash
set -euo pipefail

BACKUP_DIR="/var/backups/jchat"
TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
mkdir -p "$BACKUP_DIR"

# Export compressed PostgreSQL database archive from Docker:
docker compose exec -T db pg_dump -U jchat -Fc jchat > "$BACKUP_DIR/jchat_$TIMESTAMP.dump"

# Retain only the last 7 days of backups to preserve VPS disk space:
find "$BACKUP_DIR" -type f -name "*.dump" -mtime +7 -delete

0 2 * * * /path/to/backup-docker.sh >> /var/log/jchat-backup.log 2>&1

Restoring a Database Backup

Follow these steps to safely restore a database archive:

docker compose stop jchat

# For Docker Compose deployments:
docker compose exec -T db pg_restore -U jchat -d jchat --clean --if-exists < /var/backups/jchat/jchat_YYYYMMDD_HHMMSS.dump

# For Standalone Linux deployments:
pg_restore -U jchat -d jchat --clean --if-exists /var/backups/jchat/jchat_YYYYMMDD_HHMMSS.dump

docker compose start jchat

Operational Best Practices