History Sync & Backup

History Sync keeps your query history available across devices using client-side encryption and cloud storage. Encryption happens on your machine before upload; only encrypted data is stored in the cloud.

Capabilities

  • End to end encrypted sync and cloud backup
  • Local first: works offline; syncs when online
  • Conflict free merges across devices (CRDT powered)
  • Restore on new devices

Requirements

  • Signed in DBCode account
  • History enabled in DBCode
  • Network access to DBCode API and storage

How It Works

Your history is stored locally on your device. Before upload, DBCode encrypts changes on device using a randomly generated Data Encryption Key (DEK). The DEK is protected by a server stored key envelope: the DEK is wrapped with a Key Encryption Key (KEK) derived from your passphrase via scrypt. The passphrase never leaves your device and is not stored; only the encrypted DEK (the envelope) and encrypted history blobs are stored in the cloud. On another device, DBCode fetches the envelope, prompts once for your passphrase to unwrap the DEK, and decrypts data locally.

History Sync encryption and multi-device flow
Your device compresses and encrypts history updates (AES GCM with a DEK) before upload. The DEK is protected by a server stored key envelope (wrapped with a passphrase derived key). Other devices fetch the envelope, unwrap the DEK with your passphrase locally, then decrypt and merge using CRDTs.

Sync Cadence & Retention

  • Updates: Background sync batches and uploads changes every 2 hours.
  • Snapshots: A full snapshot is created every 7 days.
  • Restore path: New devices restore using the latest snapshot plus any subsequent updates.
  • Retention: Updates are retained for 1 month; snapshots for 6 months.
  • Protection: Uploads are compressed and then encrypted on your device before leaving it.

Enable Sync

  1. Open DBCode in VS Code and go to the DBCode Explorer sidebar.
  2. Open the History view and click the sync icon.
  3. Create an encryption passphrase (recommended minimum 12 characters). It never leaves your device and is not stored. DBCode derives a KEK from your passphrase to wrap a generated DEK and uploads only the encrypted envelope; the decrypted DEK is cached locally in VS Code Secret Storage so you won’t be prompted again on this device.
  4. If this is a new device, history will be restored from the cloud; otherwise your device begins syncing changes in the background.

Tip: You can also manage sync via settings: DBCode: History: Enable Sync.

Important: Use the same passphrase on every device that participates in History Sync. If you forget your passphrase, you will not be able to unwrap the DEK to decrypt your cloud history. We cannot recover or reset your passphrase.

Restore on a New Device

When enabling sync on a device without local history, DBCode can restore from your encrypted cloud backup.

Restore encrypted history on a new device
New devices fetch the key envelope, unwrap the DEK with your passphrase, then download and decrypt the latest snapshot and updates.

Security

  • Client side only: Encryption and decryption happen on your device.
  • End to end encryption: History blobs are encrypted with a random 32 byte DEK using AES 256 GCM. The DEK is wrapped by a KEK derived from your passphrase via scrypt and stored only as an encrypted envelope on the server.
  • Passphrase privacy: Your passphrase never leaves your device and is never stored. The decrypted DEK is cached locally in VS Code Secret Storage for seamless use on that device.
  • Zero knowledge storage: Only encrypted data and an encrypted DEK envelope are stored in S3 compatible storage; we cannot decrypt them.
  • Additional protection: Server side encryption at rest (SSE) is enabled on storage as a secondary layer.
  • Local storage: DBCode does not encrypt your history at rest on your device; encryption is applied immediately before upload.
  • Passphrase scope: All devices must use the same passphrase to unlock the same DEK; changing your passphrase rewraps the DEK without re encrypting your history data.

Technical Details

  • Key envelope: Server stores a small JSON envelope containing the DEK encrypted (wrapped) with a KEK derived from your passphrase using scrypt, along with scrypt parameters and AES GCM IV/tag. Only the encrypted DEK is stored; the passphrase is never transmitted.
  • Blob format: Each uploaded blob begins with a compact header identifying the format version and a keyId, followed by AES GCM output: IV || ciphertext || tag. The keyId lets DBCode select the correct DEK if rotation is added.
  • First device: If no envelope exists, DBCode generates a DEK, wraps it with your passphrase derived KEK, uploads the envelope, and caches the DEK in Secret Storage.
  • New device: DBCode fetches the envelope, prompts for your passphrase to unwrap the DEK, caches it locally, and decrypts history.
  • Change passphrase: DBCode derives a new KEK from your new passphrase and rewraps the same DEK; history blobs do not need to be re encrypted.