@everystack/cli 0.3.8 → 0.3.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -87,10 +87,14 @@
     "@aws-sdk/s3-request-presigner": "3.1053.0",
     "drizzle-orm": "0.41.0",
     "expo-updates": "55.0.21",
+    "postgres": "3.4.9",
     "react": "19.2.0",
     "react-native": "0.83.6"
   },
   "peerDependenciesMeta": {
+    "postgres": {
+      "optional": true
+    },
     "@everystack/server": {
       "optional": true
     },

package/src/cli/commands/db-generate.ts

@@ -27,6 +27,7 @@ import { compileModuleMigration } from '../migration-compile.js';
 import { generateMigrationSql, unmodeledTables, formatMigrationFile, planMigrationFile, HELD_DROP_PREFIX, type Journal } from '../migration-generate.js';
 import { introspectContract, type QueryRunner } from '../authz-contract.js';
 import { FUNCTIONS_SQL, catalogFunctionToDescriptor } from '../security-catalog.js';
+import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
 import { resolveConfig, opsFunction } from '../config.js';
 import { invokeAction } from '../aws.js';
 import { step, success, fail, info, warn } from '../output.js';
@@ -152,17 +153,27 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
     // updates it. The drift-guard test asserts this file matches the models.
     step(`Writing the drizzle schema → ${path.relative(process.cwd(), schemaOut)}...`);
     await fs.writeFile(schemaOut, compileDrizzleSource(models), 'utf8');
-    step('Resolving deployed config...');
-    const config = await resolveConfig(flags.stage);
-    info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
-    const runner = lambdaRunner(config.region, opsFunction(config));
+    const dbSource: DbSource = resolveDbSource(flags);
+    let runner: QueryRunner;
+    let end: (() => Promise<void>) | undefined;
+    if (dbSource.kind === 'url') {
+      step(dbSource.from === 'flag' ? 'Connecting via --database-url...' : 'Connecting via DATABASE_URL...');
+      ({ runner, end } = await createUrlRunner(dbSource.url));
+    } else {
+      step('Resolving deployed config...');
+      const config = await resolveConfig(flags.stage);
+      info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+      runner = lambdaRunner(config.region, opsFunction(config));
+    }
     step('Introspecting live database (columns + constraints)...');
     current = await introspectSchema(runner);
     step('Introspecting authorization (rls + grants + policies)...');
     liveAuthz = await introspectContract(runner, mapFunctionRow, FUNCTIONS_SQL);
+    await end?.();
   } catch (err: any) {
     fail(err.message);
     info('Ensure your IAM user/role has lambda:InvokeFunction and the stage is deployed.');
+    info('Diffing against a local database instead? Pass --database-url or set DATABASE_URL.');
     process.exit(1);
   }
 

package/src/cli/commands/db-pull.ts

@@ -1,12 +1,15 @@
 /**
  * `everystack db:pull` — generate `field()` Models from a live database (the brownfield on-ramp).
  *
- *   db:pull --stage <name> [--schema public] [--out models/index.ts]
+ *   db:pull [--stage <name> | --database-url <url>] [--schema public] [--out models/index.ts]
  *
  * The reverse of db:generate: that writes migrations FROM Models; this writes Models FROM the
  * database. It introspects the deployed schema through the read-only ops Lambda `db:query`
- * action and renders the TypeScript a Model is written in — a starting point you review and
- * refine (it flags, as inline comments, anything the field builder can't yet express).
+ * action — or, for a database no Lambda can reach (the brownfield case where the target
+ * schema exists only locally), directly via `--database-url` / an inherited `DATABASE_URL`
+ * (see db-source.ts for precedence) — and renders the TypeScript a Model is written in — a
+ * starting point you review and refine (it flags, as inline comments, anything the field
+ * builder can't yet express).
  *
  * The rendered source is the artifact: it goes to stdout (so `db:pull > models.ts` works) or
  * to `--out`. Every progress/diagnostic line goes to stderr, so the stdout pipe stays pure
@@ -18,6 +21,7 @@ import path from 'node:path';
 import { introspectSchema } from '../schema-introspect.js';
 import { renderModelSource } from '../model-render.js';
 import type { QueryRunner } from '../authz-contract.js';
+import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
 import { resolveConfig, opsFunction } from '../config.js';
 import { invokeAction } from '../aws.js';
 import { fail } from '../output.js';
@@ -41,16 +45,38 @@ function lambdaRunner(region: string, fn: string): QueryRunner {
 export async function dbPullCommand(flags: Record<string, string>): Promise<void> {
   const schema = flags.schema || 'public';
 
+  let dbSource: DbSource;
+  try {
+    dbSource = resolveDbSource(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
   let current;
   try {
-    note('Resolving deployed config...');
-    const config = await resolveConfig(flags.stage);
-    detail(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+    let runner: QueryRunner;
+    let end: (() => Promise<void>) | undefined;
+    if (dbSource.kind === 'url') {
+      note(dbSource.from === 'flag' ? 'Connecting via --database-url...' : 'Connecting via DATABASE_URL...');
+      ({ runner, end } = await createUrlRunner(dbSource.url));
+    } else {
+      note('Resolving deployed config...');
+      const config = await resolveConfig(flags.stage);
+      detail(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+      runner = lambdaRunner(config.region, opsFunction(config));
+    }
     note(`Introspecting live database (schema: ${schema})...`);
-    current = await introspectSchema(lambdaRunner(config.region, opsFunction(config)));
+    current = await introspectSchema(runner);
+    await end?.();
   } catch (err: any) {
     fail(err.message);
-    detail('Ensure your IAM user/role has lambda:InvokeFunction and the stage is deployed.');
+    if (dbSource.kind === 'url') {
+      detail('Check the connection string and that the database is accepting connections.');
+    } else {
+      detail('Ensure your IAM user/role has lambda:InvokeFunction and the stage is deployed.');
+      detail('Introspecting a local database instead? Pass --database-url or set DATABASE_URL.');
+    }
     process.exit(1);
   }
 

package/src/cli/db-source.ts

@@ -0,0 +1,77 @@
+/**
+ * db-source — where db:pull / db:generate find the database.
+ *
+ * Two paths to the same QueryRunner contract:
+ *
+ * - **Deployed** (the default): introspection SQL runs through the read-only ops Lambda
+ *   `db:query` action. Credentials never leave AWS; works for any deployed stage.
+ * - **Direct** (`--database-url` or an inherited `DATABASE_URL`): a postgres.js
+ *   connection from this process. This is the brownfield on-ramp's missing half — when
+ *   the target schema exists only on a local Postgres (migrations applied locally, no
+ *   interim deploy), there is no Lambda to ask.
+ *
+ * Precedence is explicit-over-ambient: `--database-url` beats an explicit `--stage`,
+ * which beats an inherited `DATABASE_URL`, which beats the default stage. An explicit
+ * `--stage` deliberately wins over the env var so a shell with DATABASE_URL exported
+ * still introspects the stage you named.
+ *
+ * The driver is loaded lazily: `postgres` ships with @everystack/server (every deployed
+ * consumer has it hoisted), so the deployed path never pays the import and a missing
+ * driver only surfaces — with instructions — when the direct path is actually used.
+ */
+
+import type { QueryRunner } from './authz-contract.js';
+
+export type DbSource =
+  | { kind: 'url'; url: string; from: 'flag' | 'env' }
+  | { kind: 'stage' };
+
+/** Decide which path serves this invocation. Pure; env injectable for tests. */
+export function resolveDbSource(
+  flags: Record<string, string>,
+  env: Record<string, string | undefined> = process.env,
+): DbSource {
+  const flagUrl = flags['database-url'];
+  if (flagUrl) {
+    // parseFlags encodes a value-less flag as 'true'
+    if (flagUrl === 'true') {
+      throw new Error(
+        '--database-url needs a connection string (or omit the flag and set DATABASE_URL in the environment).',
+      );
+    }
+    return { kind: 'url', url: flagUrl, from: 'flag' };
+  }
+  if (flags.stage) return { kind: 'stage' };
+  if (env.DATABASE_URL) return { kind: 'url', url: env.DATABASE_URL, from: 'env' };
+  return { kind: 'stage' };
+}
+
+export interface UrlRunner {
+  runner: QueryRunner;
+  /** Close the client so the process can exit cleanly. */
+  end: () => Promise<void>;
+}
+
+/**
+ * A QueryRunner over a direct postgres.js connection. One connection is enough —
+ * introspection is a handful of sequential catalog queries.
+ */
+export async function createUrlRunner(
+  url: string,
+  load: () => Promise<any> = () => import('postgres'),
+): Promise<UrlRunner> {
+  let mod: any;
+  try {
+    mod = await load();
+  } catch {
+    throw new Error(
+      'The direct-connection path needs the "postgres" driver. It ships with @everystack/server; in a project without it: pnpm add -D postgres',
+    );
+  }
+  const postgres = mod.default ?? mod;
+  const sql = postgres(url, { max: 1, onnotice: () => {} });
+  return {
+    runner: async (query: string) => Array.from(await sql.unsafe(query)),
+    end: () => sql.end({ timeout: 5 }),
+  };
+}

package/src/cli/index.ts

@@ -95,6 +95,13 @@ async function main() {
 
   const flags = parseFlags(args.slice(1));
 
+  // `everystack <command> --help` shows help instead of running the command
+  // (a db command falling through to the default stage is a footgun).
+  if ('help' in flags || 'h' in flags) {
+    printHelp();
+    process.exit(0);
+  }
+
   // Auto-detect deployed URL from SST outputs
   await loadSstOutputs(flags.stage);
 
@@ -280,8 +287,9 @@ Usage:
   everystack db:backups        [--stage <name>]  List logical backups (id, size, created)
   everystack db:restore        --from <id> [--stage <name>] --confirm  Restore a backup INTO the stage's DB (DESTRUCTIVE)
   everystack db:backup:download <id> [--stage <name>]  Presigned URL to download a backup's dump (valid 1h)
-  everystack db:generate       [--stage <name>] [--name <label>] [--models models/index.ts] [--allow-drops]  Diff models vs the live DB → write the next migration (never touches the DB; DROPs held back unless --allow-drops)
-  everystack db:pull           [--stage <name>] [--schema public] [--out <file>]  Introspect the live DB → render field() Models (the brownfield on-ramp; stdout unless --out)
+  everystack db:generate       [--stage <name> | --database-url <url>] [--name <label>] [--models models/index.ts] [--allow-drops]  Diff models vs the live DB → write the next migration (never touches the DB; DROPs held back unless --allow-drops)
+  everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <file>]  Introspect the live DB → render field() Models (the brownfield on-ramp; stdout unless --out)
+                               Both introspect via the deployed ops Lambda by default; --database-url (or an inherited DATABASE_URL) connects directly — for a schema that exists only on a local Postgres.
   everystack db:authz:pull     [--stage <name>] [--dir authz]  Introspect live authz (rls/grants/policies/secdef) → reviewable contract files
   everystack db:authz:diff     [--stage <name>] [--dir authz]  Validate the live DB against the committed contract (non-zero exit on drift)
   everystack db:authz:test     [--stage <name>] [--dir authz]  Red-team enforcement: SET ROLE + attempt per role/table/command (non-zero exit on a hole)