Getting started

safe-db runs on macOS and Windows. Unsupported operating systems exit before any profile, credential store, or app data is touched. Refusal is a feature here, and it starts at the operating system. The MCP server is the exception: it has no window, so it also runs on Linux.

Install

Use the signed installer from the downloads page (Windows today; a signed, notarized macOS installer is next).

The Windows download is a signed .exe bootstrapper. Windows App Installer then installs a signed MSIX. That is not a traditional Setup.exe: there is no Program Files tree of yours to patch, and the package under WindowsApps is read-only. Uninstall is a package removal; virtualized app data goes with it. The package bundles its own Java runtime, so there is nothing to install first and no version of anything to check.

The app already runs on macOS from source: ./gradlew run, or ./gradlew packageDistributionForCurrentOS for an unsigned DMG. Those unsigned builds (and ./gradlew run on Windows) are ordinary processes; they do not get the MSIX AppData redirect. The GitHub repository covers the rest.

Updates

There is no in-app updater and no prompt. App Installer checks the published package in the background, whether or not you launched the app. Windows batches that check about every eight hours by default; MDM or App Installer policy on the machine can change or disable it. You cannot speed it up from inside safe-db.

A new version is a new signed package, applied when Windows next takes the update. Closing the app lets a pending package finish replacing.

The shortest safe path to data

There is no first-launch wizard. Home is a welcome screen with shortcuts. From there:

• Connections. Give the profile a name, test it, save it. The password goes to the platform credential store on save. See Connections and Credential storage.
• Browse the schema. Map is the dedicated screen. The Query Builder also has a Schema rail for putting tables on the canvas.
• Build a query. Typed and parameterized, with joins, nested filters, and a row limit you actually control; see Query builder. Or type a single SELECT on the SQL screen (Typed SQL). Ctrl/Cmd+Enter runs SQL; Ctrl/Cmd+K opens the command palette.
• Look at the sample. Explore opens a second window: pivot it, spreadsheet it, chart it. The underlying rows stay put until you refresh from a new run. See Explore.
• History keeps recent and saved queries if you want to come back to one.

Where things live

The app writes JSON under %APPDATA%\com.safedb.app\ on Windows and ~/Library/Application Support/com.safedb.app/ on macOS. On the signed MSIX, Windows virtualizes roaming AppData, so Explorer does not show those files at %APPDATA%. Open this instead:

%LOCALAPPDATA%\Packages\Safedb_q22pzpqsf8v86\LocalCache\Roaming\com.safedb.app\

Not LocalState, not WindowsApps. From-source and unsigned MSI builds write to the real roaming folder; there is no package redirect.

Passwords are not in any of these files; see Credential storage. A hand-edit the app cannot parse is moved aside with a .corrupt- or .unsupported- suffix, and load fails closed. Restart after editing. Caps, timeouts, and the risk dial are in Limits & risk model.