History Sync & Backup

Keep your work with you everywhere. History Sync provides a local first, privacy preserving way to keep your query history backed up and available on all of your devices — with end to end encryption applied before upload so we can never see your data in the cloud.

What You Get

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

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 itself 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 are retained for 6 months.
  • Protection: All 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 Details

  • 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 rewaps the DEK without re encrypting your history data.

Important: If you forget your passphrase, your cloud history cannot be decrypted and sync will not work. Keep it safe.

Performance & Reliability

  • Local first: Your history remains fully functional offline; sync resumes when online.
  • Efficient sync: Changes are batched and compressed to minimize bandwidth.
  • Conflict free: CRDTs merge changes from multiple devices automatically.

Technical Details

  • Key envelope: The 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.