Add validate (dry-run) mode to JDBC connection string

Introduce `mode=validate`, a dry-run flavor alongside `mode=apply`. In
validate mode every DDL statement (CREATE, DROP, FIRE/PAUSE/RESUME) is
fully parsed, planned, and validated — including deployer-level
validation — but no real object is created, updated, or deleted, and no
specs are emitted. With respect to OR REPLACE, validate behaves like
apply: an already-existing resource is treated as an in-place update
rather than an error.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: ryannedolan

docs/user-guide/ddl-reference.md

@@ -50,6 +50,28 @@ remains imperative and explicit. Detection of *incompatible* metadata changes
 `CREATE` and `CREATE OR REPLACE` apply the new definition regardless. Use
 caution when changing schemas of in-flight pipelines.
 
+## Dry-run: validate mode
+
+`mode=validate` is a dry-run. Every statement — `CREATE`, `DROP`, and the
+trigger verbs (`FIRE`/`PAUSE`/`RESUME`) — is fully parsed, planned, and
+validated (including deployer-level validation), but **no real object is ever
+created, updated, or deleted.** A statement that would succeed reports
+`(0 rows modified)`; a statement that would fail validation raises the same
+error a real run would. Use it to check a script against a live environment
+without touching anything:
+
+```
+jdbc:hoptimator://...;mode=validate
+```
+
+With respect to `OR REPLACE`, `validate` behaves like `apply`: an
+already-existing resource is treated as an in-place update, so a plain
+`CREATE` over an existing object validates cleanly instead of erroring.
+Unlike the YAML preview produced by the SPECIFY path, `validate` emits no
+specs — it is purely a pass/fail validation. `validate`, `apply`, and `create`
+are mutually exclusive; pick one per connection.
+
+
 ## CREATE VIEW
 
 ```

hoptimator-jdbc/src/main/java/com/linkedin/hoptimator/jdbc/HoptimatorDdlExecutor.java

@@ -130,7 +130,11 @@ public void execute(SqlCreateView create, CalcitePrepare.Context context) {
           throw new DdlException(create,
               "View " + pair.right + " already exists. Use CREATE OR REPLACE to update.");
         }
-        pair.left.removeFunction(pair.right);
+        // Only mutate the in-memory schema when we are actually deploying. In dry-run
+        // (VALIDATE) we leave the existing definition untouched.
+        if (mode.mutable()) {
+          pair.left.removeFunction(pair.right);
+        }
       }
     }
 
@@ -152,16 +156,20 @@ public void execute(SqlCreateView create, CalcitePrepare.Context context) {
       deployers = DeploymentService.deployers(view, connection);
       ValidationService.validateOrThrow(deployers, connection);
       logger.info("Validated view {}", viewName);
-      if (mode == HoptimatorDdlUtils.DdlMode.UPDATE) {
-        logger.info("Deploying update view {}", viewName);
-        DeploymentService.update(deployers);
+      if (mode == HoptimatorDdlUtils.DdlMode.VALIDATE) {
+        logger.info("Validated view (dry-run) {}; skipping deployment", viewName);
       } else {
-        logger.info("Deploying create view {}", viewName);
-        DeploymentService.create(deployers);
+        if (mode == HoptimatorDdlUtils.DdlMode.UPDATE) {
+          logger.info("Deploying update view {}", viewName);
+          DeploymentService.update(deployers);
+        } else {
+          logger.info("Deploying create view {}", viewName);
+          DeploymentService.create(deployers);
+        }
+        logger.info("Deployed view {}", viewName);
+        schemaPlus.add(viewName, viewTable);
+        logger.info("Added view {} to schema {}", viewName, schemaPlus.getName());
       }
-      logger.info("Deployed view {}", viewName);
-      schemaPlus.add(viewName, viewTable);
-      logger.info("Added view {} to schema {}", viewName, schemaPlus.getName());
     } catch (SQLException | RuntimeException e) {
       logger.info("Failed to deploy view {}", viewName);
       if (deployers != null) {
@@ -241,14 +249,18 @@ public void execute(SqlCreateTrigger create, CalcitePrepare.Context context) {
       ValidationService.validateOrThrow(deployers, connection);
       logger.info("Validated trigger {}", name);
       HoptimatorDdlUtils.DdlMode mode = HoptimatorDdlUtils.effectiveMode(create.getReplace(), connection);
-      if (mode == HoptimatorDdlUtils.DdlMode.UPDATE) {
-        logger.info("Updating trigger {}", name);
-        DeploymentService.update(deployers);
+      if (mode == HoptimatorDdlUtils.DdlMode.VALIDATE) {
+        logger.info("Validated trigger (dry-run) {}; skipping deployment", name);
       } else {
-        logger.info("Creating trigger {}", name);
-        DeploymentService.create(deployers);
+        if (mode == HoptimatorDdlUtils.DdlMode.UPDATE) {
+          logger.info("Updating trigger {}", name);
+          DeploymentService.update(deployers);
+        } else {
+          logger.info("Creating trigger {}", name);
+          DeploymentService.create(deployers);
+        }
+        logger.info("Deployed trigger {}", name);
       }
-      logger.info("Deployed trigger {}", name);
       logger.info("CREATE TRIGGER {} completed", name);
     } catch (Exception e) {
       if (deployers != null) {
@@ -336,7 +348,11 @@ public void execute(SqlFireTrigger fire, CalcitePrepare.Context context) {
     try {
       logger.info("Firing trigger {} with {} option(s)", name, options.size() - 1);
       deployers = DeploymentService.deployers(trigger, connection);
-      DeploymentService.update(deployers);
+      if (HoptimatorDdlUtils.isValidateMode(connection)) {
+        logger.info("Validated FIRE TRIGGER (dry-run) {}; skipping deployment", name);
+      } else {
+        DeploymentService.update(deployers);
+      }
       logger.info("FIRE TRIGGER {} completed", name);
     } catch (Exception e) {
       if (deployers != null) {
@@ -366,8 +382,12 @@ public void execute(SqlDropTrigger drop, CalcitePrepare.Context context) {
     try {
       logger.info("Deleting trigger {}", name);
       deployers = DeploymentService.deployers(trigger, connection);
-      DeploymentService.delete(deployers);
-      logger.info("Deleted trigger {}", name);
+      if (HoptimatorDdlUtils.isValidateMode(connection)) {
+        logger.info("Validated DROP TRIGGER (dry-run) {}; skipping deletion", name);
+      } else {
+        DeploymentService.delete(deployers);
+        logger.info("Deleted trigger {}", name);
+      }
       logger.info("DROP TRIGGER {} completed", name);
     } catch (Exception e) {
       if (deployers != null) {
@@ -403,7 +423,11 @@ private void updateTriggerPausedState(SqlNode sqlNode, SqlIdentifier triggerName
     try {
       logger.info("Updating trigger {} with paused state: {}", name, paused);
       deployers = DeploymentService.deployers(trigger, connection);
-      DeploymentService.update(deployers);
+      if (HoptimatorDdlUtils.isValidateMode(connection)) {
+        logger.info("Validated paused-state update (dry-run) for trigger {}; skipping deployment", name);
+      } else {
+        DeploymentService.update(deployers);
+      }
       logger.info("Successfully updated trigger {} with paused state: {}", name, paused);
     } catch (Exception e) {
       if (deployers != null) {
@@ -450,6 +474,7 @@ public void execute(SqlDropObject drop, CalcitePrepare.Context context) {
     tablePath.add(tableName);
 
     Collection<Deployer> deployers = null;
+    final boolean dryRun = HoptimatorDdlUtils.isValidateMode(connection);
     try {
       if (table instanceof MaterializedViewTable) {
         if (!(drop instanceof SqlDropMaterializedView)) {
@@ -459,10 +484,14 @@ public void execute(SqlDropObject drop, CalcitePrepare.Context context) {
         MaterializedViewTable materializedViewTable = (MaterializedViewTable) table;
         View view = new View(tablePath, materializedViewTable.viewSql());
         deployers = DeploymentService.deployers(view, connection);
-        logger.info("Deleting materialized view {}", tableName);
-        DeploymentService.delete(deployers);
-        schemaPlus.removeTable(tableName);
-        logger.info("Removed materialized table {} from schema {}", tableName, schemaPlus.getName());
+        if (dryRun) {
+          logger.info("Validated DROP (dry-run) for materialized view {}; skipping deletion", tableName);
+        } else {
+          logger.info("Deleting materialized view {}", tableName);
+          DeploymentService.delete(deployers);
+          schemaPlus.removeTable(tableName);
+          logger.info("Removed materialized table {} from schema {}", tableName, schemaPlus.getName());
+        }
       } else if (table instanceof ViewTable) {
         if (!(drop instanceof SqlDropView)) {
           throw new DdlException(drop,
@@ -471,10 +500,14 @@ public void execute(SqlDropObject drop, CalcitePrepare.Context context) {
         ViewTable viewTable = (ViewTable) table;
         View view = new View(tablePath, viewTable.getViewSql());
         deployers = DeploymentService.deployers(view, connection);
-        logger.info("Deleting view {}", tableName);
-        DeploymentService.delete(deployers);
-        schemaPlus.removeTable(tableName);
-        logger.info("Removed view {} from schema {}", tableName, schemaPlus.getName());
+        if (dryRun) {
+          logger.info("Validated DROP (dry-run) for view {}; skipping deletion", tableName);
+        } else {
+          logger.info("Deleting view {}", tableName);
+          DeploymentService.delete(deployers);
+          schemaPlus.removeTable(tableName);
+          logger.info("Removed view {} from schema {}", tableName, schemaPlus.getName());
+        }
       } else if (table instanceof HoptimatorJdbcTable || table instanceof TemporaryTable) {
         if (!(drop instanceof SqlDropTable)) {
           throw new DdlException(drop,
@@ -491,13 +524,17 @@ public void execute(SqlDropObject drop, CalcitePrepare.Context context) {
         }
         // Pre-delete dependency guard. PendingDelete is the explicit "delete intent" signal
         // — only validators that key off it (the K8s dep checker) fire here. The check throws
-        // before any deployer-level state change.
+        // before any deployer-level state change. This validation runs in dry-run too.
         ValidationService.validateOrThrow(new PendingDelete<>(source), connection);
         deployers = DeploymentService.deployers(source, connection);
-        logger.info("Deleting table {}", tableName);
-        DeploymentService.delete(deployers);
-        schemaPlus.removeTable(tableName);
-        logger.info("Removed table {} from schema {}", tableName, schemaPlus.getName());
+        if (dryRun) {
+          logger.info("Validated DROP (dry-run) for table {}; skipping deletion", tableName);
+        } else {
+          logger.info("Deleting table {}", tableName);
+          DeploymentService.delete(deployers);
+          schemaPlus.removeTable(tableName);
+          logger.info("Removed table {} from schema {}", tableName, schemaPlus.getName());
+        }
       } else {
         throw new SQLException(String.format("Unsupported drop type %s.", table.getClass().getSimpleName()));
       }

hoptimator-jdbc/src/main/java/com/linkedin/hoptimator/jdbc/HoptimatorDdlUtils.java

@@ -98,6 +98,10 @@ private HoptimatorDdlUtils() {
    *   <li>{@code apply} — declarative, K8s-style reconciliation. Both {@code CREATE} and
    *       {@code CREATE OR REPLACE} converge the resource to the declared definition, so
    *       running the same script twice is a no-op. Idempotent by design.</li>
+   *   <li>{@code validate} — dry-run. Every statement is fully validated (and its deployers
+   *       resolved and validated) but no real object is ever created, updated, or deleted.
+   *       With respect to {@code OR REPLACE}, {@code validate} behaves like {@code apply}:
+   *       an already-existing resource is treated as an in-place update, not an error.</li>
    * </ul>
    *
    * <p>Set per connection on the JDBC URL, e.g. {@code jdbc:hoptimator://...;mode=apply}
@@ -111,15 +115,23 @@ private HoptimatorDdlUtils() {
   /** Apply-mode value of {@link #MODE_PROPERTY}. */
   public static final String MODE_APPLY = "apply";
 
+  /** Validate-only (dry-run) value of {@link #MODE_PROPERTY}. */
+  public static final String MODE_VALIDATE = "validate";
+
   /**
    * Resolves the effective {@link DdlMode} for a {@code CREATE} statement, combining the
    * statement's {@code OR REPLACE} flag with the connection's {@link #MODE_PROPERTY}.
    *
    * <p>In {@code create} mode (the default): {@code CREATE} → {@link DdlMode#CREATE} and
    * {@code CREATE OR REPLACE} → {@link DdlMode#UPDATE}. In {@code apply} mode: both forms
-   * resolve to {@link DdlMode#UPDATE}, making CREATE idempotent.
+   * resolve to {@link DdlMode#UPDATE}, making CREATE idempotent. In {@code validate} mode:
+   * both forms resolve to {@link DdlMode#VALIDATE}, a dry-run that validates but never
+   * mutates (and, like apply, never errors on an already-existing resource).
    */
   static DdlMode effectiveMode(boolean orReplace, HoptimatorConnection conn) {
+    if (isValidateMode(conn)) {
+      return DdlMode.VALIDATE;
+    }
     if (isApplyMode(conn)) {
       return DdlMode.UPDATE;
     }
@@ -128,12 +140,21 @@ static DdlMode effectiveMode(boolean orReplace, HoptimatorConnection conn) {
 
   /** Whether the connection is configured for apply-mode DDL. */
   static boolean isApplyMode(HoptimatorConnection conn) {
+    return modeIs(conn, MODE_APPLY);
+  }
+
+  /** Whether the connection is configured for validate-only (dry-run) DDL. */
+  static boolean isValidateMode(HoptimatorConnection conn) {
+    return modeIs(conn, MODE_VALIDATE);
+  }
+
+  private static boolean modeIs(HoptimatorConnection conn, String expected) {
     Properties props = conn.connectionProperties();
     if (props == null) {
       return false;
     }
     String mode = props.getProperty(MODE_PROPERTY, MODE_CREATE);
-    return MODE_APPLY.equalsIgnoreCase(mode);
+    return expected.equalsIgnoreCase(mode);
   }
 
   /**
@@ -198,6 +219,19 @@ List<String> executeDeployers(Collection<Deployer> deployers, Connection conn) t
         return specs;
       }
 
+      @Override
+      boolean mutable() {
+        return false;
+      }
+    },
+    VALIDATE {
+      @Override
+      List<String> executeDeployers(Collection<Deployer> deployers, Connection conn) {
+        // Dry-run: validation has already happened by the time we reach here. Perform no
+        // create/update/delete, and emit no specs — unlike SPECIFY, validate produces no output.
+        return Collections.emptyList();
+      }
+
       @Override
       boolean mutable() {
         return false;
@@ -368,11 +402,12 @@ static SpecifyResult processCreateMaterializedView(CalcitePrepare.Context ctx,
             "Cannot overwrite physical table " + pair.right + " with a view.");
       }
       // A view already exists. The executor pre-resolved apply-mode into DdlMode.UPDATE,
-      // so UPDATE always means "converge to this definition". Strict CREATE is the only
-      // path that errors. SPECIFY (dry-run) keeps the original syntax-driven preview so
-      // it accurately reflects what a real run would do.
+      // so UPDATE always means "converge to this definition". VALIDATE (dry-run) follows the
+      // same convergence semantics as apply, so it never errors on an existing resource.
+      // Strict CREATE is the only path that errors. SPECIFY (dry-run) keeps the original
+      // syntax-driven preview so it accurately reflects what a real run would do.
       boolean replaceExisting;
-      if (mode == DdlMode.UPDATE) {
+      if (mode == DdlMode.UPDATE || mode == DdlMode.VALIDATE) {
         replaceExisting = true;
       } else if (mode == DdlMode.CREATE) {
         if (!create.ifNotExists) {
@@ -447,14 +482,17 @@ static SpecifyResult processCreateMaterializedView(CalcitePrepare.Context ctx,
         logger.info("Deploying update materialized view {}", viewName);
       } else if (mode == DdlMode.CREATE) {
         logger.info("Deploying create materialized view {}", viewName);
+      } else if (mode == DdlMode.VALIDATE) {
+        logger.info("Validating (dry-run) materialized view {}", viewName);
       } else {
         logger.info("Specifying materialized view {}", viewName);
       }
       List<String> specs = mode.executeDeployers(deployers, conn);
       if (mode.mutable()) {
         logger.info("Deployed materialized view {}", viewName);
       } else {
-        // SPECIFY (dry-run): roll back any side effects made by deployers during specify().
+        // Non-mutating mode (SPECIFY/VALIDATE): roll back any side effects deployers may have
+        // made (none for VALIDATE). Harmless when nothing was changed.
         DeploymentService.restore(deployers);
       }
       success = true;
@@ -542,10 +580,10 @@ static SpecifyResult processCreateTable(CalcitePrepare.Context ctx, HoptimatorCo
 
     if (!isNewSchema && schemaPlus.tables().get(tableName) != null) {
       // Strict CREATE without IF NOT EXISTS is the only path that errors. UPDATE
-      // (apply mode or explicit OR REPLACE) targets the existing table; SPECIFY
-      // (dry-run) preserves its syntax-driven semantics.
+      // (apply mode or explicit OR REPLACE) and VALIDATE (dry-run, apply-like) target
+      // the existing table; SPECIFY (dry-run) preserves its syntax-driven semantics.
       boolean wouldFail;
-      if (mode == DdlMode.UPDATE) {
+      if (mode == DdlMode.UPDATE || mode == DdlMode.VALIDATE) {
         wouldFail = false;
       } else if (mode == DdlMode.CREATE) {
         wouldFail = !create.ifNotExists;
@@ -654,14 +692,17 @@ public RexNode newColumnDefaultValue(RelOptTable table, int iColumn,
         logger.info("Deploying update table {}", source);
       } else if (mode == DdlMode.CREATE) {
         logger.info("Deploying create table {}", source);
+      } else if (mode == DdlMode.VALIDATE) {
+        logger.info("Validating (dry-run) table {}", source);
       } else {
         logger.info("Specifying table {}", source);
       }
       List<String> specs = mode.executeDeployers(deployers, conn);
       if (mode.mutable()) {
         logger.info("Deployed table {}", source);
       } else {
-        // SPECIFY (dry-run): roll back any side effects made by deployers during specify()
+        // Non-mutating mode (SPECIFY/VALIDATE): roll back any side effects deployers may have
+        // made (none for VALIDATE). Harmless when nothing was changed.
         DeploymentService.restore(deployers);
       }
       success = true;