|
| 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 | + * Remote and virtual targets a file-backed driver understands but that do not |
| 20 | + * name anything on the local filesystem: MotherDuck, object storage, HTTP, and |
| 21 | + * SQLite's `file:` URI form (which has its own resolution rules). |
| 22 | + * |
| 23 | + * This is a closed list rather than a generic `scheme:` pattern on purpose. A |
| 24 | + * pattern that treats every `word:` prefix as a scheme also swallows real file |
| 25 | + * names — DuckDB writes a file literally called `:memory:named` or `:foo`, and |
| 26 | + * a Windows path is `C:\…` — and each of those would then slip past the guard |
| 27 | + * and be silently created, which is the exact defect this module exists to |
| 28 | + * prevent. Anything not listed here is treated as a local file. |
| 29 | + */ |
| 30 | +const NON_FILE_PREFIXES = [ |
| 31 | + "md:", |
| 32 | + "motherduck:", |
| 33 | + "s3://", |
| 34 | + "gs://", |
| 35 | + "gcs://", |
| 36 | + "r2://", |
| 37 | + "az://", |
| 38 | + "azure://", |
| 39 | + "abfss://", |
| 40 | + "http://", |
| 41 | + "https://", |
| 42 | + "hf://", |
| 43 | + "file:", |
| 44 | +] |
| 45 | + |
| 46 | +/** |
| 47 | + * Whether `dbPath` names a file on the local filesystem, and so can be |
| 48 | + * existence-checked before the driver opens it. |
| 49 | + * |
| 50 | + * Only the exact string `:memory:` is an in-memory database. Both engines |
| 51 | + * treat `:memory:something` as an ordinary (and very oddly named) file, so it |
| 52 | + * must stay inside the guard. An empty path is DuckDB's in-memory database and |
| 53 | + * SQLite's anonymous temporary one; neither touches disk. |
| 54 | + */ |
| 55 | +export function isLocalFilePath(dbPath: string): boolean { |
| 56 | + if (dbPath === "" || dbPath === ":memory:") return false |
| 57 | + return !NON_FILE_PREFIXES.some((prefix) => dbPath.toLowerCase().startsWith(prefix)) |
| 58 | +} |
| 59 | + |
| 60 | +/** Whether the caller explicitly opted in to creating the store. */ |
| 61 | +export function allowsCreate(config: ConnectionConfig): boolean { |
| 62 | + return config.create === true |
| 63 | +} |
| 64 | + |
| 65 | +/** |
| 66 | + * Throw unless the store is safe to open: it already exists, the caller opted |
| 67 | + * in to creating it, or the path is not a local file at all. |
| 68 | + * |
| 69 | + * @param engine Human-readable engine name used in the error message. |
| 70 | + * @param allowCreate Whether this open will actually create the store. Defaults |
| 71 | + * to the config's `create` flag; a driver passes it explicitly when its own |
| 72 | + * options can veto creation — SQLite never creates a read-only connection. |
| 73 | + */ |
| 74 | +export function assertStoreExists( |
| 75 | + config: ConnectionConfig, |
| 76 | + dbPath: string, |
| 77 | + engine: string, |
| 78 | + allowCreate: boolean = allowsCreate(config), |
| 79 | +): void { |
| 80 | + if (allowCreate) return |
| 81 | + if (!isLocalFilePath(dbPath)) return |
| 82 | + if (fs.existsSync(dbPath)) return |
| 83 | + throw new Error( |
| 84 | + `${engine} database file not found: "${dbPath}". ` + |
| 85 | + `Opening a warehouse connection never creates the database — an empty store would answer every query with no rows. ` + |
| 86 | + `Check the "path" in your connection config (relative paths resolve against the config file's directory, not the current directory), ` + |
| 87 | + `or pass "create": true if this store is meant to be created.`, |
| 88 | + ) |
| 89 | +} |
0 commit comments