turbine-orm 0.19.0 → 0.19.1

package/README.md

@@ -13,7 +13,7 @@ npm install turbine-orm
 Prisma ships a 1.6 MB WASM query engine. Drizzle ships zero runtime but no Studio, no typed errors, no migration checksums. Turbine ships **one dependency (`pg`) and no engine binary**, and bundles six things no other TS ORM has together:
 
 1. **One runtime dependency (`pg`).** No engine binary, no WASM adapter, no adapter packages to keep in lockstep. The main entry bundles to ~30 KB gzipped (~109 KB minified); the edge entry to ~21 KB gzipped. Prisma's WASM query engine alone is 1.6 MB.
-2. **Built-in read-only Studio.** `npx turbine studio` spins up a loopback-bound web UI with 192-bit auth tokens, `BEGIN READ ONLY` transactions, and a statement-stacking guard. The only TS ORM Studio that physically cannot mutate your database. DBA-approvable.
+2. **Built-in read-only Studio.** `npx turbine studio` spins up a loopback-bound web UI with 192-bit auth tokens, `BEGIN READ ONLY` transactions, and — since v0.19 — no raw-SQL surface at all: queries are composed in the ORM's own validated builder. The only TS ORM Studio that physically cannot mutate your database. DBA-approvable.
 3. **PII-safe error messages.** Turbine errors show WHERE keys, not values. A `UniqueConstraintError` says which column violated the constraint — never the actual user data. Safe to log, safe to surface to monitoring, no scrubbing needed.
 4. **SQL-first migrations with drift detection.** Write real SQL. SHA-256 checksums catch modified migration files. `pg_try_advisory_lock()` prevents concurrent runs. Each migration in its own transaction. No shadow database, no magic DSL.
 5. **Edge-native — one import swap.** `turbineHttp(pool, schema)` — same API on Neon, Vercel Postgres, Cloudflare Hyperdrive, Supabase. No WASM bundle, no adapter package, no separate serverless build.
@@ -614,7 +614,7 @@ npx turbine migrate status
 
 ## Studio
 
-The only Postgres ORM with a Studio your DBA will approve. `turbine studio` launches a local, read-only web UI for exploring your database — no mutations, no writes, no way around the transaction guard.
+The only Postgres ORM with a Studio your DBA will approve. `turbine studio` launches a local, read-only web UI for exploring your database — no mutations, no writes, and since v0.19 **no raw-SQL surface at all**: every query is composed visually in the ORM and compiled by the same validated query builder your application uses.
 
 ```bash
 DATABASE_URL=postgres://user:pass@localhost:5432/mydb npx turbine studio
@@ -624,19 +624,19 @@ npx turbine studio --port 5173 --host 127.0.0.1 --no-open
 
 **Features**
 
-- **Data / Schema / SQL / Builder tabs.** Browse rows, inspect tables and relations, run ad-hoc `SELECT`s, or compose queries visually with a live TypeScript preview.
-- **Saved queries.** Named SQL snippets persisted to `.turbine/studio-queries.json` — share them across runs without committing them.
+- **Query / Data / Schema tabs.** Compose queries visually, browse rows, and inspect tables and relations.
+- **ORM-native query composer.** The Query tab builds a real `findMany` — drill into relations (`with`) to any depth, pick fields (`select`/`omit`), add filters (`where`), `orderBy`, and `limit` at every level — with a live TypeScript preview of the exact call to copy into your codebase.
+- **Saved queries.** Named builder queries persisted to `.turbine/studio-queries.json` — share them across runs without committing them.
 - **Cmd+K command palette.** Jump to any table, tab, or saved query in one keystroke.
 - **Full-text search across rows.** The Data tab supports substring search across every text column of the current table.
-- **Visual query composer.** The Builder tab lets you click together `where` / `orderBy` / `with` / `limit` clauses and renders the matching `db.table.findMany(...)` TypeScript in real time — copy it into your codebase.
 
 **Security posture (read-only by design)**
 
+- **No SQL input surface.** There is nothing to inject into — builder requests are validated identifier-by-identifier against the introspected schema, and every value is bound as a `$N` parameter.
 - **Loopback by default** (`127.0.0.1`) with a loud warning if you bind to a non-loopback address.
 - **Per-process auth token** — 24 random bytes of hex, stored in a `SameSite=Strict` `HttpOnly` cookie.
-- **Every query runs inside `BEGIN READ ONLY` + `SET LOCAL statement_timeout = '30s'`.** Writes are physically impossible at the transaction level.
-- **SELECT/WITH-only SQL parser** strips comments and rejects non-trailing semicolons, blocking statement-stacking attacks.
-- **Security headers on every response** — `X-Content-Type-Options`, `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer`.
+- **Every query runs inside `BEGIN READ ONLY`** with a 30s transaction-local statement timeout (parameterized `set_config`). Writes are physically impossible at the transaction level.
+- **Security headers on every response** — CSP, `X-Content-Type-Options`, `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer` — plus per-session rate limiting and cross-origin refusal.
 
 ## Serverless / Edge
 

package/dist/adapters/index.d.ts

@@ -55,8 +55,9 @@ export interface DatabaseAdapter {
     introspectionOverrides?: Partial<IntrospectionOverrides>;
     /**
      * Generate the SQL to set a statement timeout within a transaction.
-     * PostgreSQL uses `SET LOCAL statement_timeout = $1`.
-     * CockroachDB uses `SET transaction_timeout = $1` (v23.1+).
+     * PostgreSQL uses `SELECT set_config('statement_timeout', $1, true)`.
+     * CockroachDB uses `SELECT set_config('transaction_timeout', $1, true)` (v23.1+).
+     * (`SET LOCAL ... = $1` is a syntax error — SET takes no bind params.)
      *
      * @param seconds — timeout in seconds
      * @returns an object with the parameterized SQL and its bound values

package/dist/cjs/cli/index.js

@@ -167,6 +167,15 @@ function failMissingTsLoader(filePath, reason) {
         console.log(`  ${(0, ui_js_1.dim)('Your Node.js version does not support')} ${(0, ui_js_1.cyan)('module.register()')}.`);
         console.log(`  ${(0, ui_js_1.dim)('Upgrade to Node.js')} ${(0, ui_js_1.cyan)('20.6+')} ${(0, ui_js_1.dim)('or use a')} ${(0, ui_js_1.cyan)('.js')} ${(0, ui_js_1.dim)('/')} ${(0, ui_js_1.cyan)('.mjs')} ${(0, ui_js_1.dim)('config file.')}`);
     }
+    else if (reason === 'failed') {
+        // tsx IS installed but registering its loader threw. Report the real
+        // cause — telling the user to install tsx here would be a misdiagnosis.
+        console.log(`  ${(0, ui_js_1.dim)('tsx is installed, but registering its TypeScript loader failed:')}`);
+        (0, ui_js_1.newline)();
+        console.log(`    ${(0, loader_js_1.getTsLoaderError)() ?? '(unknown error)'}`);
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.dim)('Try upgrading tsx:')} ${(0, ui_js_1.cyan)('npm install --save-dev tsx@latest')}${(0, ui_js_1.dim)(', or rename your file to')} ${(0, ui_js_1.cyan)('.mjs')}.`);
+    }
     else {
         console.log(`  ${(0, ui_js_1.dim)('Loading .ts config / schema files requires')} ${(0, ui_js_1.cyan)('tsx')} ${(0, ui_js_1.dim)('to be installed.')}`);
         (0, ui_js_1.newline)();
@@ -210,7 +219,7 @@ async function loadSchemaFile(schemaFile) {
     // ERR_UNKNOWN_FILE_EXTENSION for `.ts`.
     if ((0, loader_js_1.needsTsLoader)(absPath)) {
         const status = await (0, loader_js_1.registerTsLoader)();
-        if (status === 'missing' || status === 'unsupported') {
+        if (status === 'missing' || status === 'unsupported' || status === 'failed') {
             failMissingTsLoader(schemaFile, status);
         }
     }
@@ -346,7 +355,7 @@ export default defineSchema({
   //   id: { type: 'serial', primaryKey: true },
   //   email: { type: 'text', notNull: true, unique: true },
   //   name: { type: 'text', notNull: true },
-  //   created_at: { type: 'timestamptz', default: 'NOW()' },
+  //   created_at: { type: 'timestamp', default: 'NOW()' },
   // },
 });
 `, 'utf-8');
@@ -409,6 +418,9 @@ export default defineSchema({
             console.log(`     ${(0, ui_js_1.dim)('or create a')} ${(0, ui_js_1.cyan)('.env')} ${(0, ui_js_1.dim)('file with')} ${(0, ui_js_1.cyan)('DATABASE_URL=postgres://...')}`);
         }
         console.log(`  ${(0, ui_js_1.dim)('2.')} Run ${(0, ui_js_1.cyan)('npx turbine generate')} to introspect your DB`);
+        if (!(0, loader_js_1.canResolveTsx)()) {
+            console.log(`     ${(0, ui_js_1.dim)('Note: the TypeScript config requires')} ${(0, ui_js_1.cyan)('tsx')} ${(0, ui_js_1.dim)('—')} ${(0, ui_js_1.cyan)('npm install --save-dev tsx')}`);
+        }
     }
     else {
         console.log(`  ${(0, ui_js_1.dim)('1.')} Import the generated client:`);
@@ -1249,7 +1261,17 @@ function showVersion() {
     // Using process.argv[1] instead of import.meta.url so the same code compiles
     // cleanly for both the ESM and CJS builds.
     try {
-        let dir = (0, node_path_1.dirname)(process.argv[1] ?? '');
+        // Resolve symlinks first: `npx turbine` runs via node_modules/.bin/turbine,
+        // a symlink whose dirname would walk the CONSUMER's tree and never find
+        // turbine-orm's package.json (printing no version number at all).
+        let entry = process.argv[1] ?? '';
+        try {
+            entry = (0, node_fs_1.realpathSync)(entry);
+        }
+        catch {
+            // keep the raw path if realpath fails (e.g. deleted cwd)
+        }
+        let dir = (0, node_path_1.dirname)(entry);
         for (let i = 0; i < 6; i++) {
             const candidate = (0, node_path_1.resolve)(dir, 'package.json');
             if ((0, node_fs_1.existsSync)(candidate)) {
@@ -1297,7 +1319,7 @@ async function main() {
     const configPath = (0, config_js_1.findConfigFile)();
     if ((0, loader_js_1.needsTsLoader)(configPath)) {
         const status = await (0, loader_js_1.registerTsLoader)();
-        if (status === 'missing' || status === 'unsupported') {
+        if (status === 'missing' || status === 'unsupported' || status === 'failed') {
             failMissingTsLoader(configPath ?? 'turbine.config.ts', status);
         }
     }

package/dist/cjs/cli/loader.js

@@ -9,9 +9,18 @@
  *
  * Strategy:
  *   1. If the file we're about to import ends in `.ts` / `.mts` / `.cts`,
- *      probe whether `tsx/esm` is resolvable from the user's CWD.
- *   2. If yes, call `module.register('tsx/esm', ...)` ONCE per process.
- *   3. If no, surface an actionable error telling the user to install `tsx`.
+ *      probe whether `tsx` is resolvable from the user's CWD.
+ *   2. Prefer tsx's supported programmatic API, `tsx/esm/api`'s `register()`.
+ *      Calling Node's `module.register('tsx/esm', ...)` directly throws
+ *      "tsx must be loaded with --import instead of --loader" on every Node
+ *      version that has `module.register()` (>= 20.6) — tsx's hook file
+ *      guards against being loaded that way. The `tsx/esm/api` entry point
+ *      is the documented path and works everywhere `module.register()` does.
+ *   3. Fall back to `module.register('tsx/esm', ...)` only for very old tsx
+ *      versions (< 4.0) that predate `tsx/esm/api`.
+ *   4. If tsx isn't installed, or registration genuinely fails, surface an
+ *      actionable error — including the REAL underlying error message, never
+ *      a misdiagnosed "tsx is not installed".
  *
  * `tsx` is intentionally NOT a runtime dependency — many projects already
  * have it, and adding a heavy dev tool to a 1-dependency ORM would be silly.
@@ -52,6 +61,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.needsTsLoader = needsTsLoader;
 exports.canResolveTsx = canResolveTsx;
+exports.getTsLoaderError = getTsLoaderError;
 exports.registerTsLoader = registerTsLoader;
 exports._resetTsLoaderStateForTests = _resetTsLoaderStateForTests;
 const node_module_1 = require("node:module");
@@ -89,6 +99,14 @@ function canResolveTsx(resolver) {
     }
 }
 let tsLoaderState = null;
+let tsLoaderError = null;
+/**
+ * The underlying error message from the last failed registration attempt,
+ * or null. Lets the CLI report the REAL cause instead of guessing.
+ */
+function getTsLoaderError() {
+    return tsLoaderError;
+}
 /**
  * Register the tsx ESM loader so subsequent dynamic imports of `.ts` files
  * work. Safe to call multiple times — internal flag prevents double registration.
@@ -96,17 +114,51 @@ let tsLoaderState = null;
  * Returns:
  *   - 'registered'  loader was successfully registered this call
  *   - 'already'     a loader was previously registered (idempotent)
- *   - 'unsupported' Node lacks `module.register()` (Node < 20.6)
+ *   - 'unsupported' Node lacks `module.register()` (Node < 20.6) and tsx has
+ *                   no programmatic API to fall back to
  *   - 'missing'     `tsx` is not installed in the user's project
+ *   - 'failed'      tsx IS installed but registration threw — see
+ *                   {@link getTsLoaderError} for the underlying message
  */
 async function registerTsLoader() {
     if (tsLoaderState === 'registered' || tsLoaderState === 'already') {
         return 'already';
     }
+    const userRequire = (0, node_module_1.createRequire)(`${process.cwd()}/`);
+    // Preferred: tsx's supported programmatic API (tsx >= 4.0).
+    let apiPath = null;
+    try {
+        apiPath = userRequire.resolve('tsx/esm/api');
+    }
+    catch {
+        apiPath = null;
+    }
+    if (apiPath) {
+        try {
+            const api = (await Promise.resolve(`${(0, node_url_1.pathToFileURL)(apiPath).href}`).then(s => __importStar(require(s))));
+            if (typeof api.register !== 'function') {
+                throw new Error(`tsx/esm/api resolved at ${apiPath} but exports no register() function`);
+            }
+            api.register();
+            tsLoaderState = 'registered';
+            tsLoaderError = null;
+            return 'registered';
+        }
+        catch (err) {
+            tsLoaderState = 'failed';
+            tsLoaderError = err instanceof Error ? err.message : String(err);
+            return 'failed';
+        }
+    }
+    // tsx/esm/api not resolvable — is tsx installed at all?
     if (!canResolveTsx()) {
         tsLoaderState = 'missing';
         return 'missing';
     }
+    // Legacy fallback for tsx < 4.0 (no tsx/esm/api): Node's module.register.
+    // On tsx >= 4.19 this path throws ("tsx must be loaded with --import
+    // instead of --loader") — but those versions all ship tsx/esm/api, so we
+    // only land here for genuinely old installs.
     try {
         const mod = await Promise.resolve().then(() => __importStar(require('node:module')));
         const register = mod.register;
@@ -116,14 +168,17 @@ async function registerTsLoader() {
         }
         register('tsx/esm', (0, node_url_1.pathToFileURL)(`${process.cwd()}/`));
         tsLoaderState = 'registered';
+        tsLoaderError = null;
         return 'registered';
     }
-    catch {
-        tsLoaderState = 'missing';
-        return 'missing';
+    catch (err) {
+        tsLoaderState = 'failed';
+        tsLoaderError = err instanceof Error ? err.message : String(err);
+        return 'failed';
     }
 }
 /** Reset the loader state — used by unit tests only. */
 function _resetTsLoaderStateForTests() {
     tsLoaderState = null;
+    tsLoaderError = null;
 }

package/dist/cjs/cli/studio.js

@@ -3,15 +3,20 @@
  * turbine-orm CLI — Studio
  *
  * A local, read-only web UI for browsing databases, exploring relations,
- * and running SELECT queries. Pure Node (built-in `http` module), no
- * runtime dependencies beyond `pg`, bound to 127.0.0.1 only.
+ * and composing queries visually. ORM-native since v0.19: there is no
+ * raw-SQL input surface — the Query tab builds `findMany` args that are
+ * validated against introspected metadata and compiled by QueryInterface
+ * (`/api/builder`). Pure Node (built-in `http` module), no runtime
+ * dependencies beyond `pg`, bound to 127.0.0.1 only.
  *
  * Security model:
  *   • Bind 127.0.0.1 only (never 0.0.0.0 — no LAN exposure)
  *   • Random auth token generated per process, required in Cookie header
- *   • SELECT/WITH-only guard on the query endpoint
+ *   • No SQL input surface at all — every identifier in a builder request is
+ *     validated against the introspected schema; all values are $N params
  *   • Every query runs in a READ ONLY transaction (belt-and-suspenders)
- *   • 30s statement timeout
+ *   • 30s statement timeout via parameterized set_config()
+ *   • Per-session rate limiting, CSP + security headers, cross-origin refusal
  *
  * Not implemented (deliberately): row editing, DDL, destructive operations.
  * Studio is for inspection. Use the CLI, migrate, or raw SQL for writes.
@@ -420,6 +425,11 @@ async function apiBuilder(req, res, ctx) {
     try {
         await client.query('BEGIN READ ONLY');
         await client.query(ctx.statementTimeout.sql, ctx.statementTimeout.params);
+        // QueryInterface emits unqualified table identifiers, which resolve via
+        // the connection's search_path. Pin it to the configured --schema so the
+        // Query tab reads the same schema as the Data tab (set_config is
+        // transaction-local and fully parameterized).
+        await client.query(`SELECT set_config('search_path', $1, true)`, [ctx.options.schema]);
         const started = Date.now();
         const result = await client.query(deferred.sql, deferred.params);
         const elapsedMs = Date.now() - started;
@@ -448,6 +458,8 @@ async function apiBuilder(req, res, ctx) {
 function savedQueriesPath(ctx) {
     return (0, node_path_1.resolve)(ctx.stateDir, 'studio-queries.json');
 }
+/** One-shot flag so the legacy saved-query notice isn't logged on every request. */
+let legacyDropNoticeShown = false;
 function loadSavedQueries(ctx) {
     const file = savedQueriesPath(ctx);
     if (!(0, node_fs_1.existsSync)(file))
@@ -457,8 +469,16 @@ function loadSavedQueries(ctx) {
         const parsed = JSON.parse(raw);
         if (!parsed.queries || !Array.isArray(parsed.queries))
             return { version: 1, queries: [] };
-        // Drop any legacy raw-SQL entries — Studio is builder-only now.
+        // Drop any legacy raw-SQL entries — Studio is builder-only now. Tell the
+        // user instead of silently discarding their saved work (the file on disk
+        // is only rewritten when a new query is saved, so this is recoverable).
         const queries = parsed.queries.filter((q) => q && q.kind === 'builder');
+        const dropped = parsed.queries.length - queries.length;
+        if (dropped > 0 && !legacyDropNoticeShown) {
+            legacyDropNoticeShown = true;
+            console.warn(`[turbine studio] Ignoring ${dropped} legacy raw-SQL saved quer${dropped === 1 ? 'y' : 'ies'} in ${file} — ` +
+                'Studio is builder-only since v0.19. The entries remain in the file until a new query is saved.');
+        }
         return { version: 1, queries };
     }
     catch {

package/dist/cjs/client.js

@@ -210,6 +210,14 @@ class TurbineClient {
     /** Active LISTEN subscriptions — torn down on disconnect() so it never hangs */
     activeSubscriptions = new Set();
     constructor(config = {}, schema) {
+        // Constructing without schema metadata previously crashed deep in the
+        // constructor with an opaque "Cannot read properties of undefined
+        // (reading 'tables')". Fail fast with an actionable message instead.
+        if (!schema || typeof schema !== 'object' || !schema.tables) {
+            throw new errors_js_1.ValidationError('[turbine] TurbineClient requires schema metadata as its second argument. ' +
+                'Run `npx turbine generate` and use the generated client (`turbine()` from your output dir), ' +
+                'or pass the generated `schemaMetadata` object: new TurbineClient(config, schemaMetadata).');
+        }
         /**
          * Parse int8 (bigint, OID 20) as JavaScript number instead of string.
          * Safe for values up to Number.MAX_SAFE_INTEGER (9,007,199,254,740,991).