Data Backup and Restore

Data Backup and Restore

ChatHub can export core account data as a versioned JSON backup and restore it from Settings → Storage. The browser transfers backups directly to ChatHub; S3 is not required.

What is included

• Preferences, application settings, and installed plugins
• AI providers, provider settings, models, and encrypted provider credentials
• Assistants, session groups, sessions, and group chats
• Topics, threads, message groups, messages, plugin results, and translations
• User memories, contexts, preferences, identities, and experiences

The export is a consistent database snapshot. ChatHub does not download a file if any included table fails to export.

What is excluded

• Uploaded files, generated media, object-storage content, knowledge-base documents, chunks, and embeddings
• Derived message chunks, query caches, TTS data, and asynchronous tasks
• Background conversation jobs (conversation_generation_* tables) and Graphile’s graphile_worker schema. Restored chats do not resume in-flight replies. A PostgreSQL volume backup does include those tables.
• Login sessions, OIDC/NextAuth records, roles, MCP OAuth tokens, and app API keys

A replace import may remove derived or file links that depend on replaced conversations through database cascades. Back up object storage separately when you need a complete disaster-recovery copy.

Export

1. Open Settings → Storage.
2. Select Export data.
3. Wait for the JSON download to finish.

The filename contains a 24-hour timestamp and the backup format version. Keep the file private: credentials remain encrypted, but the backup contains conversation and preference data.

Import strategies

Select the JSON file under Import data, review the preview, then choose:

• Merge safely (default): adds missing records, updates singleton settings, and skips content already imported. Reimporting the same file does not create duplicate conversations.
• Replace current data: atomically removes current data in the backup scope and restores the file. This requires an additional confirmation. If any row fails, ChatHub rolls back the deletion and restores the original state.

Authentication records and binary/object-storage data are never replaced. After a successful restore, choose Start using to reload all application stores.

Credential portability

Provider and settings credentials are stored as AES-GCM ciphertext in the backup. The destination deployment must use the same KEY_VAULTS_SECRET as the deployment that created the backup.

Before changing or rebuilding a deployment:

1. Save KEY_VAULTS_SECRET in a secure password or secret manager.
2. Restore the exact value, including Base64 padding.
3. Do not generate a new value when moving ChatHub if you need to restore its encrypted credentials.

ChatHub validates every encrypted vault before changing database data. A wrong or missing secret stops the import with a credential-key mismatch error.

Compatibility

• Current version 2 backups include their format, application version, source database migration hash, export time, and credential strategy.
• New exports always identify PostgreSQL as their source database.
• Known version 2 PGlite exports and unversioned version 1 exports from the older IndexedDB/Dexie edition remain importable. This is import compatibility only; ChatHub no longer runs either browser database.
• Backups from a newer database require upgrading ChatHub first.
• Unknown migration hashes, future backup formats, unsupported version 2 tables, and malformed JSON are rejected before import.
• Non-empty derived tables from old backups are listed as ignored rather than reported as restored.

Moving from an old browser-local edition

The current server cannot read IndexedDB or PGlite data directly from an old browser profile. Before clearing or removing the old edition:

1. Open the old edition in the browser profile that contains the data.
2. Create and retain its JSON export.
3. Deploy the current ChatHub image with PostgreSQL and sign in as the target account.
4. Import the JSON file from Settings -> Storage.

Do not copy browser database files into the container; there is no automatic startup migration for them. When no JSON export exists, use the old application version to create one before moving to the current server deployment.

Troubleshooting

Error	Action
Encrypted credentials cannot be restored	Restore the original KEY_VAULTS_SECRET and restart ChatHub.
Backup was created by a newer database	Upgrade ChatHub and retry after migrations complete.
Unknown schema or unsupported format	Confirm the file came from ChatHub and was not manually modified.
Conversation data changed	Reopen the preview and retry; another write completed while the import was waiting.
Import failed and was rolled back	Check container/database logs for the first insert error. Existing data was not partially replaced.
HTTP 413 or transfer error	Increase the request-body limit on every reverse proxy/CDN hop. JSON backup transfer does not use S3.

For full disaster recovery, continue taking PostgreSQL volume backups in addition to this user-level JSON workflow.