turbine-orm 0.36.1 → 0.37.0

package/dist/cjs/cli/studio.js

@@ -42,6 +42,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PII_REDACTED = void 0;
 exports.startStudio = startStudio;
 exports.handleRequest = handleRequest;
+exports.apiDemoMode = apiDemoMode;
 exports.apiTableRows = apiTableRows;
 exports.resolveColumnName = resolveColumnName;
 exports.isTextishType = isTextishType;
@@ -60,6 +61,7 @@ const node_path_1 = require("node:path");
 const pg_1 = __importDefault(require("pg"));
 const introspect_js_1 = require("../introspect.js");
 const index_js_1 = require("../query/index.js");
+const studio_demo_js_1 = require("./studio-demo.js");
 const studio_ui_generated_js_1 = require("./studio-ui.generated.js");
 // ---------------------------------------------------------------------------
 // Main entry point
@@ -74,35 +76,55 @@ const studio_ui_generated_js_1 = require("./studio-ui.generated.js");
  *   process.on('SIGINT', () => studio.dispose().then(() => process.exit(0)));
  */
 async function startStudio(options) {
-    const pool = new pg_1.default.Pool({
-        connectionString: options.url,
-        max: 4, // small pool — single-user tool
-        idleTimeoutMillis: 10_000,
-    });
-    // Verify connectivity before starting the server — fail fast.
-    const probe = await pool.connect();
-    try {
-        await probe.query('SELECT 1');
+    const demo = options.demo === true;
+    let pool;
+    let metadata;
+    let dialect;
+    let statementTimeout;
+    if (demo) {
+        // Seeded in-memory SQLite store: no DATABASE_URL, no network. Each launch
+        // starts pristine and nothing is ever persisted.
+        const demoCtx = (0, studio_demo_js_1.createDemoContext)();
+        pool = demoCtx.pool;
+        metadata = demoCtx.metadata;
+        dialect = demoCtx.dialect;
+        // SQLite has no set_config / statement_timeout GUC; a harmless no-op keeps
+        // the shared execution path (which issues this before each query) uniform.
+        statementTimeout = { sql: 'SELECT 1', params: [] };
     }
-    finally {
-        probe.release();
+    else {
+        // pg.Pool satisfies the PgCompatPool contract (same as the external-pool
+        // seam in client.ts); the cast keeps one typed pool field for both modes.
+        pool = new pg_1.default.Pool({
+            connectionString: options.url,
+            max: 4, // small pool — single-user tool
+            idleTimeoutMillis: 10_000,
+        });
+        // Verify connectivity before starting the server — fail fast.
+        const probe = await pool.connect();
+        try {
+            await probe.query('SELECT 1');
+        }
+        finally {
+            probe.release();
+        }
+        metadata = await (0, introspect_js_1.introspect)({
+            connectionString: options.url,
+            schema: options.schema,
+            include: options.include,
+            exclude: options.exclude,
+        });
+        statementTimeout = options.adapter?.statementTimeout?.(30) ?? {
+            // Postgres rejects parameters in `SET LOCAL` (`SET LOCAL ... = $1` is a
+            // syntax error). `set_config(name, value, is_local=true)` is the
+            // parameterizable, transaction-local equivalent and works on every
+            // Postgres-compatible engine.
+            sql: `SELECT set_config('statement_timeout', $1, true)`,
+            params: ['30s'],
+        };
     }
-    const metadata = await (0, introspect_js_1.introspect)({
-        connectionString: options.url,
-        schema: options.schema,
-        include: options.include,
-        exclude: options.exclude,
-    });
     const authToken = (0, node_crypto_1.randomBytes)(24).toString('hex');
     const stateDir = (0, node_path_1.resolve)(options.stateDir ?? '.turbine');
-    const statementTimeout = options.adapter?.statementTimeout?.(30) ?? {
-        // Postgres rejects parameters in `SET LOCAL` (`SET LOCAL ... = $1` is a
-        // syntax error). `set_config(name, value, is_local=true)` is the
-        // parameterizable, transaction-local equivalent and works on every
-        // Postgres-compatible engine.
-        sql: `SELECT set_config('statement_timeout', $1, true)`,
-        params: ['30s'],
-    };
     const rateLimiter = new Map();
     const ctx = {
         pool,
@@ -112,8 +134,12 @@ async function startStudio(options) {
         stateDir,
         statementTimeout,
         rateLimiter,
-        writable: options.write === true,
-        showPii: options.showPii === true,
+        // Demo always boots read-only + PII redacted; the in-UI switcher flips these
+        // live. Non-demo honors the CLI flags.
+        writable: demo ? false : options.write === true,
+        showPii: demo ? false : options.showPii === true,
+        demo,
+        dialect,
     };
     const server = (0, node_http_1.createServer)((req, res) => {
         handleRequest(req, res, ctx).catch((err) => {
@@ -246,9 +272,40 @@ async function handleRequest(req, res, ctx) {
         if (op === 'delete')
             return apiRowWrite(req, res, ctx, 'delete');
     }
+    // Demo mode switcher: ONLY exists in demo mode (404 otherwise). Flips the live
+    // read-only / PII / write toggles on the in-memory store. State-changing, so it
+    // requires a matching Origin like the write routes.
+    if (ctx.demo && pathname === '/api/demo/mode' && req.method === 'POST') {
+        if (origin !== expectedOrigin) {
+            sendJson(res, 403, { error: 'a matching Origin header is required for mode changes' });
+            return;
+        }
+        return apiDemoMode(req, res, ctx);
+    }
     sendJson(res, 404, { error: 'not found' });
 }
 // ---------------------------------------------------------------------------
+// API: /api/demo/mode: live mode switcher (demo mode only)
+//
+// Mutates the shared StudioContext so the change applies to every subsequent
+// request: `writable` gates the (already-registered) `/api/row/*` routes and the
+// UI's write affordances; `showPii` toggles server-side PII redaction. The two
+// are independent toggles. The UI re-fetches `/api/schema` afterwards to re-read
+// the effective state.
+// ---------------------------------------------------------------------------
+async function apiDemoMode(req, res, ctx) {
+    const body = await readJsonBody(req);
+    if (typeof body.writable === 'boolean')
+        ctx.writable = body.writable;
+    if (typeof body.showPii === 'boolean')
+        ctx.showPii = body.showPii;
+    sendJson(res, 200, {
+        demo: true,
+        writable: ctx.writable === true,
+        showPii: ctx.showPii === true,
+    });
+}
+// ---------------------------------------------------------------------------
 // Auth
 // ---------------------------------------------------------------------------
 function isAuthorized(req, expectedToken) {
@@ -325,17 +382,28 @@ async function apiSchema(res, ctx) {
             referenceKey: rel.referenceKey,
         })),
     }));
-    // Row counts — cheap enough to fetch inline. Use pg_class reltuples as
-    // a fast estimate so we don't hammer big tables with SELECT COUNT(*).
-    const countsResult = await ctx.pool.query(`SELECT c.relname, c.reltuples::bigint::text AS reltuples
-     FROM pg_class c
-     JOIN pg_namespace n ON n.oid = c.relnamespace
-     WHERE n.nspname = $1 AND c.relkind = 'r'`, [ctx.options.schema]);
+    // Row counts (cheap enough to fetch inline).
     const counts = new Map();
-    for (const row of countsResult.rows) {
-        // pg_class.reltuples is -1 on PG14+ until a table is ANALYZEd; clamp so the
-        // sidebar never shows a negative estimate.
-        counts.set(row.relname, Math.max(0, Number(row.reltuples)));
+    if (ctx.demo) {
+        // The demo dataset is tiny and in-memory: an exact per-table COUNT(*) is
+        // instant, and SQLite has no pg_class estimate to read.
+        for (const t of tables) {
+            const r = await ctx.pool.query(`SELECT COUNT(*) AS count FROM ${(0, index_js_1.quoteIdent)(t.name)}`);
+            counts.set(t.name, Number(r.rows[0]?.count ?? 0));
+        }
+    }
+    else {
+        // Use pg_class reltuples as a fast estimate so we don't hammer big tables
+        // with SELECT COUNT(*).
+        const countsResult = await ctx.pool.query(`SELECT c.relname, c.reltuples::bigint::text AS reltuples
+       FROM pg_class c
+       JOIN pg_namespace n ON n.oid = c.relnamespace
+       WHERE n.nspname = $1 AND c.relkind = 'r'`, [ctx.options.schema]);
+        for (const row of countsResult.rows) {
+            // pg_class.reltuples is -1 on PG14+ until a table is ANALYZEd; clamp so the
+            // sidebar never shows a negative estimate.
+            counts.set(row.relname, Math.max(0, Number(row.reltuples)));
+        }
     }
     sendJson(res, 200, {
         schema: ctx.options.schema,
@@ -345,6 +413,8 @@ async function apiSchema(res, ctx) {
         // Read-only Studio reports `writable: false` so the UI renders no write UI.
         writable: ctx.writable === true,
         showPii: ctx.showPii === true,
+        // Demo flag drives the in-UI mode switcher + persistent demo banner.
+        demo: ctx.demo === true,
     });
 }
 // ---------------------------------------------------------------------------
@@ -384,12 +454,21 @@ async function apiTableRows(res, ctx, rawTableName, params) {
         .map((c) => c.name);
     const hasSearch = search.length > 0 && textColumns.length > 0;
     const pattern = hasSearch ? `%${escapeLikePattern(search)}%` : null;
+    // Parameter placeholder + case-insensitive LIKE condition differ by engine.
+    // Postgres: numbered `$N` + `ILIKE`. Demo (SQLite): named `:pN` (bound by
+    // name from the positional value array, matching Turbine's own SQLite path)
+    // + `LOWER(col) LIKE LOWER(:pN)` (explicit case-fold, ASCII). The escape char
+    // (`\`) is identical. When demo is off these produce byte-identical SQL.
+    const ph = (n) => (ctx.demo ? `:p${n}` : `$${n}`);
+    const likeCond = (col, n) => ctx.demo
+        ? `LOWER(${(0, index_js_1.quoteIdent)(col)}) LIKE LOWER(${ph(n)}) ESCAPE '\\'`
+        : `${(0, index_js_1.quoteIdent)(col)} ILIKE ${ph(n)} ESCAPE '\\'`;
     // Main query: $1 = limit, $2 = offset, $3 = pattern (if search)
     const mainValues = [limit, offset];
     let mainWhere = '';
     if (hasSearch && pattern !== null) {
         mainValues.push(pattern);
-        const conds = textColumns.map((c) => `${(0, index_js_1.quoteIdent)(c)} ILIKE $3 ESCAPE '\\'`);
+        const conds = textColumns.map((c) => likeCond(c, 3));
         mainWhere = `WHERE (${conds.join(' OR ')})`;
     }
     // Count query: $1 = pattern (if search)
@@ -397,22 +476,35 @@ async function apiTableRows(res, ctx, rawTableName, params) {
     let countWhere = '';
     if (hasSearch && pattern !== null) {
         countValues.push(pattern);
-        const conds = textColumns.map((c) => `${(0, index_js_1.quoteIdent)(c)} ILIKE $1 ESCAPE '\\'`);
+        const conds = textColumns.map((c) => likeCond(c, 1));
         countWhere = `WHERE (${conds.join(' OR ')})`;
     }
-    const qualifiedTable = `${(0, index_js_1.quoteIdent)(ctx.options.schema)}.${(0, index_js_1.quoteIdent)(table.name)}`;
-    const sql = `SELECT * FROM ${qualifiedTable} ${mainWhere} ${orderByClause} LIMIT $1 OFFSET $2`;
-    const countSql = `SELECT COUNT(*)::text AS count FROM ${qualifiedTable} ${countWhere}`;
+    // Demo runs against an unqualified in-memory SQLite table (no schemas);
+    // Postgres qualifies with the configured `--schema`.
+    const qualifiedTable = ctx.demo
+        ? (0, index_js_1.quoteIdent)(table.name)
+        : `${(0, index_js_1.quoteIdent)(ctx.options.schema)}.${(0, index_js_1.quoteIdent)(table.name)}`;
+    const sql = `SELECT * FROM ${qualifiedTable} ${mainWhere} ${orderByClause} LIMIT ${ph(1)} OFFSET ${ph(2)}`;
+    // Postgres casts the bigint COUNT to text to avoid int8 precision loss on the
+    // wire; SQLite returns a safe integer directly, so no cast.
+    const countSql = `SELECT COUNT(*)${ctx.demo ? '' : '::text'} AS count FROM ${qualifiedTable} ${countWhere}`;
     const client = await ctx.pool.connect();
     try {
-        await client.query('BEGIN READ ONLY');
-        await client.query(ctx.statementTimeout.sql, ctx.statementTimeout.params);
+        // Demo: the in-memory SQLite handle is a single synchronous connection with
+        // no READ ONLY txn mode or statement_timeout GUC, so we skip the read
+        // transaction wrapper entirely. Postgres keeps its belt-and-suspenders
+        // READ ONLY transaction + timeout.
+        if (!ctx.demo) {
+            await client.query('BEGIN READ ONLY');
+            await client.query(ctx.statementTimeout.sql, ctx.statementTimeout.params);
+        }
         const result = await client.query(sql, mainValues);
         const countResult = await client.query(countSql, countValues);
-        await client.query('COMMIT');
+        if (!ctx.demo)
+            await client.query('COMMIT');
         sendJson(res, 200, {
             table: table.name,
-            columns: result.fields.map((f) => ({ name: f.name, dataTypeID: f.dataTypeID })),
+            columns: resultColumns(result, result.rows),
             rows: result.rows.map((r) => serializeRow(redactFlatRow(r, redactedPii))),
             total: Number(countResult.rows[0]?.count ?? 0),
             limit,
@@ -421,11 +513,13 @@ async function apiTableRows(res, ctx, rawTableName, params) {
         });
     }
     catch (err) {
-        try {
-            await client.query('ROLLBACK');
-        }
-        catch {
-            /* ignore */
+        if (!ctx.demo) {
+            try {
+                await client.query('ROLLBACK');
+            }
+            catch {
+                /* ignore */
+            }
         }
         throw err;
     }
@@ -470,6 +564,9 @@ async function apiBuilder(req, res, ctx) {
             warnOnUnlimited: false,
             sqlCache: false,
             preparedStatements: false,
+            // Demo compiles SQLite SQL (`:pN`, json_group_array, …); Postgres default
+            // when unset.
+            dialect: ctx.dialect,
         });
         deferred = qi.buildFindMany(args);
     }
@@ -479,33 +576,44 @@ async function apiBuilder(req, res, ctx) {
     }
     const client = await ctx.pool.connect();
     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]);
+        if (!ctx.demo) {
+            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). Demo has no schemas.
+            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;
-        await client.query('COMMIT');
-        const rawRows = result.rows;
+        if (!ctx.demo)
+            await client.query('COMMIT');
+        // Postgres auto-parses json/jsonb relation columns into JS values via its
+        // type parsers; the SQLite demo driver returns them as raw JSON strings. So
+        // in demo mode, parse relation columns back into arrays/objects (walking the
+        // `with` tree) to match the Postgres shape before redaction + serialization.
+        const rawRows = ctx.demo
+            ? parseDemoRelationRows(result.rows, tableName, args.with, ctx.metadata)
+            : result.rows;
         const redactedRows = ctx.showPii ? rawRows : redactBuilderRows(rawRows, tableName, args.with, ctx.metadata);
         sendJson(res, 200, {
             sql: deferred.sql,
-            columns: result.fields.map((f) => ({ name: f.name, dataTypeID: f.dataTypeID })),
+            columns: resultColumns(result, result.rows),
             rows: redactedRows.map((r) => serializeRow(r)),
             rowCount: result.rowCount ?? result.rows.length,
             elapsedMs,
         });
     }
     catch (err) {
-        try {
-            await client.query('ROLLBACK');
-        }
-        catch {
-            /* ignore */
+        if (!ctx.demo) {
+            try {
+                await client.query('ROLLBACK');
+            }
+            catch {
+                /* ignore */
+            }
         }
         sendJson(res, 400, { error: err instanceof Error ? err.message : String(err) });
     }
@@ -577,6 +685,7 @@ async function apiRowWrite(req, res, ctx, op) {
             warnOnUnlimited: false,
             sqlCache: false,
             preparedStatements: false,
+            dialect: ctx.dialect,
         });
         if (op === 'insert') {
             deferred = qi.buildCreate({ data });
@@ -594,11 +703,15 @@ async function apiRowWrite(req, res, ctx, op) {
     }
     const client = await ctx.pool.connect();
     try {
-        // A real write transaction, NOT `READ ONLY`. Same parameterized
-        // statement-timeout + search_path pin as the read paths.
+        // A real write transaction, NOT `READ ONLY`. Postgres also pins the
+        // parameterized statement-timeout + search_path; demo (SQLite) has neither
+        // GUC, so those are skipped, but the BEGIN/COMMIT is kept (SqlitePool
+        // supports it) so an in-memory write still applies atomically.
         await client.query('BEGIN');
-        await client.query(ctx.statementTimeout.sql, ctx.statementTimeout.params);
-        await client.query(`SELECT set_config('search_path', $1, true)`, [ctx.options.schema]);
+        if (!ctx.demo) {
+            await client.query(ctx.statementTimeout.sql, ctx.statementTimeout.params);
+            await client.query(`SELECT set_config('search_path', $1, true)`, [ctx.options.schema]);
+        }
         const result = await client.query(deferred.sql, deferred.params);
         await client.query('COMMIT');
         const row = result.rows[0];
@@ -837,6 +950,52 @@ function redactBuilderRows(rows, tableName, withClause, metadata) {
         return out;
     });
 }
+/**
+ * Demo-only: parse relation columns that arrive as raw JSON strings from the
+ * SQLite driver back into arrays/objects, walking the `with` tree so nested
+ * relations are parsed at every level. This mirrors what Postgres' json/jsonb
+ * type parsers do automatically, so the builder response shape (and downstream
+ * redaction) is identical across engines. Rows without the named relation, or
+ * whose value is already a parsed object/array, pass through unchanged.
+ */
+function parseDemoRelationRows(rows, tableName, withClause, metadata) {
+    const table = metadata.tables[tableName];
+    if (!table)
+        return rows;
+    const relEntries = withClause && typeof withClause === 'object'
+        ? Object.entries(withClause).filter(([, v]) => v)
+        : [];
+    if (relEntries.length === 0)
+        return rows;
+    return rows.map((row) => {
+        const out = { ...row };
+        for (const [relName, relVal] of relEntries) {
+            const rel = table.relations[relName];
+            if (!rel)
+                continue;
+            let child = out[relName];
+            if (typeof child === 'string') {
+                try {
+                    child = JSON.parse(child);
+                }
+                catch {
+                    continue;
+                }
+            }
+            const nestedWith = relVal && typeof relVal === 'object' ? relVal.with : undefined;
+            if (Array.isArray(child)) {
+                out[relName] = parseDemoRelationRows(child, rel.to, nestedWith, metadata);
+            }
+            else if (child && typeof child === 'object') {
+                out[relName] = parseDemoRelationRows([child], rel.to, nestedWith, metadata)[0];
+            }
+            else {
+                out[relName] = child;
+            }
+        }
+        return out;
+    });
+}
 /**
  * A fresh CSP nonce for one HTML response. Base64 of 16 random bytes; the value
  * is stamped into both the `Content-Security-Policy` header and the inline
@@ -853,6 +1012,20 @@ function clampInt(value, fallback, min, max) {
         return fallback;
     return Math.min(Math.max(n, min), max);
 }
+/**
+ * Column descriptors for a result payload. Postgres results carry a `fields`
+ * array (name + OID); the SQLite demo driver does not, so we fall back to the
+ * keys of the first returned row (dataTypeID 0 = "unknown", which the UI treats
+ * generically). When `fields` is present this is byte-identical to the previous
+ * inline `result.fields.map(...)`.
+ */
+function resultColumns(result, rows) {
+    if (result.fields) {
+        return result.fields.map((f) => ({ name: f.name, dataTypeID: f.dataTypeID }));
+    }
+    const first = rows[0];
+    return first ? Object.keys(first).map((name) => ({ name, dataTypeID: 0 })) : [];
+}
 function serializeRow(row) {
     const out = {};
     for (const [k, v] of Object.entries(row)) {

package/dist/cli/index.d.ts

@@ -14,7 +14,7 @@
  *   turbine seed                  — Run seed file
  *   turbine status                — Show schema summary
  *   turbine doctor                — Check relations for missing FK indexes (--fix emits migration)
- *   turbine studio                — Launch local read-only web UI
+ *   turbine studio                : Launch local read-only web UI (--demo for a seeded sample DB)
  *   turbine mcp                   — Start read-only MCP server over JSON-RPC stdio
  *   turbine observe               — Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
  *
@@ -57,6 +57,8 @@ export interface CliArgs {
     write?: boolean;
     /** Reveal PII-tagged column values in Studio instead of redacting (`--show-pii`). */
     showPii?: boolean;
+    /** Launch Studio with a seeded in-memory sample database (`studio --demo`). */
+    demo?: boolean;
 }
 export declare function parseArgs(argv?: string[]): CliArgs;
 /** Where a resolved `DATABASE_URL` came from, after the `.env` load. */

package/dist/cli/index.js

@@ -14,7 +14,7 @@
  *   turbine seed                  — Run seed file
  *   turbine status                — Show schema summary
  *   turbine doctor                — Check relations for missing FK indexes (--fix emits migration)
- *   turbine studio                — Launch local read-only web UI
+ *   turbine studio                : Launch local read-only web UI (--demo for a seeded sample DB)
  *   turbine mcp                   — Start read-only MCP server over JSON-RPC stdio
  *   turbine observe               — Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
  *
@@ -148,6 +148,9 @@ export function parseArgs(argv = process.argv.slice(2)) {
             case '--show-pii':
                 result.showPii = true;
                 break;
+            case '--demo':
+                result.demo = true;
+                break;
             default:
                 if (!arg.startsWith('-')) {
                     result.positional.push(arg);
@@ -1461,7 +1464,10 @@ export function isLoopbackHost(host) {
 // ---------------------------------------------------------------------------
 async function cmdStudio(args, config) {
     banner();
-    const url = requireUrl(config);
+    const demo = args.demo === true;
+    // Demo mode is self-contained (seeded in-memory database), so it never needs
+    // a DATABASE_URL. The placeholder is only used for display.
+    const url = demo ? 'demo://in-memory' : requireUrl(config);
     const port = args.port ?? 4983;
     const host = args.host ?? '127.0.0.1';
     const openBrowser = !args.noOpen;
@@ -1484,7 +1490,7 @@ async function cmdStudio(args, config) {
         console.log(warn(`Studio is binding to ${yellow(host)} — this is NOT loopback. ` +
             `Anyone on your network who can reach this port + guess the session token can read your database.`));
     }
-    const spinner = new Spinner('Introspecting database').start();
+    const spinner = new Spinner(demo ? 'Seeding demo dataset' : 'Introspecting database').start();
     let studio;
     try {
         studio = await startStudio({
@@ -1495,39 +1501,60 @@ async function cmdStudio(args, config) {
             openBrowser,
             include: config.include.length ? config.include : undefined,
             exclude: config.exclude.length ? config.exclude : undefined,
+            // Demo boots read-only + PII redacted; the flags are ignored in demo mode
+            // (the in-UI switcher controls modes live).
             write: args.write === true,
             showPii: args.showPii === true,
+            demo,
         });
-        spinner.succeed(`Studio is running`);
+        spinner.succeed(demo ? 'Demo Studio is running' : 'Studio is running');
     }
     catch (err) {
         spinner.fail(`Failed to start Studio: ${err instanceof Error ? err.message : String(err)}`);
         process.exit(1);
     }
-    // Loud startup warnings for the opt-in modes that widen Studio's surface.
-    if (args.write) {
+    if (demo) {
+        newline();
+        console.log(box([
+            `${bold('Turbine Studio')}  ${dim('DEMO MODE (seeded in-memory sample database)')}`,
+            '',
+            `  ${cyan('URL:')}    ${bold(studio.url)}`,
+            `  ${cyan('Data:')}   seeded sample dataset (users, posts, comments, orgs)`,
+            `  ${cyan('Modes:')}  switch Read-only / Show PII / Write live from inside the UI`,
+            '',
+            dim('Nothing you do here is saved anywhere. The database lives only in'),
+            dim('memory: every launch starts fresh and restarts reset all edits.'),
+            dim('Open the URL above (it carries a one-time session token).'),
+            dim('Press Ctrl+C to stop.'),
+        ].join('\n'), { title: bold(cyan('Studio · demo')), padding: 1 }));
         newline();
-        console.log(warn('WRITE MODE is ON. Studio can update, insert, and delete single rows in ' +
-            `${redactUrl(url)}. Every change is committed directly to your database.`));
     }
-    if (args.showPii) {
+    else {
+        // Loud startup warnings for the opt-in modes that widen Studio's surface.
+        if (args.write) {
+            newline();
+            console.log(warn('WRITE MODE is ON. Studio can update, insert, and delete single rows in ' +
+                `${redactUrl(url)}. Every change is committed directly to your database.`));
+        }
+        if (args.showPii) {
+            newline();
+            console.log(warn('--show-pii is ON. PII-tagged column values are shown UNREDACTED in Studio.'));
+        }
+        newline();
+        console.log(box([
+            `${bold('Turbine Studio')}  ${dim(args.write ? 'local UI (WRITE MODE)' : 'local read-only UI')}`,
+            '',
+            `  ${cyan('URL:')}    ${bold(studio.url)}`,
+            `  ${cyan('Schema:')} ${config.schema}`,
+            `  ${cyan('DB:')}     ${redactUrl(url)}`,
+            `  ${cyan('Mode:')}   ${args.write ? red('read-write (single-row)') : 'read-only'}`,
+            '',
+            dim('Open the URL above in your browser. It includes a one-time session'),
+            dim('token that gets set as an HttpOnly cookie on first load.'),
+            dim('Press Ctrl+C to stop.'),
+        ].join('\n'), { title: bold(cyan('Studio')), padding: 1 }));
         newline();
-        console.log(warn('--show-pii is ON. PII-tagged column values are shown UNREDACTED in Studio.'));
     }
-    newline();
-    console.log(box([
-        `${bold('Turbine Studio')}  ${dim(args.write ? 'local UI (WRITE MODE)' : 'local read-only UI')}`,
-        '',
-        `  ${cyan('URL:')}    ${bold(studio.url)}`,
-        `  ${cyan('Schema:')} ${config.schema}`,
-        `  ${cyan('DB:')}     ${redactUrl(url)}`,
-        `  ${cyan('Mode:')}   ${args.write ? red('read-write (single-row)') : 'read-only'}`,
-        '',
-        dim('Open the URL above in your browser. It includes a one-time session'),
-        dim('token that gets set as an HttpOnly cookie on first load.'),
-        dim('Press Ctrl+C to stop.'),
-    ].join('\n'), { title: bold(cyan('Studio')), padding: 1 }));
-    newline();
     // Wait forever until SIGINT/SIGTERM, then dispose cleanly.
     await new Promise((resolve) => {
         const shutdown = async () => {
@@ -1808,7 +1835,7 @@ function showHelp() {
     console.log(`    ${cyan('seed')}               Run seed file`);
     console.log(`    ${cyan('status')} ${dim('| info')}      Show schema summary`);
     console.log(`    ${cyan('doctor')}             Check relations for missing FK indexes ${dim('(--fix emits migration)')}`);
-    console.log(`    ${cyan('studio')}             Launch local read-only web UI ${dim('(--write opts in to single-row writes)')}`);
+    console.log(`    ${cyan('studio')}             Launch local read-only web UI ${dim('(--write for writes, --demo for a sample DB)')}`);
     console.log(`    ${cyan('mcp')}                Start read-only MCP server over stdio`);
     console.log(`    ${cyan('observe')}            Launch metrics dashboard ${dim('(requires TURBINE_OBSERVE_URL)')}`);
     newline();
@@ -1834,6 +1861,7 @@ function showHelp() {
     console.log(`    ${cyan('--allow-remote')}       Allow non-loopback --host ${dim('(refused without this flag)')}`);
     console.log(`    ${cyan('--write')}              Studio: enable single-row update/insert/delete ${dim('(read-only by default)')}`);
     console.log(`    ${cyan('--show-pii')}           Studio: show PII-tagged values unredacted ${dim('(redacted by default)')}`);
+    console.log(`    ${cyan('--demo')}               Studio: launch with a seeded in-memory sample database ${dim('(no DATABASE_URL needed; nothing is saved)')}`);
     newline();
     console.log(`  ${bold('Config file:')}`);
     console.log(`    ${dim('Create')} ${cyan('turbine.config.ts')} ${dim('with')} ${cyan('npx turbine init')}`);

package/dist/cli/studio-demo.d.ts

@@ -0,0 +1,43 @@
+/**
+ * turbine-orm CLI: Studio demo mode (`turbine studio --demo`)
+ *
+ * Boots Studio with NO database and NO DATABASE_URL: a baked-in, seeded sample
+ * dataset served from an in-memory engine. It is the "feel the product in 10
+ * seconds" experience: read mode, PII redaction, and the single-row write flow,
+ * all safely fake.
+ *
+ * The store is backed by Turbine's OWN SQLite engine over `node:sqlite`'s
+ * `:memory:` database (a built-in on Node >= 22.5, zero new dependency). Because
+ * `:memory:` is per-handle, the store dies with the process and every launch
+ * starts pristine: writes genuinely apply (edits stick, a refresh shows them)
+ * but nothing is ever persisted anywhere.
+ *
+ * This module lives under `src/cli/` (coverage-excluded, never imported by
+ * library code) and reuses `SqlitePool` + `sqliteDialect` from `../sqlite.js`;
+ * it never writes its own SQL evaluator.
+ */
+import type { PgCompatPool } from '../client.js';
+import type { Dialect } from '../dialect.js';
+import type { SchemaMetadata } from '../schema.js';
+/**
+ * The seeded sample schema. Four tables with realistic relations; `email` and
+ * `phone` are tagged `pii` so Studio's redaction path is exercised out of the
+ * box.
+ */
+export declare const DEMO_SCHEMA: SchemaMetadata;
+export interface DemoContext {
+    /** In-memory SQLite pool (pg-compatible) backing the demo store. */
+    pool: PgCompatPool;
+    /** The seeded sample schema metadata. */
+    metadata: SchemaMetadata;
+    /** The SQLite dialect the Studio handlers compile against in demo mode. */
+    dialect: Dialect;
+}
+/**
+ * Open a fresh, seeded in-memory demo store and return the pool + metadata +
+ * dialect Studio needs. Each call yields an independent, pristine database
+ * (`:memory:` is per-handle), so demo launches never share state.
+ *
+ * @throws Error on Node < 22.5 (no built-in `node:sqlite`).
+ */
+export declare function createDemoContext(): DemoContext;