DBX

DBX Configuration Cloud Sync

DBX can package connections, application settings, and saved SQL into a snapshot. Desktop can sync through WebDAV or private snippets, while Web/Docker can sync through WebDAV and restore the snapshot in another DBX instance.

Cloud Sync backs up DBX configuration. It does not read or back up the business databases behind your connections. Use Database Export for schema and data, or Database Backup for scheduled Desktop MySQL/PostgreSQL backups.

Choose a provider under Settings → Sync:

  • WebDAV: Best when you already use a NAS, Nextcloud, or another WebDAV service. Supports scheduled uploads.
  • GitHub / Gitee / GitLab snippets: Stores the snapshot in a private snippet, including on self-managed GitLab. It is currently exposed in Desktop only; uploads and downloads are manual and never merge automatically.

What Is Synchronized

ItemDefault behavior
Database connections and non-secret optionsSynchronized
Sidebar layout and pinned nodesSynchronized
Saved SQL librarySynchronized
Desktop and editor settingsSynchronized
Database, SSH, proxy, HTTP tunnel, connection string, and AI API secretsExcluded by default; can be encrypted and synchronized
JDBC drivers, plugins, and local filesNot synchronized

Downloading replaces local connection metadata and saved SQL with the remote snapshot. Verify the snippet ID or WebDAV path before restoring.

Preventing uploads from an outdated device

Before updating an existing encrypted snippet, DBX compares its current content hash with the version last successfully uploaded or downloaded on this device. If they differ, or this device has no saved version, the upload stops. Back up local changes, then download and review the remote snapshot before uploading again. Inspecting the remote selection does not reset this protection. A new snippet can still be created by leaving its ID empty.

This check detects changes already present when the upload reads the remote file. Snippet providers do not offer a shared atomic compare-and-swap contract, so avoid uploading from multiple devices simultaneously. Snapshots are not merged automatically.

GitHub Gist

Create an Access Token

A GitHub fine-grained personal access token is recommended:

Open the GitHub fine-grained token creation page

Open token settings

Sign in to GitHub and open Settings → Developer settings → Personal access tokens → Fine-grained tokens.

Create a token

Select Generate new token, then set a name and expiration.

Grant permission

Under Account permissions, set Gists to Read and write. Repository permissions are not required.

Save the token

Copy the token immediately. GitHub only displays the complete token once.

A classic token also works, but grant only the gist scope.

First Upload

Select GitHub

Open Settings → Sync → Snippets and select GitHub Gist.

Enter the token

Paste the access token. Enabling Store encrypted on this device is recommended.

Create the Gist

Leave Snippet ID empty and select Upload. DBX creates a private Gist and stores the returned ID.

DBX stores an encrypted dbx-sync.json file in the Gist. The snippet encryption password protects the complete snapshot, so the URL does not expose connection details, SQL, or settings. Existing plain-text snippets can still be downloaded once for migration.

Plain-text snippets created by older versions cannot be safely migrated in place: updating the same Gist does not remove its revision history. Use Migrate legacy snippet instead. DBX encrypts the existing remote snapshot into a new snippet first, stores the new ID locally, and then rereads the old snippet before deleting it. If another device changed the old content, DBX stops automatic cleanup and tells you which old snippet must be deleted manually. If the old snapshot contains encrypted credentials, enter its original credentials password so DBX can verify them before cleanup. Rotate any credentials the old snippet may have exposed.

Restore on Another Device

  1. Open the private Gist and copy its ID from the URL. The URL normally looks like https://gist.github.com/<actual-username>/<gist-id>, where the final segment is the ID. You can also open https://gist.github.com/<gist-id> and let GitHub redirect to the URL containing the actual username.
  2. Enter the same GitHub token and Gist ID on the new device.
  3. Select Test to verify access.
  4. Select Download and confirm the restore.

Gitee Snippets

Create a Personal Access Token

Open the Gitee personal access token page

Open token settings

Sign in to Gitee and open Settings → Personal Access Tokens.

Create a token

Select Generate new token and enter a description.

Grant permission

Select only the code snippet (gists) permission. If permissions are grouped, choose the smallest permission that allows reading and writing snippets.

Save the token

Copy the generated token immediately and store it in a password manager.

Upload and Restore

  1. Select Gitee Snippet under Settings → Sync → Snippets.
  2. Enter the personal access token. Leave the snippet ID empty on the first upload; DBX creates a private snippet and stores its ID.
  3. To restore elsewhere, enter the same snippet ID and select Download.

Gitee snippets also use a dbx-sync.json file.

GitLab Snippets (including self-managed instances)

  1. Create a personal access token in GitLab under User Settings → Access Tokens with api scope. Do not put the token in the instance URL.
  2. In Desktop, open Settings → Sync → Snippets, select GitLab Snippets, and enter the root URL of your GitLab instance (for example, https://gitlab.example.com or http://gitlab.internal on an internal network; the default is https://gitlab.com). URLs with credentials, queries, or fragments are rejected. Leaving the field or pressing Enter applies a changed instance.
  3. Enter the token and a snippet encryption password. Leave the ID empty for the first upload: DBX creates a private personal Snippet. Later uploads update dbx-sync.json in that Snippet. To restore on another device, provide the same instance, token, ID, and encryption password, then manually download.

GitLab Snippets are not GitLab repository file sync. Each instance keeps its own local token, ID, and pending migration cleanup. Uploads and downloads do not merge automatically. A legacy plaintext DBX snapshot must use Migrate legacy snippet: DBX first creates an encrypted replacement, then rereads and deletes the old Snippet only if unchanged. If the old content has changed or cleanup fails, delete the old Snippet manually.

HTTP transmits the GitLab access token in cleartext even though the snapshot is encrypted. Use HTTP only on a trusted internal network; prefer HTTPS for self-managed GitLab.

Sync Password and Secrets

GitHub Gist, Gitee, and GitLab snippets always encrypt the entire snapshot with a snippet encryption password. The password is never uploaded or saved and cannot be recovered. This password is independent from the password that encrypts optional synced credentials.

Snapshots exclude credentials by default. To restore passwords on another device:

  1. Enable Include encrypted credentials when uploading.
  2. Enter a separate sync password for credentials.
  3. Upload the snapshot.
  4. On another device, enable Restore encrypted credentials when downloading and enter the same credentials password. Leave it off to keep local passwords unchanged.

DBX derives the encryption key with Argon2id and uses AES-256-GCM encryption. Provider access tokens are encrypted with a device-local key and are never written to dbx-sync.json.

Neither password can be recovered. An encrypted snippet cannot be restored without its snippet encryption password. For WebDAV, a snapshot without encrypted secrets can still be restored without a passphrase.

WebDAV

Enter the WebDAV endpoint, username, application password, and remote snapshot path. The default path is DBX/sync/snapshot.json.

Set the remote snapshot path to DBX/sync/snapshot.zip to enable ZIP snapshots. DBX compresses the same JSON snapshot into a ZIP containing only snapshot.json and uploads it as application/zip. Other paths still upload JSON. Downloads detect JSON or ZIP from the content, including JSON snapshots that older versions stored at a .zip path. Both the ZIP archive and its uncompressed JSON are limited to 100 MiB, and no files are extracted to disk. Compression is not encryption; existing sensitive-data encryption settings still apply.

Some WebDAV services, including CSTCloud Capsule, restrict both client applications and upload file types. For a client restriction, set User-Agent to an identifier accepted by the service (for example Zotero/10.0.0). It stays empty by default, which sends no User-Agent. Zotero-specific endpoints may also accept only .zip / .prop uploads, so changing User-Agent alone does not make JSON uploads compatible; try a ZIP snapshot in this case. For upload errors 403, 405 or 415, also check account write permissions and server policies. ZIP support does not bypass permission checks.

Switching formats uses a new remote path and does not delete the original JSON snapshot. Configure the same path on all devices. Upgrade every device to a DBX version supporting ZIP snapshots before enabling ZIP; older versions must keep using a JSON path. Use a separate DBX directory, not Zotero's own synchronization directory.

In Web/Docker mode, the DBX server sends WebDAV requests, so browser CORS restrictions do not apply. WebDAV application passwords are encrypted in the current DBX instance and are never included in sync snapshots.

WebDAV supports scheduled uploads while the corresponding DBX client remains open. Keep at least one DBX page open when using Web/Docker. Downloads always require confirmation to prevent accidental replacement of data in the current instance.

Troubleshooting

HTTP 401 or 403

The token is invalid, expired, or missing snippet read/write permission. Create a new least-privilege token and test again.

HTTP 404

The snippet ID is incorrect, or the current token cannot access the private snippet.

Where is the ID after the first upload?

DBX stores it automatically. You can also find it in the URL of the GitHub Gist or Gitee snippet page.

Can multiple devices synchronize automatically?

Snippet synchronization currently uses manual upload and download and does not merge concurrent changes. Download the latest snapshot before uploading to avoid replacing changes from another device.