Recern
Download
Recern Workspace · Documentation

Local settings backups and recovery

Available in Workspace 1.0.0. This is a local profile backup, not a database backup or an app installer downgrade.

What is saved

Each completed checkpoint is a private directory under <app config>/settings-backups/<uuid>, with a versioned manifest.json, SHA-256 and a size for each allowlisted file. Missing files are recorded explicitly so restoring a previously empty profile also removes newer connection/query files.

  • connections.json: connection settings, groups and order, without passwords.
  • queries.json: local query history and saved queries.
  • known_hosts: SSH keys explicitly trusted in Recern, without reading or changing the user's global ~/.ssh/known_hosts.
  • settings-state.json: profile schema and last initialized app version. Versioned profiles record an explicit minimum reader version for compatible installer rollback. Older markers without it retain their conservative version guard; unknown schemas or a newer minimum reader stop before profile writes.
  • webview-state.json: a capture of the Recern-owned webview keys for settings, remembered engine flavors, sidebar grouping, console drafts and legacy history.

System-keychain secrets and debug dev-secrets.json, telemetry consent/IDs, exports, database files, TLS/private keys, arbitrary filesystem paths and browser demo data are excluded. Existing password stores are never rolled back or cleared by restore; previously deleted or changed passwords may need re-entry.

On Unix, checkpoint directories are 0700 and files are 0600. On Windows, they inherit the app configuration directory's user ACL; verify the installer/user ACLs on release builds. Checksums detect corruption; they are not encryption or protection against a process that can modify both the data and manifest. Backups can contain sensitive SQL and local paths. They are not uploaded or automatically deleted. Incomplete .pending-* directories are retained but are not offered for restore.

When a checkpoint is made

The native shell holds a settings lock for its lifetime. Before React mounts or connections open, the frontend captures its existing webview preferences/drafts. The native initializer validates the profile, creates a checkpoint if version tracking is absent or the app version changed, and then writes the version marker. A malformed profile is reported rather than replaced with empty defaults.

This captures the original unversioned 0.5.0 files before Workspace 1.0 can save new sqlserver records. If someone has already used a previous preview without version tracking, the source is labeled Before version tracking, not falsely identified as 0.5.0.

Settings → Backups & recovery can create additional manual checkpoints. Installing a downloaded app update also requires a successful checkpoint before calling the updater's install operation. Connection/query/SSH-trust writes are serialized with snapshot creation, without holding the lock for database query execution. Native copies are built in a private staging directory, synced and renamed into place; partial copies never appear as completed backups.

Each native file is limited to 64 MiB; interface state is limited to 2,048 keys and 16 MiB of key/value text. Oversized data stops backup/update instead of being silently omitted. A snapshot is not claimed to cover another app's storage, another webview origin or credentials in the keychain.

Restore

  1. Select a completed checkpoint in Settings. The dialog identifies its date and explains what will change. Nothing is overwritten while the app is open.
  2. Restore and restart validates the archive and records the request. If the restart fails, the request remains visible and can be cancelled in Settings. Profile writes/new connections are blocked while recovery is pending.
  3. Before opening stores on the next launch, the app validates the archive again and creates a safety checkpoint of the current native profile plus the interface capture from the restore request. It writes a recovery journal, then atomically replaces each allowlisted native file.
  4. Before mounting React, the frontend restores preferences/drafts, removes newer Recern-owned keys absent from the snapshot, and disables automatic connections. Unrelated browser storage is preserved. Telemetry is reset to off and requires a new opt-in in Settings; archived consent can never enable it.
  5. Only after frontend acknowledgement is the journal removed and normal profile writes/connections allowed. A quota failure attempts to restore the previous browser values and offers Return to previous settings and restart.

WebView acknowledgement alone does not prove asynchronous localStorage writes reached disk. A private webview-restore-receipt.json records the confirmed UI generation alongside the durable webview-state.json cache. Before opening the profile on a later launch, a stale WebView generation replays that cache rather than replacing it with old preferences. A matching generation accepts later deliberate user edits. The generation marker and receipt are transaction metadata, not archived user preferences. Completed-generation replay does not reset a new telemetry consent a second time.

If the process stops during file replacement, the next launch replays the whole transaction. If the target archive disappears or fails validation after a partial restore, it replays the safety checkpoint instead. If neither checkpoint can be validated, startup stops with the journal and files retained for recovery; it does not open a mixed profile or erase it. Native stores also fail closed on invalid JSON. Stores are loaded only after initialization succeeds, so damaged startup data leaves the native recovery screen usable. It lists verified local copies and can recover the selected copy and restart. A damaged active journal is retained under a settings-restore-superseded-*.json name when the user explicitly selects another backup. An invalid queued target can be cancelled when native replacement has not begun. Raw damaged files are preserved in the safety checkpoint; an invalid checkpoint is retained but is not offered for use. If the configuration folder cannot be opened or locked, close other instances and repair access with the app closed.

The UI's 0.5.0 note only checks that connection and query records use engines recognized by 0.5.0. It is not proof of a signed installer downgrade or every OS/webview storage migration. Restore a compatible profile while still running Workspace 1.0, close it, then test the old installer separately. Never start 0.5.0 against sqlserver records. Keep all app instances closed during manual recovery; older versions do not participate in the new settings lock.

Tested behavior and limits

Native WebView checks run on macOS, Windows and Linux, including real restart, corrupted startup files, process termination between file replacements and the unchanged 0.5.0 reader. Installed-candidate tests also exercise signed updates, compatible installer rollback and real system password stores. Hosted runners do not establish every physical-device, elevation prompt or keychain policy.

Windows 1.0.0 is intentionally released without Authenticode. Process termination is not proof of power-loss durability on every filesystem. Disk-full/power-loss checks and automatic backup retention remain follow-up work. Check free disk space and manage retained backups according to your needs.