|
| 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 store path a file-backed connection names, or a loud failure. |
| 44 | + * |
| 45 | + * Both drivers used to read `(config.path as string) ?? ":memory:"`. That turns |
| 46 | + * ANY failure to carry a path — a config the registry never loaded, a field |
| 47 | + * under the wrong name, a lookup that fell through — into a successful |
| 48 | + * connection over an empty in-memory database. Every query then returns no rows |
| 49 | + * and no error, which reads as a healthy warehouse that happens to be empty. |
| 50 | + * |
| 51 | + * It is a worse failure than creating a store on disk: a stray file can at |
| 52 | + * least be found afterwards, whereas an in-memory database leaves nothing |
| 53 | + * behind to explain the empty answer. `:memory:` remains available, but only |
| 54 | + * when a caller asks for it by name. |
| 55 | + */ |
| 56 | +export function requireStorePath(config: ConnectionConfig, engine: string): string { |
| 57 | + const value = config.path |
| 58 | + if (typeof value === "string" && value !== "") return value |
| 59 | + throw new Error( |
| 60 | + `${engine} connection is missing its "path". A file-backed warehouse must name its database explicitly — ` + |
| 61 | + `falling back to an in-memory database would answer every query with no rows and no error, ` + |
| 62 | + `which is indistinguishable from a healthy but empty warehouse. ` + |
| 63 | + `Set "path" to the database file, or to ":memory:" if a throwaway empty database is genuinely what you want.`, |
| 64 | + ) |
| 65 | +} |
| 66 | + |
| 67 | +/** Whether the caller explicitly opted in to creating the store. */ |
| 68 | +export function allowsCreate(config: ConnectionConfig): boolean { |
| 69 | + return config.create === true |
| 70 | +} |
| 71 | + |
| 72 | +/** |
| 73 | + * Throw unless the store is safe to open: it already exists, the caller opted |
| 74 | + * in to creating it, or the path is not a local file at all. |
| 75 | + * |
| 76 | + * @param engine Human-readable engine name used in the error message. |
| 77 | + * @param allowCreate Whether this open will actually create the store. Defaults |
| 78 | + * to the config's `create` flag; a driver passes it explicitly when its own |
| 79 | + * options can veto creation — SQLite never creates a read-only connection. |
| 80 | + */ |
| 81 | +export function assertStoreExists( |
| 82 | + config: ConnectionConfig, |
| 83 | + dbPath: string, |
| 84 | + engine: string, |
| 85 | + allowCreate: boolean = allowsCreate(config), |
| 86 | +): void { |
| 87 | + if (allowCreate) return |
| 88 | + if (!isLocalFilePath(dbPath)) return |
| 89 | + if (fs.existsSync(dbPath)) return |
| 90 | + throw new Error( |
| 91 | + `${engine} database file not found: "${dbPath}". ` + |
| 92 | + `Opening a warehouse connection never creates the database — an empty store would answer every query with no rows. ` + |
| 93 | + `Check the "path" in your connection config (relative paths resolve against the config file's directory, not the current directory), ` + |
| 94 | + `or pass "create": true if this store is meant to be created.`, |
| 95 | + ) |
| 96 | +} |
0 commit comments