@rex0220/kintone-sql-tools 2.2.0 → 2.4.0

package/README.md

@@ -16,13 +16,13 @@ kintone アプリを SQL 風の構文で操作するツールセットです。
   - プラグイン: read-only バッチのみ（最終結果を表示）
 - **`ASSERT`（実行時ゲート。DML 前の件数ガード / CLI ヘルスチェック）**（v1.10.0）
 - サブテーブル仮想テーブル（`APP100$明細`）
-- CLI 拡張 `APP@profile`
-  - 同一 SQL 内で同一 APP の profile 混在を許可
-  - `INSERT/UPDATE/UPSERT` 対応、`DELETE` は未対応
-- CLI / MCP の論理アプリ参照 `LAPP_<NAME>`
-  - profile ごとの `logicalApps` で、同じ SQL を異なる物理アプリ ID へ安全に解決
-  - `APP100` は常に物理 ID 100 のまま（暗黙変換なし）
-  - `allowPhysicalAppRefs: false` で、その profile の物理 `APPxxx` 直接参照を禁止可能
+- CLI 拡張 `APP@profile`
+  - 同一 SQL 内で同一 APP の profile 混在を許可
+  - `INSERT/UPDATE/UPSERT` 対応、`DELETE` は未対応
+- CLI / MCP の論理アプリ参照 `LAPP_<NAME>`
+  - profile ごとの `logicalApps` で、同じ SQL を異なる物理アプリ ID へ安全に解決
+  - `APP100` は常に物理 ID 100 のまま（暗黙変換なし）
+  - `allowPhysicalAppRefs: false` で、その profile の物理 `APPxxx` 直接参照を禁止可能
 - `FROM` 省略 SELECT（例: `SELECT 'xxx' AS a`）
 
 ## インストール
@@ -50,11 +50,11 @@ npm run build:plugin
 
 ## 使い分け（CLI / Plugin）
 
-- CLI を使うケース:
+- CLI を使うケース:
   - DML を含むバッチ実行・SQL ファイル実行（`-f`）
   - CI/CD 連携
-  - `APP@profile` を使った環境切替
-  - `LAPP_<NAME>` を使った配置非依存 SQL
+  - `APP@profile` を使った環境切替
+  - `LAPP_<NAME>` を使った配置非依存 SQL
   - `--dry-run` / `EXPLAIN` による安全確認
 
 - Plugin を使うケース:
@@ -62,14 +62,14 @@ npm run build:plugin
   - 非エンジニア向けの運用
   - UI で結果確認したい場合
 
-- MCP を使うケース:
+- MCP を使うケース:
   - Claude 等の AI クライアントから kintone を照会・更新
-  - 一時テーブルで中間結果をサーバー内に保持し、AI のコンテキスト消費を抑えたい場合
-  - validation / EXPLAIN で論理名から最終的な物理アプリ ID への解決を確認したい場合
+  - 一時テーブルで中間結果をサーバー内に保持し、AI のコンテキスト消費を抑えたい場合
+  - validation / EXPLAIN で論理名から最終的な物理アプリ ID への解決を確認したい場合
 
 注意:
 
-- `APP@profile` と `LAPP_<NAME>[@profile]` は Node.js runtime（CLI / MCP）の拡張です。plugin 側では非対応です。
+- `APP@profile` と `LAPP_<NAME>[@profile]` は Node.js runtime（CLI / MCP）の拡張です。plugin 側では非対応です。
 
 ## 最短実行例（CLI）
 
@@ -104,39 +104,39 @@ node dist-cli/ksql.js --console --base-url https://example.cybozu.com --token xx
 - 既定: `./ksql.config.json`
 - profile 切替: `--profile <name>`
 
-例:
+例:
 
 ```bash
-node dist-cli/ksql.js --config ./ksql.config.json --profile dev -e "SELECT * FROM APP100"
-```
-
-論理アプリ参照を使う場合、profile ごとに論理名と物理 ID を定義します。
-
-```json
-{
-  "defaultProfile": "dev",
-  "profiles": {
-    "dev": {
-      "baseUrl": "https://dev.example.cybozu.com",
-      "logicalApps": { "ORDERS": 100 },
-      "tokenMap": { "APP100": "env:DEV_ORDERS_TOKEN" }
-    },
-    "prod": {
-      "baseUrl": "https://prod.example.cybozu.com",
-      "allowPhysicalAppRefs": false,
-      "logicalApps": { "ORDERS": 1200 },
-      "tokenMap": { "APP1200": "env:PROD_ORDERS_TOKEN" }
-    }
-  }
-}
-```
-
-```bash
-node dist-cli/ksql.js --config ./ksql.config.json --profile dev -e "SELECT * FROM LAPP_ORDERS"
-node dist-cli/ksql.js --config ./ksql.config.json --profile prod -e "SELECT * FROM LAPP_ORDERS"
-```
-
-どちらも同じ SQL ですが、前者は `APP100`、後者は `APP1200` に解決されます。`logicalApps` のキーは `LAPP_` を付けない ASCII 論理名です。`APP100`、`100`、`LAPP_ORDERS` は設定キーとして拒否されます。
+node dist-cli/ksql.js --config ./ksql.config.json --profile dev -e "SELECT * FROM APP100"
+```
+
+論理アプリ参照を使う場合、profile ごとに論理名と物理 ID を定義します。
+
+```json
+{
+  "defaultProfile": "dev",
+  "profiles": {
+    "dev": {
+      "baseUrl": "https://dev.example.cybozu.com",
+      "logicalApps": { "ORDERS": 100 },
+      "tokenMap": { "APP100": "env:DEV_ORDERS_TOKEN" }
+    },
+    "prod": {
+      "baseUrl": "https://prod.example.cybozu.com",
+      "allowPhysicalAppRefs": false,
+      "logicalApps": { "ORDERS": 1200 },
+      "tokenMap": { "APP1200": "env:PROD_ORDERS_TOKEN" }
+    }
+  }
+}
+```
+
+```bash
+node dist-cli/ksql.js --config ./ksql.config.json --profile dev -e "SELECT * FROM LAPP_ORDERS"
+node dist-cli/ksql.js --config ./ksql.config.json --profile prod -e "SELECT * FROM LAPP_ORDERS"
+```
+
+どちらも同じ SQL ですが、前者は `APP100`、後者は `APP1200` に解決されます。`logicalApps` のキーは `LAPP_` を付けない ASCII 論理名です。`APP100`、`100`、`LAPP_ORDERS` は設定キーとして拒否されます。
 
 ## CLI オプション
 
@@ -154,6 +154,7 @@ Options:
   -f, --file <path>          Execute SQL file
   --console                  Start interactive console mode
   --dry-run                  Parse and show execution plan only
+  --var <name=value>         Override a DECLARE variable (repeatable; not for secrets)
   --format <type>            Output format: table | json | jsonl | csv | markdown | md
                              (batch + json: prints one JSON envelope for the whole batch)
   --max-records <n>          Max records to fetch (default: 500)
@@ -236,7 +237,7 @@ Options:
 - [CLI / Console 仕様](docs/ksql_cli_console_spec.md)
 - [バッチ実行・一時テーブル仕様](docs/ksql_batch_temp_table_spec.md)
 - [MCP サーバー仕様](docs/ksql_mcp_server_spec.md) / [Claude Desktop への導入（MCPB）](docs/ksql_mcpb_claude_desktop_install.md)
-- [APP@profile 仕様](docs/cli_app_profile_spec.md)
+- [APP@profile 仕様](docs/cli_app_profile_spec.md)
 - [公開前チェックリスト](docs/internal/public_release_checklist.md)
 
 ## ライセンス

package/dist-cli/ksql.js

@@ -599,13 +599,14 @@ var Parser = class {
         const upper = tok.value.toUpperCase();
         if (upper === "CREATE") return this.parseCreateTempTable();
         if (upper === "DROP") return this.parseDropTempTable();
+        if (upper === "DECLARE") return this.parseDeclareVariable();
         break;
       }
       default:
         break;
     }
     throw new ParseError(
-      "SELECT / INSERT / UPDATE / DELETE / REORDER / WITH / SHOW / DESCRIBE / EXPLAIN / CREATE TEMP TABLE / DROP TEMP TABLE / SET / ASSERT \u306E\u3044\u305A\u308C\u304B\u3067\u59CB\u307E\u308B SQL \u6587\u304C\u5FC5\u8981\u3067\u3059",
+      "SELECT / INSERT / UPDATE / DELETE / REORDER / WITH / SHOW / DESCRIBE / EXPLAIN / CREATE TEMP TABLE / DROP TEMP TABLE / SET / DECLARE / ASSERT \u306E\u3044\u305A\u308C\u304B\u3067\u59CB\u307E\u308B SQL \u6587\u304C\u5FC5\u8981\u3067\u3059",
       tok
     );
   }
@@ -616,20 +617,48 @@ var Parser = class {
     this.expect("SET" /* SET */);
     const variable = this.expect("VARIABLE" /* VARIABLE */, "SET \u306E\u5F8C\u306B\u306F\u5909\u6570\u540D\uFF08\u4F8B: @name\uFF09\u304C\u5FC5\u8981\u3067\u3059");
     this.expect("=" /* EQ */);
-    const expr = this.parseScalarExpr();
+    const expr = this.parseScalarExpr("SET", true);
     return { type: "SET_VARIABLE", name: variable.value.slice(1).toLowerCase(), expr };
   }
-  /** SET RHS 専用。既存式パーサーで構文を読み、フィールド参照を明示的に拒否する。 */
-  parseScalarExpr() {
+  parseDeclareVariable() {
+    this.advance();
+    const variable = this.expect("VARIABLE" /* VARIABLE */, "DECLARE \u306E\u5F8C\u306B\u306F\u5909\u6570\u540D\uFF08\u4F8B: @name\uFF09\u304C\u5FC5\u8981\u3067\u3059");
+    this.expect("=" /* EQ */);
+    const expr = this.parseScalarExpr("DECLARE", false);
+    if (expr.type === "SCALAR_SUBQUERY") {
+      throw new ParseError("DECLARE \u306E\u65E2\u5B9A\u5024\u306B\u30B9\u30AB\u30E9\u30FC\u30B5\u30D6\u30AF\u30A8\u30EA\u306F\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093", this.peek());
+    }
+    return { type: "DECLARE_VARIABLE", name: variable.value.slice(1).toLowerCase(), default: expr };
+  }
+  /** SET / DECLARE RHS 専用。既存式パーサーで構文を読み、フィールド参照を明示的に拒否する。 */
+  parseScalarExpr(context, allowScalarSubquery) {
     const tok = this.peek();
     if (tok.kind === "VARIABLE" /* VARIABLE */) {
-      throw new ParseError("SET \u306E\u53F3\u8FBA\u3067\u306F\u4ED6\u306E\u5909\u6570\u3092\u53C2\u7167\u3067\u304D\u307E\u305B\u3093\uFF08Phase 1a\uFF09", tok);
+      throw new ParseError(`${context} \u306E\u53F3\u8FBA\u3067\u306F\u4ED6\u306E\u5909\u6570\u3092\u53C2\u7167\u3067\u304D\u307E\u305B\u3093`, tok);
     }
     if (tok.kind === "NULL" /* NULL */) {
-      throw new ParseError("SET \u306E\u53F3\u8FBA\u3067 NULL \u306F\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093\uFF08Phase 1a\uFF09", tok);
+      throw new ParseError(`${context} \u306E\u53F3\u8FBA\u3067 NULL \u306F\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093`, tok);
     }
     if (tok.kind === "(" /* LPAREN */ && this.peekAt(1).kind === "SELECT" /* SELECT */) {
-      throw new ParseError("SET \u306E\u30B9\u30AB\u30E9\u30FC\u30B5\u30D6\u30AF\u30A8\u30EA\u4EE3\u5165\u306F Phase 1b \u3067\u5BFE\u5FDC\u4E88\u5B9A\u3067\u3059", tok);
+      if (!allowScalarSubquery) {
+        throw new ParseError("DECLARE \u306E\u65E2\u5B9A\u5024\u306B\u30B9\u30AB\u30E9\u30FC\u30B5\u30D6\u30AF\u30A8\u30EA\u306F\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093", tok);
+      }
+      this.advance();
+      const query = this.parseSelect();
+      this.expect(")" /* RPAREN */);
+      if (this.isArithOp(this.peek().kind)) {
+        throw new ParseError(
+          "\u30B9\u30AB\u30E9\u30FC\u30B5\u30D6\u30AF\u30A8\u30EA\u306E\u5F8C\u306B\u7B97\u8853\u6F14\u7B97\u5B50\u306F\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093\u3002\u30B5\u30D6\u30AF\u30A8\u30EA\u5185\u3067\u8A08\u7B97\u3057\u3066\u304F\u3060\u3055\u3044",
+          this.peek()
+        );
+      }
+      const hasWildcard = query.columns.some(
+        (c) => c.type === "WILDCARD" || c.type === "PARENT_WILDCARD"
+      );
+      if (!hasWildcard && query.columns.length !== 1) {
+        throw new ParseError("scalar subquery in SET must return exactly 1 column.", tok);
+      }
+      return { type: "SCALAR_SUBQUERY", query };
     }
     if (tok.kind === "STRING" /* STRING */) {
       this.advance();
@@ -637,7 +666,7 @@ var Parser = class {
     }
     if (tok.kind === "LOGINUSER" /* LOGINUSER */) {
       throw new ParseError(
-        "SET \u306E\u53F3\u8FBA\u3067 LOGINUSER() \u306F\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093\uFF08\u5B9F\u884C\u74B0\u5883\u5171\u901A\u306E\u30ED\u30B0\u30A4\u30F3\u30E6\u30FC\u30B6\u30FC\u89E3\u6C7A\u306F\u672A\u5BFE\u5FDC\u3067\u3059\uFF09",
+        `${context} \u306E\u53F3\u8FBA\u3067 LOGINUSER() \u306F\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093\uFF08\u5B9F\u884C\u74B0\u5883\u5171\u901A\u306E\u30ED\u30B0\u30A4\u30F3\u30E6\u30FC\u30B6\u30FC\u89E3\u6C7A\u306F\u672A\u5BFE\u5FDC\u3067\u3059\uFF09`,
         tok
       );
     }
@@ -645,22 +674,22 @@ var Parser = class {
       return this.parseSqlValue();
     }
     const expr = this.parseArithAddSub();
-    this.rejectNonScalarExpr(expr, tok);
+    this.rejectNonScalarExpr(expr, tok, context);
     if (expr.type === "NUMBER" || expr.type === "STRING_FUNC" || expr.type === "ARITH") return expr;
-    throw new ParseError("SET \u306E\u53F3\u8FBA\u306B\u306F\u30D5\u30A3\u30FC\u30EB\u30C9\u53C2\u7167\u3092\u542B\u307E\u306A\u3044\u30B9\u30AB\u30E9\u30FC\u5F0F\u3092\u6307\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044", tok);
+    throw new ParseError(`${context} \u306E\u53F3\u8FBA\u306B\u306F\u30D5\u30A3\u30FC\u30EB\u30C9\u53C2\u7167\u3092\u542B\u307E\u306A\u3044\u30B9\u30AB\u30E9\u30FC\u5F0F\u3092\u6307\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044`, tok);
   }
-  rejectNonScalarExpr(node, tok) {
+  rejectNonScalarExpr(node, tok, context) {
     if (node.type === "STRING" || node.type === "NUMBER") return;
     if (node.type === "FIELD_REF" || node.type === "AGG_REF") {
-      throw new ParseError("SET \u306E\u53F3\u8FBA\u3067\u306F\u30D5\u30A3\u30FC\u30EB\u30C9\u53C2\u7167\u30FB\u96C6\u8A08\u95A2\u6570\u3092\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093", tok);
+      throw new ParseError(`${context} \u306E\u53F3\u8FBA\u3067\u306F\u30D5\u30A3\u30FC\u30EB\u30C9\u53C2\u7167\u30FB\u96C6\u8A08\u95A2\u6570\u3092\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093`, tok);
     }
     if (node.type === "ARITH" || node.type === "AGG_ARITH") {
-      this.rejectNonScalarExpr(node.left, tok);
-      this.rejectNonScalarExpr(node.right, tok);
+      this.rejectNonScalarExpr(node.left, tok, context);
+      this.rejectNonScalarExpr(node.right, tok, context);
       return;
     }
     if (node.type === "STRING_FUNC") {
-      for (const arg of node.args) this.rejectNonScalarExpr(arg, tok);
+      for (const arg of node.args) this.rejectNonScalarExpr(arg, tok, context);
     }
   }
   // ----------------------------------------------------------
@@ -2286,7 +2315,7 @@ function isDmlType(type) {
   return type === "INSERT" || type === "INSERT_SELECT" || type === "UPDATE" || type === "DELETE" || type === "UPSERT" || type === "UPSERT_SELECT" || type === "REORDER";
 }
 function isReadOnlyType(type) {
-  return type === "SELECT" || type === "UNION" || type === "WITH" || type === "EXPLAIN" || type === "SHOW_APPS" || type === "DESCRIBE" || type === "CREATE_TEMP_TABLE" || type === "DROP_TEMP_TABLE" || type === "SET_VARIABLE" || type === "ASSERT";
+  return type === "SELECT" || type === "UNION" || type === "WITH" || type === "EXPLAIN" || type === "SHOW_APPS" || type === "DESCRIBE" || type === "CREATE_TEMP_TABLE" || type === "DROP_TEMP_TABLE" || type === "SET_VARIABLE" || type === "DECLARE_VARIABLE" || type === "ASSERT";
 }
 function hasWhereClause(stmt) {
   if (!stmt || typeof stmt !== "object") return false;
@@ -2360,8 +2389,9 @@ function analyzeBatch(statements) {
   }
   if (statements.length === 1) {
     const t = statements[0].type;
-    if (t === "SET_VARIABLE") {
-      throw new BatchAnalysisError("ArgumentError: SET variable requires a batch.", 0);
+    if (t === "SET_VARIABLE" || t === "DECLARE_VARIABLE") {
+      const verb = t === "SET_VARIABLE" ? "SET" : "DECLARE";
+      throw new BatchAnalysisError(`ArgumentError: ${verb} variable requires a batch.`, 0);
     }
     if (t === "CREATE_TEMP_TABLE" || t === "DROP_TEMP_TABLE") {
       const verb = t === "CREATE_TEMP_TABLE" ? "CREATE TEMP TABLE" : "DROP TEMP TABLE";
@@ -2395,7 +2425,7 @@ function analyzeBatch(statements) {
       }
       def.referencedBy.push(index);
     }
-    if (stmt.type === "SET_VARIABLE") {
+    if (stmt.type === "SET_VARIABLE" || stmt.type === "DECLARE_VARIABLE") {
       if (variableDefs.has(stmt.name)) {
         throw new BatchAnalysisError(`ParseError: variable @${stmt.name} is already defined.`, index);
       }
@@ -2492,6 +2522,40 @@ function analyzeBatch(statements) {
   };
 }
 
+// src/core/batchVariables.ts
+var VARIABLE_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+function normalizeBatchVariableName(name) {
+  if (!VARIABLE_NAME_RE.test(name)) {
+    throw new Error(
+      `ArgumentError: invalid variable name "${name}". Use a name without @ matching [A-Za-z_][A-Za-z0-9_]{0,63}.`
+    );
+  }
+  return name.toLowerCase();
+}
+function normalizeBatchVariables(input) {
+  const normalized = /* @__PURE__ */ Object.create(null);
+  for (const [rawName, value] of Object.entries(input ?? {})) {
+    const name = normalizeBatchVariableName(rawName);
+    if (Object.prototype.hasOwnProperty.call(normalized, name)) {
+      throw new Error(`ArgumentError: variable "${rawName}" is specified more than once.`);
+    }
+    normalized[name] = value;
+  }
+  return normalized;
+}
+function validateDeclaredBatchVariables(statements, input) {
+  const normalized = normalizeBatchVariables(input);
+  const declared = new Set(
+    statements.filter((stmt) => stmt.type === "DECLARE_VARIABLE").map((stmt) => stmt.name)
+  );
+  for (const name of Object.keys(normalized)) {
+    if (!declared.has(name)) {
+      throw new Error(`ArgumentError: injected variable @${name} is not declared.`);
+    }
+  }
+  return normalized;
+}
+
 // src/core/scalarCompare.ts
 function compareScalarValues(op, leftStr, rightStr) {
   if (op === "=") return leftStr === rightStr;
@@ -4823,6 +4887,8 @@ async function executeParsedStatement(stmt, client, options, cacheContext) {
       throw new Error("ArgumentError: DROP TEMP TABLE requires a batch (temp tables are batch-scoped).");
     case "SET_VARIABLE":
       throw new Error("ArgumentError: SET variable requires a batch.");
+    case "DECLARE_VARIABLE":
+      throw new Error("ArgumentError: DECLARE variable requires a batch.");
     case "ASSERT":
       return executeAssert(stmt, client, options, cacheContext);
   }
@@ -4836,6 +4902,8 @@ var BatchTimeoutError = class extends Error {
 async function executeBatch(sql, client, options = {}) {
   const statements = parseSqlBatch(sql);
   const analysis = analyzeBatch(statements);
+  const injectedVariables = validateDeclaredBatchVariables(statements, options.variables);
+  const batchOptions = { ...options, variables: injectedVariables };
   if (options.continueOnError && analysis.containsDml) {
     throw new Error("ArgumentError: continueOnError is not allowed for batches containing DML.");
   }
@@ -4880,16 +4948,16 @@ async function executeBatch(sql, client, options = {}) {
     }
     try {
       const remaining = deadline !== null ? deadline - Date.now() : null;
-      const userConfirm = options.confirm;
+      const userConfirm = batchOptions.confirm;
       const stmtOptions = userConfirm ? {
-        ...options,
+        ...batchOptions,
         confirm: (count, operation) => userConfirm(count, operation, {
           statementIndex: i,
           statementCount: statements.length,
           statementType: info.statementType,
           targetAppId: info.targetAppId
         })
-      } : options;
+      } : batchOptions;
       const outcome = await runWithDeadline(
         executeBatchStatement(statements[i], info, countedClient, stmtOptions, cacheContext, tempTables, variables),
         remaining
@@ -4902,7 +4970,7 @@ async function executeBatch(sql, client, options = {}) {
         aborted = "timeout";
       } else if (e instanceof AssertError) {
         aborted = "assertion";
-      } else if (info.statementType === "SET_VARIABLE") {
+      } else if (info.statementType === "SET_VARIABLE" || info.statementType === "DECLARE_VARIABLE") {
         aborted = "fail-fast";
       } else if (!options.continueOnError) {
         aborted = "fail-fast";
@@ -4920,7 +4988,36 @@ async function executeBatch(sql, client, options = {}) {
 }
 async function executeBatchStatement(stmt, info, client, options, cacheContext, tempTables, variables) {
   if (stmt.type === "SET_VARIABLE") {
-    variables.set(stmt.name, evaluateScalarExpr(stmt.expr));
+    const resolvedStmt2 = resolveVariableRefs(stmt, variables);
+    if (resolvedStmt2.expr.type === "SCALAR_SUBQUERY") {
+      try {
+        const value = await evaluateScalarSubquery(
+          resolvedStmt2.expr.query,
+          client,
+          options,
+          cacheContext,
+          tempTables
+        );
+        variables.set(stmt.name, { type: "string", value });
+      } catch (e) {
+        if (e instanceof ScalarSubqueryError) {
+          throw new Error(`ArgumentError: ${e.message}`);
+        }
+        throw e;
+      }
+    } else {
+      variables.set(stmt.name, evaluateScalarExpr(resolvedStmt2.expr));
+    }
+    return {};
+  }
+  if (stmt.type === "DECLARE_VARIABLE") {
+    const injected = options.variables ?? {};
+    if (Object.prototype.hasOwnProperty.call(injected, stmt.name)) {
+      variables.set(stmt.name, { type: "string", value: injected[stmt.name] });
+    } else {
+      const value = evaluateScalarExpr(stmt.default);
+      variables.set(stmt.name, { type: "string", value: String(value.value) });
+    }
     return {};
   }
   const resolvedStmt = resolveVariableRefs(stmt, variables);
@@ -5083,6 +5180,12 @@ var AssertError = class extends Error {
     this.name = "AssertError";
   }
 };
+var ScalarSubqueryError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ScalarSubqueryError";
+  }
+};
 async function executeAssert(stmt, client, options, cacheContext, tempTables) {
   const left = await evalAssertOperand(stmt.left, client, options, cacheContext, tempTables);
   if (stmt.op === "BETWEEN") {
@@ -5116,25 +5219,38 @@ async function evalAssertOperand(operand, client, options, cacheContext, tempTab
     case "ARITH":
       return String(evalAssertArith(operand));
     case "SCALAR_SUBQUERY": {
-      const { query, probed } = withScalarProbeLimit(operand.query);
-      const result = await runSubquery(query, client, options, cacheContext, tempTables);
-      if (result.columns.length > 1) {
-        throw new AssertError(
-          `scalar subquery returned ${result.columns.length} columns (expected 1 column).`
+      try {
+        return await evaluateScalarSubquery(
+          operand.query,
+          client,
+          options,
+          cacheContext,
+          tempTables
         );
+      } catch (e) {
+        if (e instanceof ScalarSubqueryError) throw new AssertError(e.message);
+        throw e;
       }
-      if (result.rowCount === 0) {
-        throw new AssertError("scalar subquery returned no rows (expected 1 row).");
-      }
-      if (result.rowCount > 1) {
-        const rows = probed && result.rowCount === 2 ? "2 or more rows" : `${result.rowCount} rows`;
-        throw new AssertError(`scalar subquery returned ${rows} (expected 1 row).`);
-      }
-      const col = result.columns[0] ?? "";
-      return result.rows[0]?.[col] ?? "";
     }
   }
 }
+async function evaluateScalarSubquery(sourceQuery, client, options, cacheContext, tempTables) {
+  const { query, probed } = withScalarProbeLimit(sourceQuery);
+  const result = await runSubquery(query, client, options, cacheContext, tempTables);
+  if (result.columns.length !== 1) {
+    throw new ScalarSubqueryError(
+      `scalar subquery returned ${result.columns.length} columns (expected 1 column).`
+    );
+  }
+  if (result.rowCount === 0) {
+    throw new ScalarSubqueryError("scalar subquery returned no rows (expected 1 row).");
+  }
+  if (result.rowCount > 1) {
+    const rows = probed && result.rowCount === 2 ? "2 or more rows" : `${result.rowCount} rows`;
+    throw new ScalarSubqueryError(`scalar subquery returned ${rows} (expected 1 row).`);
+  }
+  return result.rows[0]?.[result.columns[0]] ?? "";
+}
 function withScalarProbeLimit(query) {
   const hasAgg = query.groupBy.length > 0 || query.columns.some((c) => c.type === "AGGREGATE" || c.type === "ARITH_AGG_COL");
   if (hasAgg || query.distinct || query.limit !== null) return { query, probed: false };
@@ -6629,20 +6745,21 @@ async function resolveScalarColumns(columns, client, options, cacheContext, cteC
   pending.forEach(([i], idx) => cache.set(i, values[idx]));
   return cache;
 }
-function buildBatchExplainPlans(sql) {
+function buildBatchExplainPlans(sql, injectedVariables) {
   const statements = parseSqlBatch(sql);
   const analysis = analyzeBatch(statements);
+  validateDeclaredBatchVariables(statements, injectedVariables);
   const variables = /* @__PURE__ */ new Map();
   return {
     statementCount: statements.length,
     statements: statements.map((stmt, i) => {
-      const planStmt = stmt.type === "SET_VARIABLE" ? stmt : resolveVariableRefs(stmt, variables);
+      const planStmt = stmt.type === "SET_VARIABLE" ? stmt.expr.type === "SCALAR_SUBQUERY" ? { ...stmt, expr: resolveVariableRefs(stmt.expr, variables) } : stmt : resolveVariableRefs(stmt, variables);
       const result = {
         index: i,
         type: analysis.statements[i].statementType,
         plan: buildBatchStatementPlan(planStmt, analysis.statements[i])
       };
-      if (stmt.type === "SET_VARIABLE") {
+      if (stmt.type === "SET_VARIABLE" || stmt.type === "DECLARE_VARIABLE") {
         variables.set(stmt.name, { type: "string", value: `@${stmt.name}` });
       }
       return result;
@@ -6665,11 +6782,26 @@ function buildBatchStatementPlan(stmt, info) {
     ];
   }
   if (stmt.type === "SET_VARIABLE") {
+    if (stmt.expr.type === "SCALAR_SUBQUERY") {
+      const subInfo = hasTempTableRef(stmt.expr.query) ? info : { ...info, tempTablesReferenced: [] };
+      return [
+        `SET @${stmt.name} = (SELECT ...)`,
+        "  value:         \u30B5\u30D6\u30AF\u30A8\u30EA\u3092\u5B9F\u884C\u6642\u306B1\u56DE\u8A55\u4FA1\uFF081\u884C1\u5217\u30FB\u30D0\u30C3\u30C1\u5185\u5B9A\u6570\u30FB\u7D50\u679C\u30E1\u30BF\u30C7\u30FC\u30BF\u306B\u306F\u975E\u516C\u958B\uFF09",
+        "  subquery:",
+        ...buildPlanForBatchQuery(stmt.expr.query, subInfo).map((l) => `  ${l}`)
+      ];
+    }
     return [
       `SET @${stmt.name} = <scalar expression>`,
       "  value:         \u5B9F\u884C\u6642\u306B1\u56DE\u8A55\u4FA1\uFF08\u30D0\u30C3\u30C1\u5185\u5B9A\u6570\u30FB\u7D50\u679C\u30E1\u30BF\u30C7\u30FC\u30BF\u306B\u306F\u975E\u516C\u958B\uFF09"
     ];
   }
+  if (stmt.type === "DECLARE_VARIABLE") {
+    return [
+      `DECLARE @${stmt.name} = <default scalar expression>`,
+      "  value:         \u5916\u90E8\u6CE8\u5165\u304C\u3042\u308C\u3070\u63A1\u7528\u3001\u306A\u3051\u308C\u3070\u65E2\u5B9A\u5024\u3092\u5B9F\u884C\u6642\u306B1\u56DE\u8A55\u4FA1\uFF08\u5024\u306F\u975E\u516C\u958B\uFF09"
+    ];
+  }
   if (stmt.type === "SHOW_APPS") return ["SHOW APPS\uFF08\u30A2\u30D7\u30EA\u4E00\u89A7\u306E\u53D6\u5F97\uFF09"];
   if (stmt.type === "DESCRIBE") return [`DESCRIBE APP${stmt.appId}\uFF08\u30D5\u30A3\u30FC\u30EB\u30C9\u5B9A\u7FA9\u306E\u53D6\u5F97\uFF09`];
   if (stmt.type === "EXPLAIN") return buildPlanForBatchQuery(stmt.query, info);
@@ -8131,6 +8263,7 @@ Options:
   -f, --file <path>          Execute SQL file
   --console                  Start interactive console mode
   --dry-run                  Parse and show execution plan only
+  --var <name=value>         Override a DECLARE variable (repeatable; not for secrets)
   --format <type>            Output format: table | json | jsonl | csv | markdown | md
                              (batch + json: prints one JSON envelope for the whole batch)
   --max-records <n>          Max records to fetch (default: 500)
@@ -8200,6 +8333,8 @@ function parseArgs(argv) {
     password: null,
     token: null,
     tokenMap: {},
+    // `__proto__` も有効な変数名なので prototype のない辞書で保持する。
+    variables: /* @__PURE__ */ Object.create(null),
     tokenFile: null,
     app: null,
     diagRecordId: null,
@@ -8294,6 +8429,19 @@ function parseArgs(argv) {
       continue;
     }
     const v = argv[i + 1];
+    if (a === "--var") {
+      const raw = v ?? "";
+      const eq = raw.indexOf("=");
+      if (eq < 0) throw new Error("ArgumentError: --var must use name=value.");
+      const rawName = raw.slice(0, eq);
+      const name = normalizeBatchVariableName(rawName);
+      if (Object.prototype.hasOwnProperty.call(out.variables, name)) {
+        throw new Error(`ArgumentError: variable "${rawName}" is specified more than once.`);
+      }
+      out.variables[name] = raw.slice(eq + 1);
+      i++;
+      continue;
+    }
     if (a === "-e" || a === "--execute") {
       out.executeSql = v ?? "";
       i++;
@@ -8850,6 +8998,7 @@ function buildReplExecArgv(base, sql, dryRun, format) {
   const argv = ["-e", sql];
   if (dryRun) argv.push("--dry-run");
   if (format) argv.push("--format", format);
+  for (const [name, value] of Object.entries(base.variables)) argv.push("--var", `${name}=${value}`);
   pushOpt(argv, "--config", base.configPath);
   pushOpt(argv, "--profile", base.profile);
   pushOpt(argv, "--base-url", base.baseUrl);
@@ -9473,6 +9622,10 @@ async function run() {
     attachmentFormat: args.attachmentFormat ?? profile.output?.attachmentFormat ?? "full"
   };
   const appIds = sql ? extractAppIds(sql) : [];
+  if (!isBatchSql && Object.keys(args.variables).length > 0) {
+    process.stderr.write("ArgumentError: --var requires a batch containing DECLARE.\n");
+    return 2;
+  }
   const defaultApp = args.app ?? envInt2("KSQL_APP") ?? profile.app ?? null;
   if (appIds.length === 0 && defaultApp !== null) appIds.push(defaultApp);
   const allowNoFromSelect = isNoFromSelectStatement(parsedStmt) || stmtType === "SHOW_APPS";
@@ -9488,7 +9641,7 @@ async function run() {
     if (args.dryRun) {
       let plans;
       try {
-        plans = buildBatchExplainPlans(sql);
+        plans = buildBatchExplainPlans(sql, args.variables);
       } catch (err) {
         const restored = sourceSql && sqlDiagnosticContext ? restoreSqlContextError(err, sourceSql, {
           bindings: sqlDiagnosticContext.appBindingByMappedApp,
@@ -9805,6 +9958,7 @@ query=${label}`);
         continueOnError: args.continueOnError,
         tempTableMaxRows,
         timeoutMs: timeout,
+        variables: args.variables,
         confirm: batchContainsDml ? async (count, operation) => {
           if (count > dmlMaxRows) {
             throw new Error(`ArgumentError: ${operation} affected rows (${count}) exceed --dml-max-rows (${dmlMaxRows}).`);

package/dist-mcp/ksql-mcp.js

@@ -31512,13 +31512,14 @@ var Parser = class {
         const upper = tok.value.toUpperCase();
         if (upper === "CREATE") return this.parseCreateTempTable();
         if (upper === "DROP") return this.parseDropTempTable();
+        if (upper === "DECLARE") return this.parseDeclareVariable();
         break;
       }
       default:
         break;
     }
     throw new ParseError(
-      "SELECT / INSERT / UPDATE / DELETE / REORDER / WITH / SHOW / DESCRIBE / EXPLAIN / CREATE TEMP TABLE / DROP TEMP TABLE / SET / ASSERT \u306E\u3044\u305A\u308C\u304B\u3067\u59CB\u307E\u308B SQL \u6587\u304C\u5FC5\u8981\u3067\u3059",
+      "SELECT / INSERT / UPDATE / DELETE / REORDER / WITH / SHOW / DESCRIBE / EXPLAIN / CREATE TEMP TABLE / DROP TEMP TABLE / SET / DECLARE / ASSERT \u306E\u3044\u305A\u308C\u304B\u3067\u59CB\u307E\u308B SQL \u6587\u304C\u5FC5\u8981\u3067\u3059",
       tok
     );
   }
@@ -31529,20 +31530,48 @@ var Parser = class {
     this.expect("SET" /* SET */);
     const variable = this.expect("VARIABLE" /* VARIABLE */, "SET \u306E\u5F8C\u306B\u306F\u5909\u6570\u540D\uFF08\u4F8B: @name\uFF09\u304C\u5FC5\u8981\u3067\u3059");
     this.expect("=" /* EQ */);
-    const expr = this.parseScalarExpr();
+    const expr = this.parseScalarExpr("SET", true);
     return { type: "SET_VARIABLE", name: variable.value.slice(1).toLowerCase(), expr };
   }
-  /** SET RHS 専用。既存式パーサーで構文を読み、フィールド参照を明示的に拒否する。 */
-  parseScalarExpr() {
+  parseDeclareVariable() {
+    this.advance();
+    const variable = this.expect("VARIABLE" /* VARIABLE */, "DECLARE \u306E\u5F8C\u306B\u306F\u5909\u6570\u540D\uFF08\u4F8B: @name\uFF09\u304C\u5FC5\u8981\u3067\u3059");
+    this.expect("=" /* EQ */);
+    const expr = this.parseScalarExpr("DECLARE", false);
+    if (expr.type === "SCALAR_SUBQUERY") {
+      throw new ParseError("DECLARE \u306E\u65E2\u5B9A\u5024\u306B\u30B9\u30AB\u30E9\u30FC\u30B5\u30D6\u30AF\u30A8\u30EA\u306F\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093", this.peek());
+    }
+    return { type: "DECLARE_VARIABLE", name: variable.value.slice(1).toLowerCase(), default: expr };
+  }
+  /** SET / DECLARE RHS 専用。既存式パーサーで構文を読み、フィールド参照を明示的に拒否する。 */
+  parseScalarExpr(context, allowScalarSubquery) {
     const tok = this.peek();
     if (tok.kind === "VARIABLE" /* VARIABLE */) {
-      throw new ParseError("SET \u306E\u53F3\u8FBA\u3067\u306F\u4ED6\u306E\u5909\u6570\u3092\u53C2\u7167\u3067\u304D\u307E\u305B\u3093\uFF08Phase 1a\uFF09", tok);
+      throw new ParseError(`${context} \u306E\u53F3\u8FBA\u3067\u306F\u4ED6\u306E\u5909\u6570\u3092\u53C2\u7167\u3067\u304D\u307E\u305B\u3093`, tok);
     }
     if (tok.kind === "NULL" /* NULL */) {
-      throw new ParseError("SET \u306E\u53F3\u8FBA\u3067 NULL \u306F\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093\uFF08Phase 1a\uFF09", tok);
+      throw new ParseError(`${context} \u306E\u53F3\u8FBA\u3067 NULL \u306F\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093`, tok);
     }
     if (tok.kind === "(" /* LPAREN */ && this.peekAt(1).kind === "SELECT" /* SELECT */) {
-      throw new ParseError("SET \u306E\u30B9\u30AB\u30E9\u30FC\u30B5\u30D6\u30AF\u30A8\u30EA\u4EE3\u5165\u306F Phase 1b \u3067\u5BFE\u5FDC\u4E88\u5B9A\u3067\u3059", tok);
+      if (!allowScalarSubquery) {
+        throw new ParseError("DECLARE \u306E\u65E2\u5B9A\u5024\u306B\u30B9\u30AB\u30E9\u30FC\u30B5\u30D6\u30AF\u30A8\u30EA\u306F\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093", tok);
+      }
+      this.advance();
+      const query = this.parseSelect();
+      this.expect(")" /* RPAREN */);
+      if (this.isArithOp(this.peek().kind)) {
+        throw new ParseError(
+          "\u30B9\u30AB\u30E9\u30FC\u30B5\u30D6\u30AF\u30A8\u30EA\u306E\u5F8C\u306B\u7B97\u8853\u6F14\u7B97\u5B50\u306F\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093\u3002\u30B5\u30D6\u30AF\u30A8\u30EA\u5185\u3067\u8A08\u7B97\u3057\u3066\u304F\u3060\u3055\u3044",
+          this.peek()
+        );
+      }
+      const hasWildcard = query.columns.some(
+        (c) => c.type === "WILDCARD" || c.type === "PARENT_WILDCARD"
+      );
+      if (!hasWildcard && query.columns.length !== 1) {
+        throw new ParseError("scalar subquery in SET must return exactly 1 column.", tok);
+      }
+      return { type: "SCALAR_SUBQUERY", query };
     }
     if (tok.kind === "STRING" /* STRING */) {
       this.advance();
@@ -31550,7 +31579,7 @@ var Parser = class {
     }
     if (tok.kind === "LOGINUSER" /* LOGINUSER */) {
       throw new ParseError(
-        "SET \u306E\u53F3\u8FBA\u3067 LOGINUSER() \u306F\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093\uFF08\u5B9F\u884C\u74B0\u5883\u5171\u901A\u306E\u30ED\u30B0\u30A4\u30F3\u30E6\u30FC\u30B6\u30FC\u89E3\u6C7A\u306F\u672A\u5BFE\u5FDC\u3067\u3059\uFF09",
+        `${context} \u306E\u53F3\u8FBA\u3067 LOGINUSER() \u306F\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093\uFF08\u5B9F\u884C\u74B0\u5883\u5171\u901A\u306E\u30ED\u30B0\u30A4\u30F3\u30E6\u30FC\u30B6\u30FC\u89E3\u6C7A\u306F\u672A\u5BFE\u5FDC\u3067\u3059\uFF09`,
         tok
       );
     }
@@ -31558,22 +31587,22 @@ var Parser = class {
       return this.parseSqlValue();
     }
     const expr = this.parseArithAddSub();
-    this.rejectNonScalarExpr(expr, tok);
+    this.rejectNonScalarExpr(expr, tok, context);
     if (expr.type === "NUMBER" || expr.type === "STRING_FUNC" || expr.type === "ARITH") return expr;
-    throw new ParseError("SET \u306E\u53F3\u8FBA\u306B\u306F\u30D5\u30A3\u30FC\u30EB\u30C9\u53C2\u7167\u3092\u542B\u307E\u306A\u3044\u30B9\u30AB\u30E9\u30FC\u5F0F\u3092\u6307\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044", tok);
+    throw new ParseError(`${context} \u306E\u53F3\u8FBA\u306B\u306F\u30D5\u30A3\u30FC\u30EB\u30C9\u53C2\u7167\u3092\u542B\u307E\u306A\u3044\u30B9\u30AB\u30E9\u30FC\u5F0F\u3092\u6307\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044`, tok);
   }
-  rejectNonScalarExpr(node, tok) {
+  rejectNonScalarExpr(node, tok, context) {
     if (node.type === "STRING" || node.type === "NUMBER") return;
     if (node.type === "FIELD_REF" || node.type === "AGG_REF") {
-      throw new ParseError("SET \u306E\u53F3\u8FBA\u3067\u306F\u30D5\u30A3\u30FC\u30EB\u30C9\u53C2\u7167\u30FB\u96C6\u8A08\u95A2\u6570\u3092\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093", tok);
+      throw new ParseError(`${context} \u306E\u53F3\u8FBA\u3067\u306F\u30D5\u30A3\u30FC\u30EB\u30C9\u53C2\u7167\u30FB\u96C6\u8A08\u95A2\u6570\u3092\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093`, tok);
     }
     if (node.type === "ARITH" || node.type === "AGG_ARITH") {
-      this.rejectNonScalarExpr(node.left, tok);
-      this.rejectNonScalarExpr(node.right, tok);
+      this.rejectNonScalarExpr(node.left, tok, context);
+      this.rejectNonScalarExpr(node.right, tok, context);
       return;
     }
     if (node.type === "STRING_FUNC") {
-      for (const arg of node.args) this.rejectNonScalarExpr(arg, tok);
+      for (const arg of node.args) this.rejectNonScalarExpr(arg, tok, context);
     }
   }
   // ----------------------------------------------------------
@@ -33199,7 +33228,7 @@ function isDmlType(type) {
   return type === "INSERT" || type === "INSERT_SELECT" || type === "UPDATE" || type === "DELETE" || type === "UPSERT" || type === "UPSERT_SELECT" || type === "REORDER";
 }
 function isReadOnlyType(type) {
-  return type === "SELECT" || type === "UNION" || type === "WITH" || type === "EXPLAIN" || type === "SHOW_APPS" || type === "DESCRIBE" || type === "CREATE_TEMP_TABLE" || type === "DROP_TEMP_TABLE" || type === "SET_VARIABLE" || type === "ASSERT";
+  return type === "SELECT" || type === "UNION" || type === "WITH" || type === "EXPLAIN" || type === "SHOW_APPS" || type === "DESCRIBE" || type === "CREATE_TEMP_TABLE" || type === "DROP_TEMP_TABLE" || type === "SET_VARIABLE" || type === "DECLARE_VARIABLE" || type === "ASSERT";
 }
 function hasWhereClause(stmt) {
   if (!stmt || typeof stmt !== "object") return false;
@@ -33261,8 +33290,9 @@ function analyzeBatch(statements) {
   }
   if (statements.length === 1) {
     const t = statements[0].type;
-    if (t === "SET_VARIABLE") {
-      throw new BatchAnalysisError("ArgumentError: SET variable requires a batch.", 0);
+    if (t === "SET_VARIABLE" || t === "DECLARE_VARIABLE") {
+      const verb = t === "SET_VARIABLE" ? "SET" : "DECLARE";
+      throw new BatchAnalysisError(`ArgumentError: ${verb} variable requires a batch.`, 0);
     }
     if (t === "CREATE_TEMP_TABLE" || t === "DROP_TEMP_TABLE") {
       const verb = t === "CREATE_TEMP_TABLE" ? "CREATE TEMP TABLE" : "DROP TEMP TABLE";
@@ -33296,7 +33326,7 @@ function analyzeBatch(statements) {
       }
       def.referencedBy.push(index);
     }
-    if (stmt.type === "SET_VARIABLE") {
+    if (stmt.type === "SET_VARIABLE" || stmt.type === "DECLARE_VARIABLE") {
       if (variableDefs.has(stmt.name)) {
         throw new BatchAnalysisError(`ParseError: variable @${stmt.name} is already defined.`, index);
       }
@@ -33393,6 +33423,40 @@ function analyzeBatch(statements) {
   };
 }
 
+// src/core/batchVariables.ts
+var VARIABLE_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+function normalizeBatchVariableName(name) {
+  if (!VARIABLE_NAME_RE.test(name)) {
+    throw new Error(
+      `ArgumentError: invalid variable name "${name}". Use a name without @ matching [A-Za-z_][A-Za-z0-9_]{0,63}.`
+    );
+  }
+  return name.toLowerCase();
+}
+function normalizeBatchVariables(input) {
+  const normalized = /* @__PURE__ */ Object.create(null);
+  for (const [rawName, value] of Object.entries(input ?? {})) {
+    const name = normalizeBatchVariableName(rawName);
+    if (Object.prototype.hasOwnProperty.call(normalized, name)) {
+      throw new Error(`ArgumentError: variable "${rawName}" is specified more than once.`);
+    }
+    normalized[name] = value;
+  }
+  return normalized;
+}
+function validateDeclaredBatchVariables(statements, input) {
+  const normalized = normalizeBatchVariables(input);
+  const declared = new Set(
+    statements.filter((stmt) => stmt.type === "DECLARE_VARIABLE").map((stmt) => stmt.name)
+  );
+  for (const name of Object.keys(normalized)) {
+    if (!declared.has(name)) {
+      throw new Error(`ArgumentError: injected variable @${name} is not declared.`);
+    }
+  }
+  return normalized;
+}
+
 // src/core/scalarCompare.ts
 function compareScalarValues(op, leftStr, rightStr) {
   if (op === "=") return leftStr === rightStr;
@@ -35724,6 +35788,8 @@ async function executeParsedStatement(stmt, client, options, cacheContext) {
       throw new Error("ArgumentError: DROP TEMP TABLE requires a batch (temp tables are batch-scoped).");
     case "SET_VARIABLE":
       throw new Error("ArgumentError: SET variable requires a batch.");
+    case "DECLARE_VARIABLE":
+      throw new Error("ArgumentError: DECLARE variable requires a batch.");
     case "ASSERT":
       return executeAssert(stmt, client, options, cacheContext);
   }
@@ -35737,6 +35803,8 @@ var BatchTimeoutError = class extends Error {
 async function executeBatch(sql, client, options = {}) {
   const statements = parseSqlBatch(sql);
   const analysis = analyzeBatch(statements);
+  const injectedVariables = validateDeclaredBatchVariables(statements, options.variables);
+  const batchOptions = { ...options, variables: injectedVariables };
   if (options.continueOnError && analysis.containsDml) {
     throw new Error("ArgumentError: continueOnError is not allowed for batches containing DML.");
   }
@@ -35781,16 +35849,16 @@ async function executeBatch(sql, client, options = {}) {
     }
     try {
       const remaining = deadline !== null ? deadline - Date.now() : null;
-      const userConfirm = options.confirm;
+      const userConfirm = batchOptions.confirm;
       const stmtOptions = userConfirm ? {
-        ...options,
+        ...batchOptions,
         confirm: (count, operation) => userConfirm(count, operation, {
           statementIndex: i,
           statementCount: statements.length,
           statementType: info.statementType,
           targetAppId: info.targetAppId
         })
-      } : options;
+      } : batchOptions;
       const outcome = await runWithDeadline(
         executeBatchStatement(statements[i], info, countedClient, stmtOptions, cacheContext, tempTables, variables),
         remaining
@@ -35803,7 +35871,7 @@ async function executeBatch(sql, client, options = {}) {
         aborted2 = "timeout";
       } else if (e instanceof AssertError) {
         aborted2 = "assertion";
-      } else if (info.statementType === "SET_VARIABLE") {
+      } else if (info.statementType === "SET_VARIABLE" || info.statementType === "DECLARE_VARIABLE") {
         aborted2 = "fail-fast";
       } else if (!options.continueOnError) {
         aborted2 = "fail-fast";
@@ -35821,7 +35889,36 @@ async function executeBatch(sql, client, options = {}) {
 }
 async function executeBatchStatement(stmt, info, client, options, cacheContext, tempTables, variables) {
   if (stmt.type === "SET_VARIABLE") {
-    variables.set(stmt.name, evaluateScalarExpr(stmt.expr));
+    const resolvedStmt2 = resolveVariableRefs(stmt, variables);
+    if (resolvedStmt2.expr.type === "SCALAR_SUBQUERY") {
+      try {
+        const value = await evaluateScalarSubquery(
+          resolvedStmt2.expr.query,
+          client,
+          options,
+          cacheContext,
+          tempTables
+        );
+        variables.set(stmt.name, { type: "string", value });
+      } catch (e) {
+        if (e instanceof ScalarSubqueryError) {
+          throw new Error(`ArgumentError: ${e.message}`);
+        }
+        throw e;
+      }
+    } else {
+      variables.set(stmt.name, evaluateScalarExpr(resolvedStmt2.expr));
+    }
+    return {};
+  }
+  if (stmt.type === "DECLARE_VARIABLE") {
+    const injected = options.variables ?? {};
+    if (Object.prototype.hasOwnProperty.call(injected, stmt.name)) {
+      variables.set(stmt.name, { type: "string", value: injected[stmt.name] });
+    } else {
+      const value = evaluateScalarExpr(stmt.default);
+      variables.set(stmt.name, { type: "string", value: String(value.value) });
+    }
     return {};
   }
   const resolvedStmt = resolveVariableRefs(stmt, variables);
@@ -35984,6 +36081,12 @@ var AssertError = class extends Error {
     this.name = "AssertError";
   }
 };
+var ScalarSubqueryError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ScalarSubqueryError";
+  }
+};
 async function executeAssert(stmt, client, options, cacheContext, tempTables) {
   const left = await evalAssertOperand(stmt.left, client, options, cacheContext, tempTables);
   if (stmt.op === "BETWEEN") {
@@ -36017,25 +36120,38 @@ async function evalAssertOperand(operand, client, options, cacheContext, tempTab
     case "ARITH":
       return String(evalAssertArith(operand));
     case "SCALAR_SUBQUERY": {
-      const { query, probed } = withScalarProbeLimit(operand.query);
-      const result = await runSubquery(query, client, options, cacheContext, tempTables);
-      if (result.columns.length > 1) {
-        throw new AssertError(
-          `scalar subquery returned ${result.columns.length} columns (expected 1 column).`
+      try {
+        return await evaluateScalarSubquery(
+          operand.query,
+          client,
+          options,
+          cacheContext,
+          tempTables
         );
+      } catch (e) {
+        if (e instanceof ScalarSubqueryError) throw new AssertError(e.message);
+        throw e;
       }
-      if (result.rowCount === 0) {
-        throw new AssertError("scalar subquery returned no rows (expected 1 row).");
-      }
-      if (result.rowCount > 1) {
-        const rows = probed && result.rowCount === 2 ? "2 or more rows" : `${result.rowCount} rows`;
-        throw new AssertError(`scalar subquery returned ${rows} (expected 1 row).`);
-      }
-      const col = result.columns[0] ?? "";
-      return result.rows[0]?.[col] ?? "";
     }
   }
 }
+async function evaluateScalarSubquery(sourceQuery, client, options, cacheContext, tempTables) {
+  const { query, probed } = withScalarProbeLimit(sourceQuery);
+  const result = await runSubquery(query, client, options, cacheContext, tempTables);
+  if (result.columns.length !== 1) {
+    throw new ScalarSubqueryError(
+      `scalar subquery returned ${result.columns.length} columns (expected 1 column).`
+    );
+  }
+  if (result.rowCount === 0) {
+    throw new ScalarSubqueryError("scalar subquery returned no rows (expected 1 row).");
+  }
+  if (result.rowCount > 1) {
+    const rows = probed && result.rowCount === 2 ? "2 or more rows" : `${result.rowCount} rows`;
+    throw new ScalarSubqueryError(`scalar subquery returned ${rows} (expected 1 row).`);
+  }
+  return result.rows[0]?.[result.columns[0]] ?? "";
+}
 function withScalarProbeLimit(query) {
   const hasAgg = query.groupBy.length > 0 || query.columns.some((c) => c.type === "AGGREGATE" || c.type === "ARITH_AGG_COL");
   if (hasAgg || query.distinct || query.limit !== null) return { query, probed: false };
@@ -37530,20 +37646,21 @@ async function resolveScalarColumns(columns, client, options, cacheContext, cteC
   pending.forEach(([i], idx) => cache.set(i, values[idx]));
   return cache;
 }
-function buildBatchExplainPlans(sql) {
+function buildBatchExplainPlans(sql, injectedVariables) {
   const statements = parseSqlBatch(sql);
   const analysis = analyzeBatch(statements);
+  validateDeclaredBatchVariables(statements, injectedVariables);
   const variables = /* @__PURE__ */ new Map();
   return {
     statementCount: statements.length,
     statements: statements.map((stmt, i) => {
-      const planStmt = stmt.type === "SET_VARIABLE" ? stmt : resolveVariableRefs(stmt, variables);
+      const planStmt = stmt.type === "SET_VARIABLE" ? stmt.expr.type === "SCALAR_SUBQUERY" ? { ...stmt, expr: resolveVariableRefs(stmt.expr, variables) } : stmt : resolveVariableRefs(stmt, variables);
       const result = {
         index: i,
         type: analysis.statements[i].statementType,
         plan: buildBatchStatementPlan(planStmt, analysis.statements[i])
       };
-      if (stmt.type === "SET_VARIABLE") {
+      if (stmt.type === "SET_VARIABLE" || stmt.type === "DECLARE_VARIABLE") {
         variables.set(stmt.name, { type: "string", value: `@${stmt.name}` });
       }
       return result;
@@ -37566,11 +37683,26 @@ function buildBatchStatementPlan(stmt, info) {
     ];
   }
   if (stmt.type === "SET_VARIABLE") {
+    if (stmt.expr.type === "SCALAR_SUBQUERY") {
+      const subInfo = hasTempTableRef(stmt.expr.query) ? info : { ...info, tempTablesReferenced: [] };
+      return [
+        `SET @${stmt.name} = (SELECT ...)`,
+        "  value:         \u30B5\u30D6\u30AF\u30A8\u30EA\u3092\u5B9F\u884C\u6642\u306B1\u56DE\u8A55\u4FA1\uFF081\u884C1\u5217\u30FB\u30D0\u30C3\u30C1\u5185\u5B9A\u6570\u30FB\u7D50\u679C\u30E1\u30BF\u30C7\u30FC\u30BF\u306B\u306F\u975E\u516C\u958B\uFF09",
+        "  subquery:",
+        ...buildPlanForBatchQuery(stmt.expr.query, subInfo).map((l) => `  ${l}`)
+      ];
+    }
     return [
       `SET @${stmt.name} = <scalar expression>`,
       "  value:         \u5B9F\u884C\u6642\u306B1\u56DE\u8A55\u4FA1\uFF08\u30D0\u30C3\u30C1\u5185\u5B9A\u6570\u30FB\u7D50\u679C\u30E1\u30BF\u30C7\u30FC\u30BF\u306B\u306F\u975E\u516C\u958B\uFF09"
     ];
   }
+  if (stmt.type === "DECLARE_VARIABLE") {
+    return [
+      `DECLARE @${stmt.name} = <default scalar expression>`,
+      "  value:         \u5916\u90E8\u6CE8\u5165\u304C\u3042\u308C\u3070\u63A1\u7528\u3001\u306A\u3051\u308C\u3070\u65E2\u5B9A\u5024\u3092\u5B9F\u884C\u6642\u306B1\u56DE\u8A55\u4FA1\uFF08\u5024\u306F\u975E\u516C\u958B\uFF09"
+    ];
+  }
   if (stmt.type === "SHOW_APPS") return ["SHOW APPS\uFF08\u30A2\u30D7\u30EA\u4E00\u89A7\u306E\u53D6\u5F97\uFF09"];
   if (stmt.type === "DESCRIBE") return [`DESCRIBE APP${stmt.appId}\uFF08\u30D5\u30A3\u30FC\u30EB\u30C9\u5B9A\u7FA9\u306E\u53D6\u5F97\uFF09`];
   if (stmt.type === "EXPLAIN") return buildPlanForBatchQuery(stmt.query, info);
@@ -39549,6 +39681,9 @@ function createKsqlMcpTools(serverOptions, deps = {}) {
   }
   async function query(input, validated) {
     const validation = validated ?? await validate(input);
+    if (!validation.batch && input.variables && Object.keys(input.variables).length > 0) {
+      throw new Error("ArgumentError: variables require a batch containing DECLARE.");
+    }
     if (validation.batch) {
       if (validation.containsDml) {
         throw new Error("ArgumentError: batch contains DML statements. Use ksql_mutate.");
@@ -39575,7 +39710,8 @@ function createKsqlMcpTools(serverOptions, deps = {}) {
         // バッチでは timeout を合計タイムアウトとして扱う（仕様 §5.7）。
         // runtime.timeout は env / profile / 既定 30000ms を解決済みの値で、
         // HTTP クライアント側の per-request タイムアウトと同値になる
-        timeoutMs: runtime2.timeout
+        timeoutMs: runtime2.timeout,
+        variables: input.variables
       });
       return { ...buildBatchEnvelope(batchResult, { maxTotalRecords: input.maxTotalRecords }) };
     }
@@ -39664,6 +39800,7 @@ function createKsqlMcpTools(serverOptions, deps = {}) {
       tempTableMaxRows: runtime.tempTableMaxRows,
       // 合計タイムアウト（解決済みの runtime.timeout。per-request と同値）
       timeoutMs: runtime.timeout,
+      variables: input.variables,
       confirm: async (count, operation) => {
         if (count > dmlMaxRows) {
           throw new Error(`ArgumentError: ${operation} affected rows (${count}) exceed dmlMaxRows (${dmlMaxRows}).`);
@@ -39692,6 +39829,9 @@ function createKsqlMcpTools(serverOptions, deps = {}) {
   async function mutate(input, validated) {
     const dmlMaxRows = requireDmlApproval(input, "ksql_mutate");
     const validation = validated ?? await validate(input);
+    if (!validation.batch && input.variables && Object.keys(input.variables).length > 0) {
+      throw new Error("ArgumentError: variables require a batch containing DECLARE.");
+    }
     if (validation.batch) {
       return mutateBatch(input, validation, dmlMaxRows);
     }
@@ -39914,7 +40054,8 @@ var queryInputSchema = external_exports.object({
   tempTableMaxRows,
   timeout,
   continueOnError: external_exports.boolean().describe("Batch (multi-statement) only: keep executing subsequent statements after a runtime error (default false = fail-fast).").optional(),
-  maxTotalRecords: external_exports.number().int().positive().describe("Batch (multi-statement) only: cap on total rows returned across all result sets (default: unlimited).").optional()
+  maxTotalRecords: external_exports.number().int().positive().describe("Batch (multi-statement) only: cap on total rows returned across all result sets (default: unlimited).").optional(),
+  variables: external_exports.record(external_exports.string(), external_exports.string()).describe("Batch only: string values for variables declared with DECLARE. Keys omit @ and are case-insensitive.").optional()
 });
 var mutateInputSchema = external_exports.object({
   sql: external_exports.string().min(1).describe("DML kSQL text. May contain multiple ;-separated statements (batch) with temp tables, e.g. CREATE TEMP TABLE #t AS SELECT ...; INSERT INTO APPx (...) SELECT ... FROM #t;"),
@@ -39925,7 +40066,8 @@ var mutateInputSchema = external_exports.object({
   fetchParallel,
   tempTableMaxRows,
   timeout,
-  dmlTotalMaxRows: external_exports.number().int().positive().describe("Batch (multi-statement) only: cap on total affected rows across the whole batch (default: per-statement dmlMaxRows only). DML batches always run fail-fast.").optional()
+  dmlTotalMaxRows: external_exports.number().int().positive().describe("Batch (multi-statement) only: cap on total affected rows across the whole batch (default: per-statement dmlMaxRows only). DML batches always run fail-fast.").optional(),
+  variables: external_exports.record(external_exports.string(), external_exports.string()).describe("Batch only: string values for variables declared with DECLARE. Keys omit @ and are case-insensitive.").optional()
 });
 var describeAppInputSchema = external_exports.object({
   app: external_exports.number().int().positive().describe("kintone app ID to describe."),
@@ -40014,7 +40156,7 @@ Options:
   -h, --help         Show help
 `);
 }
-var SERVER_VERSION = true ? "2.2.0" : "0.0.0-dev";
+var SERVER_VERSION = true ? "2.4.0" : "0.0.0-dev";
 function createServer(args) {
   const server = new McpServer({
     name: "ksql-mcp",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rex0220/kintone-sql-tools",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "kintone SQL plugin, CLI, and MCP tools (ksql)",
   "publishConfig": {
     "access": "public"