|
| 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 | + * The filesystem path inside a SQLite `file:` URI, when that path is relative. |
| 44 | + * |
| 45 | + * `bun:sqlite` opens with `SQLITE_OPEN_URI`, so `file:warehouse.db` resolves |
| 46 | + * against the process working directory — the same hazard a bare relative path |
| 47 | + * has, wearing a scheme, and one the create-on-open guard does not catch |
| 48 | + * because it can still open the *wrong existing* database. |
| 49 | + * |
| 50 | + * Returns undefined for anything this helper will not rewrite safely: the |
| 51 | + * absolute forms (`file:/abs`, `file:///abs`), an authority (`file://host/…`), |
| 52 | + * and any URI carrying a query or fragment (`?mode=ro`), whose meaning depends |
| 53 | + * on parameters this does not try to reproduce. |
| 54 | + */ |
| 55 | +export function relativeFileUriPath(dbPath: string): string | undefined { |
| 56 | + return /^file:(?![/?#])([^?#]+)$/i.exec(dbPath)?.[1] |
| 57 | +} |
| 58 | + |
| 59 | +/** Whether the caller explicitly opted in to creating the store. */ |
| 60 | +export function allowsCreate(config: ConnectionConfig): boolean { |
| 61 | + return config.create === true |
| 62 | +} |
| 63 | + |
| 64 | +/** |
| 65 | + * Throw unless the store is safe to open: it already exists, the caller opted |
| 66 | + * in to creating it, or the path is not a local file at all. |
| 67 | + * |
| 68 | + * @param engine Human-readable engine name used in the error message. |
| 69 | + * @param allowCreate Whether this open will actually create the store. Defaults |
| 70 | + * to the config's `create` flag; a driver passes it explicitly when its own |
| 71 | + * options can veto creation — SQLite never creates a read-only connection. |
| 72 | + */ |
| 73 | +export function assertStoreExists( |
| 74 | + config: ConnectionConfig, |
| 75 | + dbPath: string, |
| 76 | + engine: string, |
| 77 | + allowCreate: boolean = allowsCreate(config), |
| 78 | +): void { |
| 79 | + if (allowCreate) return |
| 80 | + if (!isLocalFilePath(dbPath)) return |
| 81 | + if (fs.existsSync(dbPath)) return |
| 82 | + throw new Error( |
| 83 | + `${engine} database file not found: "${dbPath}". ` + |
| 84 | + `Opening a warehouse connection never creates the database — an empty store would answer every query with no rows. ` + |
| 85 | + `Check the "path" in your connection config (relative paths resolve against the config file's directory, not the current directory), ` + |
| 86 | + `or pass "create": true if this store is meant to be created.`, |
| 87 | + ) |
| 88 | +} |
0 commit comments