Skip to content

Commit 7fdbe26

Browse files
anandgupta42claude
andcommitted
docs(drivers): record the bare-scheme-vs-local-filename decision (#1238 last thread)
Documents the maintainer decision on #1238's remaining open thread (file-store.ts:61 — narrowing the bare-scheme exclusion to a closed list broke forwarding for an unlisted custom DuckDB extension's bare-scheme target). Decision: accept the closed-list default. - file-store.ts: expanded the comment at NON_SLASH_REMOTE_SCHEMES to state the fundamental ambiguity (a bare word:target cannot be told apart syntactically from a local filename with a colon), why the closed list was chosen over the broad heuristic (local filenames with colons are the common case; known extensions are enumerable), and the escape hatch (use the extension's scheme:// form, or extend the list when a new extension is adopted). - docs/configure/warehouses.md: new note in the DuckDB section explaining bare word:target values are treated as local files unless the prefix is one of the recognized bare schemes (md:, motherduck:, ducklake:). - docs/drivers.md: one-sentence pointer to the same rule alongside the existing file-backed-driver path notes. Gates: packages/drivers file-store-guard tests 27/27 pass, bun turbo typecheck 13/13 (forced, 0 cached), marker check --base origin/main --strict clean, prettier clean on file-store.ts (the two docs files were already unformatted on origin/main before this change, left as-is). Co-Authored-By: Claude Opus 4.8 <[email protected]> Claude-Session: https://claude.ai/code/session_01VqnuBDGkh1ZT65Ti7e6DHZ
1 parent 7f5ebb9 commit 7fdbe26

3 files changed

Lines changed: 32 additions & 1 deletion

File tree

‎docs/docs/configure/warehouses.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -283,6 +283,15 @@ If you're already authenticated via `gcloud`, omit `credentials_path`:
283283
re-point an existing connection at a different file. Absolute paths are always
284284
safest.
285285

286+
!!! note "Bare `word:target` values are treated as local files"
287+
A `path` shaped like `word:target` with no `//` (for example
288+
`data:warehouse.duckdb`) is treated as an ordinary local filename, not a
289+
remote target — including the exact `word` prefix a DuckDB storage
290+
extension uses. Only a full `scheme://` URI (`s3://...`, `md://...`) or
291+
one of the specific bare schemes DuckDB extensions actually use —
292+
`md:`, `motherduck:`, `ducklake:` — is treated as remote. To target any
293+
other custom storage extension, use its `scheme://` form.
294+
286295
!!! note "Concurrent access"
287296
DuckDB does not support concurrent write access to the same file. If another process holds a write lock, Altimate Code automatically retries the connection in **read-only** mode so you can still query the data. A clear error message is shown if read-only access also fails.
288297

‎docs/docs/drivers.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -194,7 +194,10 @@ MongoDB supports server versions 3.6 through 8.0. Queries use MQL (MongoDB Query
194194
For both file-backed drivers, the database must already exist — connecting never
195195
creates it. Pass `create: true` to create it deliberately. A relative `path`
196196
resolves against the directory of the config that declares it, not the current
197-
working directory. See [Warehouses](configure/warehouses.md#duckdb) for the full rules.
197+
working directory. A bare `word:target` value (no `//`) is treated as a local
198+
filename unless `word` is one of the recognized remote bare schemes
199+
(`md:`, `motherduck:`, `ducklake:`) — use a `scheme://` URI to target any other
200+
storage extension. See [Warehouses](configure/warehouses.md#duckdb) for the full rules.
198201

199202
## SSH Tunneling
200203

‎packages/drivers/src/file-store.ts‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,25 @@ import type { ConnectionConfig } from "./types"
2121
* DuckDB extension schemes that take a bare `scheme:rest` form with no `//`
2222
* — MotherDuck (`md:`) and DuckLake (`ducklake:`) — and so cannot be told
2323
* apart from a local filename by the `://` check below.
24+
*
25+
* Fundamental ambiguity: a bare `word:target` is syntactically identical
26+
* whether `word` is a filename prefix (`data:warehouse.duckdb`, a real local
27+
* file) or a remote extension scheme (`md:my_database`). Nothing in the
28+
* string alone can distinguish them.
29+
*
30+
* Deliberate choice: a closed list, not a broad heuristic. Local filenames
31+
* that happen to contain a colon are the common case here; bare-scheme
32+
* DuckDB extensions are a small, enumerable set. Listing the known ones and
33+
* treating everything else as local is safer than the reverse (treating
34+
* every `word:target` as remote, which misclassified real local files — see
35+
* `isLocalFilePath`'s own comment).
36+
*
37+
* Escape hatch: a custom/future extension whose target uses a bare scheme
38+
* not in this list is NOT forwarded — it's treated as a local path and will
39+
* fail the existence guard. Two ways out: (1) use the extension's `scheme://`
40+
* form if it has one (always forwarded, see the `://` check below), or (2)
41+
* add the new bare scheme to this list once it's an extension the driver
42+
* actually needs to support.
2443
*/
2544
const NON_SLASH_REMOTE_SCHEMES = ["md:", "motherduck:", "ducklake:"]
2645
// altimate_change end

0 commit comments

Comments
 (0)