Getting started

Install and update the app, run a first session, configure settings, and find config and data files.

The published app runs on Windows x64 and macOS (arm64). It requires macOS 11 or later. The app bundles its own Java runtime. The MCP server also runs on Linux.

Install

Use the packages on the downloads page. The current release is 1.1.1. See the changelog for what changed in each release.

On Windows, run the download. Uninstall removes the app and its data.

On macOS, unzip the download and move safe-db.app to Applications.

Updates

On Windows there is no in-app updater. The published package is checked in the background, whether or not you have launched the app. Closing the app lets a pending update finish replacing the running copy.

On macOS the app checks for updates in the background, about once an hour, and installs the new package.

A first session

There is no first-launch wizard. Home is a welcome screen. The shortcuts are New Connection, Build a Query, Recent Queries, SQL Editor, and Map. Saved queries appear on the same screen after you save one. New Connection opens the add-connection form directly, even from Home. 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 adding tables to the canvas.
  • Build a query. Build queries with joins, nested filters, and a row limit. 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 with pivot, worksheet, and chart views. The fetched rows stay in place until you refresh from a new run. See Explore.
  • History keeps recent and saved queries. Builder and SQL runs appear as they complete, without restarting the app. Delete a single entry, or clear the whole list.

Settings

Settings is a dialog for the options below.

  • Default query location. A default database, which is a saved connection, and a default schema on that connection.
  • Appearance. Dark or light, and a color scheme. The schemes are Control Blue (the default), Signal Teal, Oxide, and Command Violet. New installs start in light mode. A missing or unrecognized theme value also starts light. An explicitly saved dark theme stays dark.
  • Query risk gate. Cautious, Standard, Flexible, or Off. See Limits & risk model.
  • Query timeout. A whole number of seconds from 1 to 120. The default is 10. It applies to the next query run and its plan check. Connect and schema introspection do not follow it.
  • The dialog shows the installed version.

Blocked schemas are not in that dialog. They are the blocked_schemas list in settings.json. Names are trimmed and lowercased. System catalogs are omitted from the map and from MCP catalog tools, even when the list is empty. Restart after editing the file.

Where things live

The app writes JSON under this folder on Windows:

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

On macOS the folder is ~/Library/Application Support/com.safedb.app/.

connections.json
Named profiles. No passwords.
settings.json
Theme, color scheme, risk gate, query timeout, default connection and schema, last schema per connection, and blocked schemas.
saved_queries.json
Queries you saved.
query_history.json
Recent runs, capped at 100. Delete entries in History or clear the list.
explore_recipes.json
Saved Explore layouts.

Passwords are not in any of these files. See Credential storage. A hand-edited file the app cannot parse is moved aside with a .corrupt- or .unsupported- suffix, and the load fails closed. Restart after editing. Row limits, the sample ceiling, timeouts, and the risk gate are in Limits & risk model.

safe-db is proudly opensource.

GitHub