# Settings and app data

> Where DuckLocal stores its data, what it remembers, the only network requests it can make, interface size, theme and language, and how to reset it.

Source: https://ducklocal.app/docs/settings-and-data

**[中文](zh/settings-and-data.md)**

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](dashboards.md#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`](cli.md#show-work-in-the-running-window)
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](https://github.com/JetSquirrel/DuckLocal/issues).
**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](#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](#update-check) 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 {#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](#online-base-map) | Once turned on, whenever a map draws | Which tiles are wanted: roughly the area and zoom being viewed |
| [Update check](#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](s3.md) | 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](https://github.com/JetSquirrel/DuckLocal/blob/main/docs/network-and-privacy.md) lists every path and how to check it yourself.

## Online base map {#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 {#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](https://github.com/JetSquirrel/DuckLocal/releases/latest),
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 {#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:

```bash
rm -rf ~/Library/Application\ Support/DuckLocal   # macOS
rm -rf ~/.local/share/ducklocal                  # Linux
```

On 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](troubleshooting.md) page.