|
| 1 | +/** |
| 2 | + * Shared guards for file-backed drivers (DuckDB, SQLite). |
| 3 | + * |
| 4 | + * Both engines create an empty database when asked to open a file that does |
| 5 | + * not exist. For a warehouse connection that is never what the caller wants: |
| 6 | + * a mistyped or mis-resolved path then yields a working connector over an |
| 7 | + * empty database, so every query succeeds and returns nothing. An agent handed |
| 8 | + * that result reports "no tables" instead of an error. |
| 9 | + * |
| 10 | + * Opening a store is therefore read-or-fail by default. Creation is opt-in via |
| 11 | + * `create: true`, which the tools that deliberately materialize a local store |
| 12 | + * (local test scratch databases, schema sync targets) pass explicitly. |
| 13 | + */ |
| 14 | + |
| 15 | +import * as fs from "fs" |
| 16 | +import type { ConnectionConfig } from "./types" |
| 17 | + |
| 18 | +/** |
| 19 | + * Whether `dbPath` names a file on the local filesystem, and so can be |
| 20 | + * existence-checked before the driver opens it. |
| 21 | + * |
| 22 | + * Only the exact string `:memory:` is an in-memory database. Both engines |
| 23 | + * treat `:memory:named` — and any other colon-prefixed name — as an ordinary |
| 24 | + * (if oddly named) file: DuckDB really does write a file called |
| 25 | + * `:memory:named`, so those must stay inside the guard. An empty path is |
| 26 | + * DuckDB's in-memory database and SQLite's anonymous temporary one; neither |
| 27 | + * touches disk. |
| 28 | + * |
| 29 | + * A scheme-qualified target is not a local file: MotherDuck (`md:`), object |
| 30 | + * storage (`s3://`), DuckLake, and any other scheme a DuckDB extension |
| 31 | + * provides. Those are left to the driver, which reports an unknown scheme as a |
| 32 | + * missing-extension error rather than silently creating anything. The pattern |
| 33 | + * requires two or more characters before the colon so a Windows drive letter |
| 34 | + * (`C:\data\wh.duckdb`) stays a path. |
| 35 | + */ |
| 36 | +export function isLocalFilePath(dbPath: string): boolean { |
| 37 | + if (dbPath === "" || dbPath === ":memory:") return false |
| 38 | + if (/^[a-zA-Z][a-zA-Z0-9+.-]+:/.test(dbPath)) return false |
| 39 | + return true |
| 40 | +} |
| 41 | + |
| 42 | +/** |
| 43 | + * Split a relative SQLite `file:` URI into its path and its `?query`/`#fragment` |
| 44 | + * suffix, so the path can be absolutized and the suffix put back untouched. |
| 45 | + * |
| 46 | + * `bun:sqlite` opens with `SQLITE_OPEN_URI`, so `file:warehouse.db` resolves |
| 47 | + * against the process working directory — the same hazard a bare relative path |
| 48 | + * has, wearing a scheme, and a worse one: the create-on-open guard cannot catch |
| 49 | + * it, because the failure is opening the *wrong existing* database rather than |
| 50 | + * making a new empty one. `file:warehouse.db?mode=ro` and `file:my%20db.db` |
| 51 | + * follow cwd exactly the same way, so they are in scope too. The path keeps its |
| 52 | + * percent-encoding; only the directory in front of it changes. |
| 53 | + * |
| 54 | + * Returns undefined for the forms that are already unambiguous or that this |
| 55 | + * does not model: the absolute forms (`file:/abs`, `file:///abs`), an authority |
| 56 | + * (`file://host/…`), an empty path (`file:` or `file:?mode=memory`, which is a |
| 57 | + * temporary database, not a file), and a colon-led path — `file::memory:` is |
| 58 | + * SQLite's in-memory URI, and absolutizing it would turn an in-memory database |
| 59 | + * into a file on disk. A real file whose name starts with a colon is written |
| 60 | + * `file:%3A…` in URI form, which is not colon-led and so still resolves. |
| 61 | + * |
| 62 | + * The scheme match is case-SENSITIVE, deliberately. SQLite recognises only a |
| 63 | + * lowercase `file:` as a URI; `FILE:warehouse.db` is a literal filename that |
| 64 | + * happens to contain a colon. Matching case-insensitively would rewrite that |
| 65 | + * name into a different path and open a different database. |
| 66 | + */ |
| 67 | +export function parseRelativeFileUri(dbPath: string): { path: string; suffix: string } | undefined { |
| 68 | + const match = /^file:(?![/?#:])([^?#]+)([?#].*)?$/.exec(dbPath) |
| 69 | + if (!match) return undefined |
| 70 | + return { path: match[1]!, suffix: match[2] ?? "" } |
| 71 | +} |
| 72 | + |
| 73 | +/** Whether the caller explicitly opted in to creating the store. */ |
| 74 | +export function allowsCreate(config: ConnectionConfig): boolean { |
| 75 | + return config.create === true |
| 76 | +} |
| 77 | + |
| 78 | +/** |
| 79 | + * Throw unless the store is safe to open: it already exists, the caller opted |
| 80 | + * in to creating it, or the path is not a local file at all. |
| 81 | + * |
| 82 | + * @param engine Human-readable engine name used in the error message. |
| 83 | + * @param allowCreate Whether this open will actually create the store. Defaults |
| 84 | + * to the config's `create` flag; a driver passes it explicitly when its own |
| 85 | + * options can veto creation — SQLite never creates a read-only connection. |
| 86 | + */ |
| 87 | +export function assertStoreExists( |
| 88 | + config: ConnectionConfig, |
| 89 | + dbPath: string, |
| 90 | + engine: string, |
| 91 | + allowCreate: boolean = allowsCreate(config), |
| 92 | +): void { |
| 93 | + if (allowCreate) return |
| 94 | + if (!isLocalFilePath(dbPath)) return |
| 95 | + if (fs.existsSync(dbPath)) return |
| 96 | + throw new Error( |
| 97 | + `${engine} database file not found: "${dbPath}". ` + |
| 98 | + `Opening a warehouse connection never creates the database — an empty store would answer every query with no rows. ` + |
| 99 | + `Check the "path" in your connection config (relative paths resolve against the config file's directory, not the current directory), ` + |
| 100 | + `or pass "create": true if this store is meant to be created.`, |
| 101 | + ) |
| 102 | +} |
0 commit comments