convex 1.46.0 → 1.47.0

package/src/cli/lib/components.ts

@@ -53,6 +53,18 @@ import { deploymentDashboardUrlPage } from "./dashboard.js";
 import { formatIndex, LargeIndexDeletionCheck } from "./indexes.js";
 import { checkForLargeIndexDeletion } from "./checkForLargeIndexDeletion.js";
 import { checkForSlowSchemaValidation } from "./checkForSlowSchemaValidation.js";
+import {
+  checkForLargeIndexBackfill,
+  LargeIndexBackfillCheck,
+} from "./checkForLargeIndexBackfill.js";
+import {
+  pushStagesValidators,
+  sharedSchemaEvaluation,
+} from "./schemaEvaluation.js";
+import {
+  checkForStagedValidatorDeletion,
+  StagedValidatorDeletionCheck,
+} from "./checkForStagedValidatorDeletion.js";
 import { LogManager } from "./logs.js";
 import { createHash } from "crypto";
 import { Bundle, BundleHash } from "../../bundler/index.js";
@@ -76,6 +88,8 @@ export type PushOptions = {
   pushAllModules: boolean;
   logManager?: LogManager | undefined;
   largeIndexDeletionCheck: LargeIndexDeletionCheck;
+  largeIndexBackfillCheck: LargeIndexBackfillCheck;
+  stagedValidatorDeletionCheck: StagedValidatorDeletionCheck;
   // Whether a dry run should warn when the schema change would block the
   // deploy on a slow table walk. On for deploys; off for commands whose dry
   // runs never deploy (e.g. codegen).
@@ -125,6 +139,11 @@ export async function runCodegen(
         liveComponentSources: options.liveComponentSources,
         typecheckComponents: false,
         debugNodeApis: options.debugNodeApis,
+        // Code generation uses the source schema independently of deployment data.
+        largeIndexDeletionCheck: "no verification",
+        largeIndexBackfillCheck: "no verification",
+        stagedValidatorDeletionCheck: "no verification",
+        warnOnSlowSchemaValidation: false,
       },
     );
   } else {
@@ -234,6 +253,8 @@ async function startComponentsPushAndCodegen(
     pushAllModules?: boolean;
     debugNodeApis: boolean;
     largeIndexDeletionCheck: LargeIndexDeletionCheck;
+    largeIndexBackfillCheck: LargeIndexBackfillCheck;
+    stagedValidatorDeletionCheck: StagedValidatorDeletionCheck;
     warnOnSlowSchemaValidation: boolean;
     codegenOnlyThisComponent?: string | undefined;
   },
@@ -451,6 +472,11 @@ async function startComponentsPushAndCodegen(
   }
   logStartPushSizes(parentSpan, startPushRequest);
 
+  const schemaEvaluation = sharedSchemaEvaluation(
+    ctx,
+    startPushRequest,
+    options,
+  );
   if (options.largeIndexDeletionCheck !== "no verification") {
     await parentSpan.enterAsync("checkForLargeIndexDeletion", (span) =>
       checkForLargeIndexDeletion({
@@ -458,19 +484,60 @@ async function startComponentsPushAndCodegen(
         span,
         request: startPushRequest,
         options,
+        schemaEvaluation,
         askForConfirmation:
           options.largeIndexDeletionCheck === "ask for confirmation",
       }),
     );
   }
 
-  if (options.dryRun && options.warnOnSlowSchemaValidation) {
-    await parentSpan.enterAsync("checkForSlowSchemaValidation", (span) =>
-      checkForSlowSchemaValidation({
+  const largeIndexBackfillCheck = options.largeIndexBackfillCheck;
+  if (largeIndexBackfillCheck !== "no verification") {
+    await parentSpan.enterAsync("checkForLargeIndexBackfill", (span) =>
+      checkForLargeIndexBackfill({
         ctx,
         span,
-        request: startPushRequest,
+        schemaEvaluation,
         options,
+        // A dry run never blocks on a backfill, so it only reports.
+        mode: options.dryRun ? "warn" : largeIndexBackfillCheck,
+      }),
+    );
+  }
+
+  const stagedValidatorDeletionCheck = options.stagedValidatorDeletionCheck;
+  if (stagedValidatorDeletionCheck !== "no verification") {
+    await parentSpan.enterAsync(
+      "checkForStagedValidatorDeletion",
+      async (span) => {
+        const response = await schemaEvaluation(span);
+        await checkForStagedValidatorDeletion({
+          ctx,
+          response,
+          askForConfirmation:
+            stagedValidatorDeletionCheck === "ask for confirmation",
+          // A dry run previews the confirmation required by a real push.
+          dryRun: options.dryRun,
+        });
+      },
+    );
+  }
+
+  // A real push evaluates the schema only when the evaluation is already
+  // paid for by the unstaging check or the pushed schema stages a validator,
+  // so `dev` pushes of ordinary schemas skip the isolate evaluation and round
+  // trip that the status report would otherwise add on every save.
+  if (
+    options.warnOnSlowSchemaValidation &&
+    (options.dryRun ||
+      stagedValidatorDeletionCheck !== "no verification" ||
+      pushStagesValidators(startPushRequest))
+  ) {
+    await parentSpan.enterAsync("checkForSlowSchemaValidation", (span) =>
+      checkForSlowSchemaValidation({
+        span,
+        schemaEvaluation,
+        dryRun: options.dryRun,
       }),
     );
   }

package/src/cli/lib/config.ts

@@ -42,6 +42,7 @@ import {
 } from "./localDeployment/errors.js";
 import { debugIsolateBundlesSerially } from "../../bundler/debugBundle.js";
 import { DeploymentType } from "./api.js";
+import { isAnonymousDeployment } from "./deployment.js";
 export { productionProvisionHost, provisionHost } from "./utils/utils.js";
 
 /** Type representing WorkOS AuthKit integration configuration. */
@@ -672,7 +673,7 @@ export async function configFromProjectConfig(
   }
   const modules = convexResult.modules;
   modules.push(...nodeResult.modules);
-  modules.push(...(await bundleAuthConfig(ctx, baseDir)));
+  modules.push(...(await bundleAuthConfig(ctx, baseDir)).modules);
 
   const nodeDependencies: NodeDependency[] = [];
   for (const [moduleName, moduleVersion] of nodeResult.externalDependencies) {
@@ -911,6 +912,49 @@ export function diffConfig(
   return { diffString: diff };
 }
 
+export function setEnvVarsInstructions(
+  names: string[],
+  deploymentName: string | null,
+  deploymentType: DeploymentType | undefined,
+  deploymentUrl: string | undefined,
+): string {
+  // Name cloud deployments explicitly: without a flag `env set` targets the
+  // project's default dev deployment, which may not be where this push went
+  // (e.g. `npx convex dev --deployment <other dev deployment>`). Local and
+  // anonymous deployments are always the default target.
+  let deploymentFlag = "";
+  if (
+    deploymentName !== null &&
+    deploymentType !== "local" &&
+    deploymentType !== "anonymous"
+  ) {
+    deploymentFlag = ` --deployment ${deploymentName}`;
+  } else if (deploymentType === "prod") {
+    deploymentFlag = " --prod";
+  } else if (deploymentName === null && deploymentUrl !== undefined) {
+    // Pushes via `--url`/`--admin-key` or self-hosted env vars have no
+    // deployment name. The admin key stays a placeholder to keep it out of
+    // terminal output.
+    deploymentFlag = ` --url ${deploymentUrl} --admin-key <admin key>`;
+  }
+  const commands = (names.length > 0 ? names : ["<NAME>"]).map(
+    (name) =>
+      `    ${chalkStderr.bold(`npx convex env set${deploymentFlag} ${name} <value>`)}`,
+  );
+  let instructions = `Set ${names.length > 1 ? "them" : "it"} with:\n\n${commands.join("\n")}\n`;
+  // Anonymous deployments are only reachable from the local dashboard, which
+  // `deploymentDashboardUrlPage` can't address.
+  if (deploymentName !== null && !isAnonymousDeployment(deploymentName)) {
+    const variableQuery = names.length === 1 ? `?var=${names[0]}` : "";
+    const dashboardUrl = deploymentDashboardUrlPage(
+      deploymentName,
+      `/settings/environment-variables${variableQuery}`,
+    );
+    instructions += `\nor in the dashboard:\n\n    ${chalkStderr.bold(dashboardUrl)}\n`;
+  }
+  return instructions;
+}
+
 /** Handle an error from
  * legacy push path:
  * - /api/push_config
@@ -934,7 +978,7 @@ export async function handlePushConfigError(
         deploymentNotice: string;
       }
     | undefined,
-  _deploymentType: DeploymentType | undefined,
+  deploymentType: DeploymentType | undefined,
 ): Promise<never> {
   const data: ErrorData | undefined =
     error instanceof ThrowingFetchError ? error.serverErrorData : undefined;
@@ -965,26 +1009,49 @@ export async function handlePushConfigError(
       `Environment variable ${chalkStderr.bold(
         variableName,
       )} is used in auth config file but ` + `its value was not set.`;
-    let setEnvVarInstructions =
-      "Go set it in the dashboard or using `npx convex env set`";
-
-    // If `npx convex dev` is running using --url there might not be a configured deployment
-    if (deploymentName !== null) {
-      const variableQuery =
-        variableName !== undefined ? `?var=${variableName}` : "";
-      const dashboardUrl = deploymentDashboardUrlPage(
-        deploymentName,
-        `/settings/environment-variables${variableQuery}`,
-      );
-      setEnvVarInstructions = `Go to:\n\n    ${chalkStderr.bold(
-        dashboardUrl,
-      )}\n\n  to set it up. `;
-    }
     await ctx.crash({
       exitCode: 1,
       errorType: "invalid filesystem or env vars",
       errForSentry: error,
-      printedMessage: envVarMessage + "\n" + setEnvVarInstructions,
+      printedMessage:
+        envVarMessage +
+        "\n" +
+        setEnvVarsInstructions(
+          variableName !== undefined ? [variableName] : [],
+          deploymentName,
+          deploymentType,
+          deployment?.deploymentUrl,
+        ),
+    });
+  }
+
+  if (data?.code === "MissingEnvironmentVariables") {
+    const errorMessage = data.message || "(no error message given)";
+    const [, namesList] = errorMessage.match(/are not set: ([^.]+)\./) ?? [];
+    const names = namesList?.split(", ") ?? [];
+    const envVarMessage =
+      names.length === 0
+        ? errorMessage
+        : names.length === 1
+          ? `Environment variable ${chalkStderr.bold(names[0])} is ` +
+            `declared as required in convex.config.ts but its value was not set.`
+          : `Environment variables ${names
+              .map((name) => chalkStderr.bold(name))
+              .join(", ")} are declared as required in convex.config.ts ` +
+            `but their values were not set.`;
+    await ctx.crash({
+      exitCode: 1,
+      errorType: "invalid filesystem or env vars",
+      errForSentry: error,
+      printedMessage:
+        envVarMessage +
+        "\n" +
+        setEnvVarsInstructions(
+          names,
+          deploymentName,
+          deploymentType,
+          deployment?.deploymentUrl,
+        ),
     });
   }
 

package/src/cli/lib/deploy2.ts

@@ -457,7 +457,9 @@ export async function deployToDeployment(
     writePushRequest?: string | undefined;
     liveComponentSources?: boolean | undefined;
     skipWorkosCheck?: boolean | undefined;
+    skipLargeIndexesCheck: boolean;
     allowDeletingLargeIndexes: boolean;
+    allowUnstagingSchema: boolean;
     message: string | null;
   },
 ) {
@@ -504,7 +506,14 @@ export async function deployToDeployment(
     writePushRequest: options.writePushRequest,
     liveComponentSources: !!options.liveComponentSources,
     pushAllModules: !!options.pushAllModules,
-    largeIndexDeletionCheck: options.allowDeletingLargeIndexes
+    largeIndexDeletionCheck:
+      options.skipLargeIndexesCheck || options.allowDeletingLargeIndexes
+        ? "has confirmation"
+        : "ask for confirmation",
+    largeIndexBackfillCheck: options.skipLargeIndexesCheck
+      ? "has confirmation"
+      : "ask for confirmation",
+    stagedValidatorDeletionCheck: options.allowUnstagingSchema
       ? "has confirmation"
       : "ask for confirmation",
     warnOnSlowSchemaValidation: true,

package/src/cli/lib/deployApi/evaluateSchema.ts

@@ -10,6 +10,7 @@ import { looseObject } from "./utils.js";
 export const tableValidationOutcome = z.enum([
   "notValidated",
   "supersetOfEnforced",
+  "supersetOfStagedValidated",
   "supersetOfShape",
   "mustWalk",
 ]);
@@ -24,11 +25,26 @@ export const indexChangePrediction = z.enum([
 ]);
 export type IndexChangePrediction = z.infer<typeof indexChangePrediction>;
 
+// Mirrors `StagedValidatorState` in
+// `crates/application/src/deploy_config.rs`.
+export const stagedValidatorState = z.union([
+  looseObject({
+    state: z.literal("pending"),
+    numDocsValidated: z.number(),
+    totalDocs: z.number().nullable().optional(),
+  }),
+  looseObject({ state: z.literal("valid") }),
+  looseObject({ state: z.literal("failed"), error: z.string() }),
+]);
+export type StagedValidatorState = z.infer<typeof stagedValidatorState>;
+
 export const tablePrediction = looseObject({
   name: z.string(),
   outcome: tableValidationOutcome,
   numDocs: z.number(),
   sizeBytes: z.number(),
+  staged: stagedValidatorState.optional(),
+  canSkipAfterStagedValidation: z.boolean().optional(),
 });
 export type TablePrediction = z.infer<typeof tablePrediction>;
 
@@ -42,11 +58,30 @@ export const indexPrediction = z.intersection(
 );
 export type IndexPrediction = z.infer<typeof indexPrediction>;
 
+// Mirrors `SerializedDiscardedStagedValidator` in
+// `crates/local_backend/src/deploy_config2.rs`. The backend never discards a
+// failed validator, since a redeploy retries it anyway.
+export const discardedStagedValidator = looseObject({
+  tableName: z.string(),
+  state: z.union([
+    looseObject({
+      state: z.literal("pending"),
+      numDocsValidated: z.number(),
+      totalDocs: z.number().nullable().optional(),
+    }),
+    looseObject({ state: z.literal("valid") }),
+  ]),
+  replaced: z.boolean(),
+});
+export type DiscardedStagedValidator = z.infer<typeof discardedStagedValidator>;
+
 export const componentSchemaPrediction = looseObject({
   definitionPath: z.string(),
   schemaValidation: z.boolean(),
   tables: z.array(tablePrediction),
   indexes: z.array(indexPrediction),
+  // Optional: responses from backends predating the field.
+  discardedStagedValidators: z.array(discardedStagedValidator).optional(),
 });
 export type ComponentSchemaPrediction = z.infer<
   typeof componentSchemaPrediction

package/src/cli/lib/dev.ts

@@ -60,6 +60,7 @@ export async function devAgainstDeployment(
     debugNodeApis: boolean;
     liveComponentSources: boolean;
     pushAllModules: boolean;
+    allowUnstagingSchema: boolean;
   },
 ) {
   const logManager = new LogManager(devOptions.tailLogs);
@@ -148,6 +149,19 @@ export async function devAgainstDeployment(
         pushAllModules: devOptions.pushAllModules,
         logManager, // Pass logManager to control logs during deploy
         largeIndexDeletionCheck: "no verification", // `convex dev` can’t push to prod
+        // `convex dev --prod` pushes straight to production, where an
+        // unstaged index on a large table blocks the push for the whole
+        // backfill; dev deployments are small enough to let it through.
+        largeIndexBackfillCheck:
+          credentials.deploymentType === "prod"
+            ? "ask for confirmation"
+            : "no verification",
+        stagedValidatorDeletionCheck:
+          credentials.deploymentType === "prod"
+            ? devOptions.allowUnstagingSchema
+              ? "has confirmation"
+              : "ask for confirmation"
+            : "no verification",
         warnOnSlowSchemaValidation: true,
         message: null,
       },

package/src/cli/lib/formatValidationProgress.ts

@@ -0,0 +1,35 @@
+import { chalkStderr } from "chalk";
+import { DiscardedStagedValidator } from "./deployApi/evaluateSchema.js";
+
+export function formatValidationProgress({
+  numDocsValidated,
+  totalDocs,
+}: {
+  numDocsValidated: number;
+  totalDocs?: number | null | undefined;
+}): string {
+  const checked = numDocsValidated.toLocaleString();
+  return totalDocs === null || totalDocs === undefined
+    ? `${checked} documents checked`
+    : `${checked} of approximately ${totalDocs.toLocaleString()} documents checked`;
+}
+
+/** "validated; the push removes the staged validator" */
+export function formatDiscardedStagedValidator(
+  validator: DiscardedStagedValidator,
+): string {
+  let status;
+  switch (validator.state.state) {
+    case "pending": {
+      status = `validating in the background (${formatValidationProgress(validator.state)})`;
+      break;
+    }
+    case "valid":
+      status = chalkStderr.green("validated");
+      break;
+  }
+  const action = validator.replaced
+    ? "the push stages a different validator"
+    : "the push removes the staged validator";
+  return `${status}; ${action}`;
+}

package/src/cli/lib/indexes.ts

@@ -27,7 +27,7 @@ export type LargeIndexDeletionCheck =
   | "no verification"
   // If large indexes are being deleted, ask for confirmation (and fail in non-interactive envs)
   | "ask for confirmation"
-  // If large indexes are being deleted, confirm (the user has used --allow-deleting-large-indexes)
+  // If large indexes are being deleted, confirm (the user has used --skip-large-indexes-check)
   | "has confirmation";
 
 export function addProgressLinkIfSlow(

package/src/cli/lib/mcp/tools/env.ts

@@ -12,13 +12,22 @@ const envListInputSchema = z.object({
     .describe(
       "Deployment selector (from the status tool) to list environment variables from.",
     ),
+  includeValues: z
+    .boolean()
+    .optional()
+    .describe(
+      "Also return each variable's value. Values are often secrets like API keys, so leave this off unless you need every value, and use envGet to read a single variable instead.",
+    ),
 });
 
 const envListOutputSchema = z.object({
   variables: z.array(
     z.object({
       name: z.string(),
-      value: z.string(),
+      value: z
+        .string()
+        .optional()
+        .describe("Only present when includeValues is true."),
     }),
   ),
 });
@@ -28,7 +37,8 @@ export const EnvListTool: ConvexTool<
   typeof envListOutputSchema
 > = {
   name: "envList",
-  description: "List all environment variables in your Convex deployment.",
+  description:
+    "List the names of all environment variables in your Convex deployment. Values are left out unless includeValues is true.",
   inputSchema: envListInputSchema,
   outputSchema: envListOutputSchema,
   handler: async (ctx, args) => {
@@ -51,7 +61,11 @@ export const EnvListTool: ConvexTool<
       componentPath: undefined,
       args: {},
     })) as EnvVar[];
-    return { variables };
+    return {
+      variables: variables.map(({ name, value }) =>
+        args.includeValues ? { name, value } : { name },
+      ),
+    };
   },
 };
 

package/src/cli/lib/run.ts

@@ -535,6 +535,8 @@ export async function pushToDeployment(
       liveComponentSources: args.liveComponentSources,
       pushAllModules: false,
       largeIndexDeletionCheck: "no verification", // `convex run` can’t push to prod
+      largeIndexBackfillCheck: "no verification", // ditto
+      stagedValidatorDeletionCheck: "no verification", // ditto
       warnOnSlowSchemaValidation: true,
       message: null,
     },

package/src/cli/lib/schemaEvaluation.ts

@@ -0,0 +1,88 @@
+import { Context } from "../../bundler/context.js";
+import { logVerbose } from "../../bundler/log.js";
+import { EvaluateSchemaResponse } from "./deployApi/evaluateSchema.js";
+import { StartPushRequest } from "./deployApi/startPush.js";
+import { evaluateSchema } from "./deploy2.js";
+import { Span } from "./tracing.js";
+
+type EvaluateOptions = {
+  url: string;
+  deploymentName: string | null;
+  adminKey: string;
+};
+
+/**
+ * A schema evaluation shared by the pre-push checks. Resolves to `null` when
+ * the deployment doesn't support `evaluate_schema` or the request failed, in
+ * which case each check skips itself.
+ */
+export type SchemaEvaluation = (
+  span: Span,
+) => Promise<EvaluateSchemaResponse | null>;
+
+/**
+ * Evaluate the schema at most once per push however many checks consume it:
+ * the first check to call sends the request under its own span, and the rest
+ * await the same promise. Each request makes the backend evaluate the schema
+ * module in an isolate and predict against a fresh snapshot, so repeating it
+ * per check would add that work and a round trip to the deploy's critical
+ * path for every check.
+ */
+/**
+ * Whether a schema module in the push calls `.staged(`. Bundles aren't
+ * minified, so the call survives bundling. A false positive from a comment or
+ * string costs one evaluation, while a push without staged validators skips
+ * the evaluation round trip on its critical path.
+ */
+export function pushStagesValidators(request: StartPushRequest): boolean {
+  return [
+    request.appDefinition.schema,
+    ...request.componentDefinitions.map((definition) => definition.schema),
+  ].some((schema) => schema?.source.includes(".staged(") ?? false);
+}
+
+export function sharedSchemaEvaluation(
+  ctx: Context,
+  request: StartPushRequest,
+  options: EvaluateOptions,
+): SchemaEvaluation {
+  let evaluation: Promise<EvaluateSchemaResponse | null> | undefined;
+  return (span) => {
+    evaluation ??= evaluateSchemaBestEffort({ ctx, span, request, options });
+    return evaluation;
+  };
+}
+
+// The checks are advisory: if evaluation fails, fall back to skipping them
+// rather than aborting the push over a check that isn't required for
+// correctness. Plausibly transient failures — network errors and 5xx
+// responses (e.g. table summaries still bootstrapping) — are retried with
+// backoff by the shared fetch wrapper (see `pushCode`); anything else is
+// deterministic, including a 2xx whose shape the CLI doesn't recognize, so
+// it skips the checks immediately.
+async function evaluateSchemaBestEffort({
+  ctx,
+  span,
+  request,
+  options,
+}: {
+  ctx: Context;
+  span: Span;
+  request: StartPushRequest;
+  options: EvaluateOptions;
+}): Promise<EvaluateSchemaResponse | null> {
+  try {
+    return await evaluateSchema(
+      ctx,
+      span,
+      request,
+      options,
+      /* bestEffort */ true,
+    );
+  } catch (error: unknown) {
+    logVerbose(
+      `Skipping schema evaluation checks: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    return null;
+  }
+}

package/src/cli/lib/usageLimits.ts

@@ -21,6 +21,7 @@ export const USAGE_LIMIT_METRICS = [
   "databaseIoGb",
   "searchQueryGb",
   "dataEgressGb",
+  "aiGatewayCostDollars",
 ] as const satisfies readonly UsageLimitMetric[];
 
 // Fails to compile if the backend's `UsageLimitMetric` gains a metric not listed
@@ -47,6 +48,7 @@ export const METRIC_LABELS: Record<UsageLimitMetric, string> = {
   databaseIoGb: "Database I/O",
   searchQueryGb: "Search queries",
   dataEgressGb: "Data egress",
+  aiGatewayCostDollars: "AI Gateway",
 };
 
 export function metricLabel(metric: string): string {

package/src/cli/lib/utils/mutex.ts

@@ -1,32 +1,14 @@
 export class Mutex {
-  currentlyRunning: Promise<void> | null = null;
-  waiting: Array<() => Promise<void>> = [];
+  private tail: Promise<void> = Promise.resolve();
 
   async runExclusive<T>(fn: () => Promise<T>): Promise<T> {
-    const outerPromise = new Promise<T>((resolve, reject) => {
-      const wrappedCallback: () => Promise<void> = () => {
-        return fn()
-          .then((v: T) => resolve(v))
-          .catch((e: any) => reject(e));
-      };
-      this.enqueueCallbackForMutex(wrappedCallback);
-    });
-    return outerPromise;
-  }
-
-  private enqueueCallbackForMutex(callback: () => Promise<void>) {
-    if (this.currentlyRunning === null) {
-      this.currentlyRunning = callback().finally(() => {
-        const nextCb = this.waiting.shift();
-        if (nextCb === undefined) {
-          this.currentlyRunning = null;
-        } else {
-          this.enqueueCallbackForMutex(nextCb);
-        }
-      });
-      this.waiting.length = 0;
-    } else {
-      this.waiting.push(callback);
-    }
+    const result = this.tail.then(fn);
+    // Reserve the next position before running fn, and allow the queue to
+    // continue even if fn rejects or throws synchronously.
+    this.tail = result.then(
+      () => {},
+      () => {},
+    );
+    return result;
   }
 }