How DBX Implements Cloud Synchronization for Database Connections

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, with thin Tauri command wrappers exposed through 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.

pub async fn build_sync_snapshot_with_saved_secrets(
    storage: &Storage,
    app_version: impl Into<String>,
    editor_settings: Option<serde_json::Value>,
    secrets_passphrase: Option<&str>,
) -> Result<SyncSnapshot, String> {
    // 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, 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.

pub async fn put_snapshot(&self, snapshot: &SyncSnapshot) -> Result<WebDavSyncSummary, String> {
    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 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.

pub async fn apply_sync_snapshot(
    storage: &Storage,
    snapshot: &SyncSnapshot,
    options: ApplySnapshotOptions<'_>,
) -> Result<ApplySnapshotSummary, String> {
    // 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. 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

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

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, exposed to the UI via 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}