Settings and app data
DuckLocal stores one database file on disk, plus a small file while the window is running, and a log file. If you enable the online base map, it also caches map tiles; a downloaded update waits in the cache too. Everything else stays in memory for the duration of the session. Dashboard review comments are an exception: they are stored beside the dashboard file, not in the app-data directory (see Review with comments).
Where things are stored
| Platform | Path |
|---|---|
| macOS | ~/Library/Application Support/DuckLocal/history.duckdb |
| Windows | %APPDATA%\DuckLocal\data\history.duckdb |
| Linux | ~/.local/share/ducklocal/history.duckdb |
The DuckDB file contains four tables: query history, registered data files, databases attached beside the open database, and a small key/value settings table. Settings include the interface language and size, open query and dashboard tabs, the recent-dashboards list, and whether the base map and update check are enabled. While the app runs, a companion .wal file (DuckDB's write-ahead log) sits beside it.
Your datasets are never copied into the application database. Registered files are stored as file paths and automatically re-attached whenever DuckLocal launches.
Beside it, while a window is open, gui-endpoint.json holds the loopback port and random token ducklocal open uses to reach the window. Only your account can read it, and a stale gui-endpoint.json left by a window that quit is harmless.
The logs folder beside it holds the window's log, ducklocal.log (and the previous launch's, ducklocal.previous.log). If DuckLocal crashes, it writes a crash-….log report there first, and the next launch says what happened, with Show report. The last ten reports are kept. Attach the report when you file an issue. Open logs folder opens the folder: it is in the DuckLocal menu on macOS, and on the right-click menu of the version at the right end of the status bar everywhere. The ducklocal command writes no log file; its errors go to its caller.
Map tiles for the online base map go to the platform cache folder — ~/Library/Caches/DuckLocal/tiles on macOS, %LOCALAPPDATA%\DuckLocal\cache\tiles on Windows, ~/.cache/ducklocal/tiles on Linux — one folder per tile server. Deleting it is harmless — the tiles are simply downloaded again. A downloaded update waits in updates in the same cache folder until it is installed.
What survives a restart
| Remembered | Where |
|---|---|
| Registered data files — path, view name, kind | app data file |
| Query history, including failures | app data file |
| Interface language | app data file |
| Interface size | app data file |
| Whether the first-run guide has been seen | app data file |
| Whether the sidebar is hidden | app data file |
| Databases attached beside the open one, and whether each is read-only | app data file |
| Open query tabs, with their titles and SQL | app data file |
| Open dashboard tabs, with their titles | app data file |
| Whether the online base map is on | app data file |
| Whether DuckLocal checks for updates at launch | app data file |
| Recently opened dashboards (the sidebar's Dashboards) | app data file |
| Not remembered | Notes |
|---|---|
| The results panel contents | in memory only — rerun the query |
| Which database file is open | each launch starts in memory unless you choose a database file |
| Window size and position | fixed at 1440×900, minimum 960×600 |
| Sidebar and results panel sizes | fixed per launch |
| The results filter | in memory only |
| What a dashboard's filters have picked | in memory only; kept across a reload of the tab |
| The theme | always starts light — see below |
| S3 credentials | session-only by design |
The theme is the odd one out: the language toggle persists, the theme toggle does not, and every launch begins in light mode.
Network
DuckLocal makes no network request on its own until you turn one on. There are two switches, both off at first, plus the things you ask for directly:
| Request | When | What leaves the machine |
|---|---|---|
| Online base map | Once turned on, whenever a map draws | Which tiles are wanted: roughly the area and zoom being viewed |
| Update check | When you click the version, or at launch once turned on | One request to dl.ducklocal.app for the latest release's version; when there is a newer one, the download of its package |
| S3 | When you configure S3 and query it | Your requests to the store you configured |
| Extensions | When you click Install or Update, or run INSTALL | A download from DuckDB's extension repository |
| Remote data in SQL | When SQL names https://, s3:// or a remote database, including a dashboard's SQL when it opens. Needs the extension already installed | What the SQL asks for, including anything written into the address |
There is no telemetry, and apart from SQL you run, none of these sends a row of your data. SQL does what it says: an address can carry values from your tables. So once httpfs is installed, a .dash file from someone you don't trust can send data when you open it. Network and privacy lists every path and how to check it yourself.
Online base map
Map charts — in a dashboard or the results' Chart tab — can draw OpenStreetMap tiles under their points. View → Online base map (OpenStreetMap) turns it on and off, and the choice is remembered (the map_tiles setting, on or off). It starts off. Only the requested tiles leave the machine — roughly the area and zoom you are viewing — never a row of data.
Fetching follows the OpenStreetMap Foundation's tile policy: an identifying User-Agent, at most two requests at a time, tiles reused from the cache for a week, no bulk prefetch, and the attribution on the map. For heavier use, set map_tile_url in the settings table to another server's {z}/{x}/{y} URL template.
Update check
The status bar ends with DuckLocal's version — DuckLocal 0.3.0. Click it to check dl.ducklocal.app for the latest release:
- Up to date — the version you run is the latest.
- Downloading v0.3.1… — there is a newer release, and DuckLocal is downloading it. The package is checked against the release's published size and SHA-256 — on macOS, also against the signature of the app you are running — before it is unpacked.
- Restart to update to v0.3.1 — the new version is ready. Click it to quit, install and reopen; otherwise it installs the next time you quit DuckLocal.
- Update available: v0.3.1 — a newer release that this copy cannot install itself: a build you compiled, or an app in a folder it may not write to. Click it to download the package, and install it the way you installed this one.
- Update check failed — hover it for the reason (offline, a proxy, a download that did not match its checksum); click to try again.
Updates come from dl.ducklocal.app, the same packages as the GitHub release, served from a mirror that is fast in mainland China too.
On macOS the DuckLocal menu has the same check, as Check for Updates…, and Check for Updates at Launch, which checks once each time the app starts. It is off until you turn it on (the update_check setting, on or off). Until then, DuckLocal checks only when you click.
Language
The EN / 中 button in the title bar switches the interface language immediately and records the choice.
On first run — before any setting is stored — the language is taken from the system locale: LC_ALL or LANG containing zh selects Chinese, anything else selects English. An unrecognized stored value falls back to Chinese.
A few strings are deliberately not translated: DuckLocal, the S3 and EXPLAIN button labels, the EN / 中 toggle, and the credential placeholders. Engine and network error messages are surfaced verbatim and are always in English, whatever the interface language is.
Themes
The sun/moon button toggles between the light and dark theme. There is no theme picker and no theme file to edit — the two modes are what you get.
Interface size
Text, icons and controls scale together, in four steps:
| Size | Base text | Editor text |
|---|---|---|
| Small | 13px | 12px |
| Default | 14px | 13px |
| Large | 16px | 15px |
| Extra large | 18px | 17px |
Choose one from the Aa button in the title bar, or step through them with ⌘+ (larger), ⌘− (smaller) and ⌘0 (back to default) — these work wherever the focus is, the SQL editor included. The choice is remembered, and survives switching between light and dark.
Panel sizes you dragged, and the height of a dashboard's plots, stay in pixels: they are yours to adjust, not the interface's.
Resetting
To start over — clearing history, registered files, attached databases, remembered tabs and every setting — quit DuckLocal and remove its app data directory:
rm -rf ~/Library/Application\ Support/DuckLocal # macOS
rm -rf ~/.local/share/ducklocal # LinuxOn Windows, delete %APPDATA%\DuckLocal.
The next launch creates it fresh. Your data files are never affected by this, only DuckLocal's own records.
Troubleshooting
Symptoms, causes and fixes are collected on the Troubleshooting page.