# How DBX Implements Cloud Synchronization for Database Connections > Discover how DBX implements secure cloud synchronization for database connections. Learn about encrypted snapshots, WebDAV transmission, and AES-256-GCM protection for your data. - Repository: [skyler/dbx](https://github.com/t8y2/dbx) - Tags: internals - Published: 2026-07-05 --- **DBX implements cloud synchronization by capturing encrypted snapshots of database connections and UI state, transmitting them via WebDAV, and restoring them on target devices using AES-256-GCM encryption for secrets.** The open-source DBX project (t8y2/dbx) provides a robust mechanism for synchronizing database connections across multiple devices through WebDAV-compatible cloud storage. This system centers on the `cloud_sync` module within the core crate, which handles snapshot serialization, military-grade encryption of sensitive credentials, and bidirectional data transfer. Understanding how DBX implements cloud synchronization for database connections reveals a security-first architecture that protects user secrets while enabling seamless cross-device workflows. ## Core Architecture of DBX Cloud Sync DBX employs a three-stage pipeline for cloud synchronization that separates data packaging from transport and restoration. 1. **Snapshot creation** – Aggregates connection metadata, UI state, saved SQL queries, and encrypted secrets into a portable `SyncSnapshot` struct. 2. **WebDAV transport** – Uploads or downloads the snapshot as a JSON payload via standard HTTP methods, automatically creating remote directory structures. 3. **Snapshot application** – Validates, decrypts, and merges the incoming data with existing local storage while preserving device-specific settings. All core logic resides in [`crates/dbx-core/src/cloud_sync.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-core/src/cloud_sync.rs), with thin Tauri command wrappers exposed through [`src-tauri/src/commands/cloud_sync.rs`](https://github.com/t8y2/dbx/blob/main/src-tauri/src/commands/cloud_sync.rs). ## Building and Encrypting Sync Snapshots ### Snapshot Creation with build_sync_snapshot_with_saved_secrets The `build_sync_snapshot_with_saved_secrets` function orchestrates the export process by gathering all persisted connections from the local `Storage` layer. It scrubs clear-text secrets from `ConnectionConfig` structs using `scrub_connection_secrets`, then conditionally encrypts sensitive data when a user provides a passphrase. ```rust pub async fn build_sync_snapshot_with_saved_secrets( storage: &Storage, app_version: impl Into, editor_settings: Option, secrets_passphrase: Option<&str>, ) -> Result { // Gathers connections, encrypts secrets if passphrase present } ``` The resulting `SyncSnapshot` contains connection metadata, UI layout configurations, pinned nodes, saved SQL snippets, desktop settings, and an optional encrypted blob of secrets. ### AES-256-GCM Encryption for Sensitive Data When a passphrase is supplied, DBX encrypts secrets using **AES-256-GCM** with keys derived via **Argon2id**. The `encrypt_sensitive_payload` function serializes a `SensitiveSyncPayload` (containing `ConnectionSecretSnapshot` objects) and encrypts the bytes using `encrypt_bytes_with_secret`. Decryption via `decrypt_sensitive_payload` validates the blob format (version 1, KDF argon2id, cipher aes-256-gcm) before restoring the plaintext. This ensures that secrets never leave the local device in an unencrypted state during cloud synchronization. ## WebDAV Transport Layer ### WebDavClient Implementation The `WebDavClient` struct wraps a `reqwest::Client` and implements the WebDAV protocol for snapshot transfer. Located in [`crates/dbx-core/src/cloud_sync.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-core/src/cloud_sync.rs), it exposes three primary operations: - **`test`** – Issues a `PROPFIND` request to verify endpoint accessibility. - **`put_snapshot`** – Serializes the `SyncSnapshot` to JSON and uploads via `PUT`. - **`get_snapshot`** – Downloads and deserializes the snapshot via `GET`. ```rust pub async fn put_snapshot(&self, snapshot: &SyncSnapshot) -> Result { let remote_path = self.remote_path(); self.ensure_parent_collections(&remote_path).await?; // Serialize and send JSON payload } ``` ### Remote Collection Management Before uploading, `ensure_parent_collections` recursively walks the remote path and issues `MKCOL` requests to create missing parent directories. This ensures compatibility with WebDAV servers that do not automatically instantiate collection hierarchies. ## Applying Snapshots on Target Devices The `apply_sync_snapshot` function reverses the export process by validating snapshot versions and decrypting the secret payload when a passphrase is available. The implementation in [`crates/dbx-core/src/cloud_sync.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-core/src/cloud_sync.rs) performs three critical steps: 1. **Metadata restoration** – Saves connection configurations while preserving existing local secrets. 2. **UI state recovery** – Restores layout, pinned nodes, saved SQL, and desktop preferences. 3. **Secret synchronization** – Clears obsolete secrets and writes new ones via `apply_sensitive_payload` when an encrypted blob is present. ```rust pub async fn apply_sync_snapshot( storage: &Storage, snapshot: &SyncSnapshot, options: ApplySnapshotOptions<'_>, ) -> Result { // Version check, decryption, then persistence } ``` ## Tauri Integration and UI Commands The desktop interface communicates with the core engine through commands defined in [`src-tauri/src/commands/cloud_sync.rs`](https://github.com/t8y2/dbx/blob/main/src-tauri/src/commands/cloud_sync.rs). These wrappers resolve stored WebDAV passwords and forward user parameters to the underlying Rust implementation: - **`webdav_sync_test`** – Verifies connectivity using `WebDavClient::test`. - **`webdav_sync_upload`** – Invokes `build_sync_snapshot_with_saved_secrets` followed by `WebDavClient::put_snapshot`. - **`webdav_sync_download`** – Fetches via `WebDavClient::get_snapshot` then applies via `apply_sync_snapshot`. - **`save_webdav_sync_secrets_preference`** – Configures whether secrets sync and stores the passphrase encrypted with a device secret. ## Practical Implementation Examples ### Uploading a Snapshot with Encrypted Secrets ```rust use dbx_core::cloud_sync::{WebDavConfig, WebDavClient}; use dbx_core::storage::Storage; // Initialize storage from Tauri AppState let storage: Storage = /* ... */; // Configure WebDAV endpoint let config = WebDavConfig { endpoint: "https://dav.example.com/webdav".into(), username: Some("alice".into()), password: None, // Resolved from secure storage remote_path: None, // Defaults to DBX/sync/snapshot.json }; // Build encrypted snapshot let snapshot = dbx_core::cloud_sync::build_sync_snapshot_with_saved_secrets( &storage, env!("CARGO_PKG_VERSION"), None, Some("my-secret-passphrase"), ).await?; // Upload to cloud let client = WebDavClient::new(config); let summary = client.put_snapshot(&snapshot).await?; println!("Uploaded {} bytes to {}", summary.bytes, summary.remote_path); ``` ### Downloading and Restoring a Snapshot ```rust use dbx_core::cloud_sync::{WebDavConfig, WebDavClient, ApplySnapshotOptions}; let config = WebDavConfig { endpoint: "https://dav.example.com/webdav".into(), username: Some("alice".into()), password: None, remote_path: None, }; let client = WebDavClient::new(config); let (snapshot, summary) = client.get_snapshot().await?; // Restore with passphrase decryption let apply_summary = dbx_core::cloud_sync::apply_sync_snapshot( &storage, &snapshot, ApplySnapshotOptions { secrets_passphrase: Some("my-secret-passphrase") }, ).await?; println!("Restored {} connections", apply_summary.connections_restored); ``` ## Summary - **Snapshot-based architecture** – DBX packages connections, UI state, and SQL history into versioned `SyncSnapshot` objects. - **Zero-knowledge encryption** – Secrets are encrypted with AES-256-GCM using Argon2id-derived keys before leaving the device. - **WebDAV compatibility** – Standard HTTP methods (`PUT`, `GET`, `PROPFIND`, `MKCOL`) enable synchronization with any WebDAV-compliant storage provider. - **Core implementation** – All synchronization logic lives in [`crates/dbx-core/src/cloud_sync.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-core/src/cloud_sync.rs), exposed to the UI via [`src-tauri/src/commands/cloud_sync.rs`](https://github.com/t8y2/dbx/blob/main/src-tauri/src/commands/cloud_sync.rs). - **Bidirectional flow** – The same code paths handle both upload (export) and download (import) operations with symmetric encryption support. ## Frequently Asked Questions ### How does DBX protect database passwords during cloud synchronization? DBX extracts secrets from connection configurations and encrypts them using AES-256-GCM before transmission. The encryption key is derived from a user-supplied passphrase via Argon2id, ensuring that the cloud provider cannot decrypt the payload without the passphrase. Clear-text secrets are scrubbed from the snapshot metadata and stored separately in the `SensitiveSyncPayload` encrypted blob. ### What cloud storage providers are compatible with DBX synchronization? Any storage service that exposes a WebDAV interface is compatible. This includes Nextcloud, ownCloud, Box, and generic WebDAV servers. The `WebDavClient` implementation uses standard HTTP methods (`PUT`, `GET`, `PROPFIND`) and automatically creates necessary directory structures using `MKCOL` requests. ### Can I synchronize database connections without sharing my passwords? Yes. The `build_sync_snapshot_with_saved_secrets` function accepts an optional passphrase parameter. If you pass `None`, the snapshot will include only connection metadata (hostnames, ports, usernames) while omitting the encrypted secrets payload. You can then manually re-enter passwords on the target device without transmitting them through the cloud. ### Where does DBX store the WebDAV password and sync passphrase locally? The Tauri command layer stores the WebDAV password and optional sync passphrase using the system's secure storage (keychain on macOS, credential manager on Windows, libsecret on Linux). These credentials are encrypted with a device-specific key and never included in the snapshot JSON that gets uploaded to the WebDAV server.