@fadhilp/stateql 0.12.0 → 0.13.0

package/README.md

@@ -216,6 +216,20 @@ Use `--params JSON` for a JSON array or named parameters. Use
 `--params-file FILE` when JSON is awkward to quote; `--params-file -` reads
 JSON from standard input.
 
+### Dialect upserts
+
+PostgreSQL `INSERT ... ON CONFLICT DO NOTHING|UPDATE` and MySQL `INSERT ... ON
+DUPLICATE KEY UPDATE` are structurally validated and recorded with statement
+type `upsert`. Finite `VALUES` and MySQL `INSERT ... SET` sources use normal
+write policy. An update-upsert fed by `SELECT` requires `--allow-unbounded`
+because its candidate row count is not statically bounded. Upserts support direct
+`exec`, `plan`/`apply`, and staged transactions; hidden additional writes are rejected.
+
+MySQL `INSERT IGNORE` remains a non-overwriting `insert`. SQLite `INSERT OR
+REPLACE` retains destructive-operation approval, while SQLite modern `ON
+CONFLICT ... DO UPDATE` and every `MERGE` form remain blocked until the parser
+can expose their complete mutation structure.
+
 ### PostgreSQL diagnostics and maintenance
 
 Run PostgreSQL plans through `query`:
@@ -231,6 +245,15 @@ mutations are rejected. Diagnostics execute inside PostgreSQL `BEGIN READ ONLY`
 and are never reused from cache. `--cache require` therefore returns
 `CACHE_MISS` without executing the diagnostic.
 
+StateQL supports PostgreSQL 14–18. Top-level `VALUES` is a bounded read and
+accepts normal PostgreSQL positional parameters. It is conservatively
+non-cacheable because expressions may be volatile. The following narrow `SHOW`
+allowlist is also available as non-cacheable diagnostics:
+`server_version`, `server_version_num`, `transaction_read_only`,
+`transaction_isolation`, and `default_transaction_isolation`. `SHOW ALL` and
+other settings remain blocked. Syntax accepted by StateQL but introduced by a
+newer PostgreSQL release may be rejected safely by an older server.
+
 `VACUUM`, `ANALYZE`, `REINDEX`, and `CLUSTER` are PostgreSQL maintenance writes:
 
 ```bash
@@ -238,6 +261,13 @@ stql exec "VACUUM (ANALYZE) public.jobs" --allow-destructive
 stql plan "REINDEX TABLE public.jobs" --allow-destructive
 ```
 
+The PostgreSQL 14–18 grammar includes parenthesized `REINDEX CONCURRENTLY`,
+PostgreSQL 16 `BUFFER_USAGE_LIMIT` for `VACUUM`/`ANALYZE`, optional
+`DATABASE`/`SYSTEM` reindex names, and PostgreSQL 18 `ONLY table *` maintenance
+targets. Memory sizes accept an integer number of kilobytes or a quoted
+`B|kB|MB|GB|TB` value. Older servers may reject newer forms after dispatch, so
+StateQL retains conservative unknown-outcome handling.
+
 They require a read-write connection and `--allow-destructive`, reject StateQL
 parameters, and run as individually tracked autocommit operations. They cannot
 be staged in a StateQL transaction. A timeout or cancellation after dispatch is
@@ -247,6 +277,55 @@ remain unsupported—use `stql transaction` commands instead. See
 [`SQL_COMMAND_ROADMAP.md`](SQL_COMMAND_ROADMAP.md) for the exact implemented
 boundary and deferred command categories.
 
+### SQLite and MySQL diagnostics and maintenance
+
+SQLite supports `EXPLAIN QUERY PLAN` for structurally read-only `SELECT`
+statements. MySQL supports `EXPLAIN SELECT` plus bare `SHOW TABLES`,
+`SHOW COLUMNS FROM table`, and `SHOW INDEX|INDEXES FROM table`. Broader
+`EXPLAIN`, `SHOW`, and write-bearing forms remain blocked.
+
+MySQL executable comments (`/*! ... */`) are rejected throughout SQL. Because
+StateQL does not assume a server `sql_mode`, quoting that could expose these
+comments under `ANSI_QUOTES` or `NO_BACKSLASH_ESCAPES` is also rejected.
+
+These diagnostics use `query`, work with read-only connections, preserve the
+original statement instead of applying StateQL's limiting SQL wrapper, and are
+never reused from cache. Materialized results still receive StateQL's row and
+byte checks.
+
+SQLite also supports bare `VACUUM`, plus `ANALYZE [target]` and
+`REINDEX [target]` with at most one unqualified or double-quoted target:
+
+```bash
+stql exec "ANALYZE jobs" --allow-destructive
+stql exec "REINDEX jobs_created_at_idx" --allow-destructive
+stql exec "VACUUM" --allow-destructive
+```
+
+These commands require a read-write connection, reject parameters, run as
+individually tracked autocommit operations, and cannot be staged. A timeout,
+cancellation, or error after dispatch is reported as `OUTCOME_UNKNOWN`.
+`VACUUM INTO`, schema-qualified targets, paths, `ATTACH`, and arbitrary `PRAGMA`
+remain blocked.
+
+MySQL supports one optionally qualified bare or backtick-quoted target for
+`ANALYZE TABLE`, `OPTIMIZE TABLE`, and `CHECK TABLE`:
+
+```bash
+stql exec "ANALYZE TABLE jobs" --allow-destructive
+stql plan "OPTIMIZE TABLE jobs" --allow-destructive
+stql query "CHECK TABLE jobs"
+```
+
+`ANALYZE` and `OPTIMIZE` are durable autocommit writes requiring a read-write
+connection and destructive approval; server-reported error rows become known
+failed operations, while timeout or cancellation after dispatch remains
+`OUTCOME_UNKNOWN`. `CHECK TABLE` is an unwrapped, non-cacheable autocommit read
+that works on read-only connections and retains normal result limits. All three
+reject StateQL parameters, options, multiple targets, and additional
+statements, and none can run during a staged transaction.
+
+
 ### Native MongoDB
 
 MongoDB commands use official Extended JSON (EJSON), so BSON values survive the

package/dist/src/adapters.d.ts

@@ -32,6 +32,7 @@ export interface Adapter {
     readonly confidence: StateConfidence;
     ping(): Promise<void>;
     read(sql: string, params: SqlParameters): Promise<ReadResult>;
+    readAutocommit?(sql: string, params: SqlParameters): Promise<ReadResult>;
     write(sql: string, params: SqlParameters, expectedRows?: 1): Promise<WriteResult>;
     writeAutocommit?(sql: string, params: SqlParameters): Promise<WriteResult>;
     writeBatch(operations: BatchWriteOperation[], isolation: string): Promise<WriteResult[]>;

package/dist/src/adapters.js

@@ -51,6 +51,7 @@ export async function createAdapter(connection, context, input) {
             throw new StateQLError("UNSUPPORTED_DRIVER", "Redis uses the native Redis adapter.");
     }
 }
+const SQLITE_AUTOCOMMIT_STATEMENTS = new Set(["vacuum", "analyze", "reindex"]);
 class SQLiteAdapter {
     source;
     readOnly;
@@ -101,7 +102,14 @@ class SQLiteAdapter {
     async write(sql, params, expectedRows) {
         return this.call("write", [sql, params, expectedRows], true, false);
     }
+    async writeAutocommit(sql, params) {
+        return this.call("writeAutocommit", [sql, params], true, false);
+    }
     async writeBatch(operations, isolation) {
+        const unsupported = operations.find((operation) => SQLITE_AUTOCOMMIT_STATEMENTS.has(operation.statement_type));
+        if (unsupported) {
+            throw new BatchWriteError(`SQLite transactions cannot include ${unsupported.statement_type.toUpperCase()} maintenance statements.`, false);
+        }
         return this.call("writeBatch", [operations, isolation], true, true);
     }
     async signature() {
@@ -590,6 +598,16 @@ class MySqlAdapter {
             throw error;
         }
     }
+    async readAutocommit(sql, params) {
+        const [result, fields] = await this.query(sql, mysqlParams(params), false, false);
+        return {
+            rows: toJsonSafe(mysqlRows(result)),
+            columns: fields.map((field) => ({
+                name: field.name,
+                type: mysqlFieldType(field),
+            })),
+        };
+    }
     async write(sql, params, expectedRows) {
         if (this.readOnly)
             throw new Error("Connection is read-only.");
@@ -629,6 +647,35 @@ class MySqlAdapter {
             throw new AdapterWriteError(errorText(error), true);
         }
     }
+    async writeAutocommit(sql, params) {
+        if (this.readOnly)
+            throw new AdapterWriteError("Connection is read-only.", false);
+        let values;
+        try {
+            values = mysqlParams(params);
+            await this.connect();
+        }
+        catch (error) {
+            if (error instanceof AdapterExecutionError)
+                throw error;
+            throw new AdapterWriteError(errorText(error), false);
+        }
+        try {
+            const [result] = await this.runQuery(sql, values, true, false);
+            const maintenanceError = mysqlMaintenanceError(result);
+            if (maintenanceError)
+                throw new AdapterWriteError(maintenanceError, false);
+            return {
+                affectedRows: Array.isArray(result) ? 0 : mysqlAffectedRows(result),
+            };
+        }
+        catch (error) {
+            if (error instanceof AdapterExecutionError || error instanceof AdapterWriteError) {
+                throw error;
+            }
+            throw new AdapterWriteError(errorText(error), true);
+        }
+    }
     async writeBatch(operations, isolation) {
         if (this.readOnly)
             throw new Error("Connection is read-only.");
@@ -901,6 +948,7 @@ const MYSQL_ISOLATION_LEVELS = new Set([
 const MYSQL_TRANSACTIONAL_STATEMENTS = new Set([
     "delete",
     "insert",
+    "upsert",
     "replace",
     "update",
 ]);
@@ -927,6 +975,18 @@ function mysqlRows(result) {
     }
     return result;
 }
+function mysqlMaintenanceError(result) {
+    if (!Array.isArray(result))
+        return undefined;
+    for (const row of result) {
+        const typeEntry = Object.entries(row).find(([key]) => key.toLowerCase() === "msg_type");
+        if (String(typeEntry?.[1] ?? "").toLowerCase() !== "error")
+            continue;
+        const textEntry = Object.entries(row).find(([key]) => key.toLowerCase() === "msg_text");
+        return String(textEntry?.[1] ?? "MySQL maintenance failed.");
+    }
+    return undefined;
+}
 function mysqlAffectedRows(result) {
     if (Array.isArray(result) || !("affectedRows" in result)) {
         throw new Error("MySQL statement did not return a write result.");

package/dist/src/sql.d.ts

@@ -1,6 +1,6 @@
 import type { AST } from "node-sql-parser";
 import type { Driver, SqlDriver } from "./types.js";
-export type StatementType = "select" | "insert" | "replace" | "update" | "delete" | "create" | "alter" | "drop" | "truncate" | "explain" | "vacuum" | "analyze" | "reindex" | "cluster";
+export type StatementType = "select" | "insert" | "upsert" | "replace" | "update" | "delete" | "create" | "alter" | "drop" | "truncate" | "values" | "show" | "explain" | "vacuum" | "analyze" | "reindex" | "optimize" | "check" | "cluster";
 export interface SqlAnalysis {
     ast: AST;
     normalized: string;
@@ -12,6 +12,8 @@ export interface SqlAnalysis {
     wrapForLimit: boolean;
     cacheable: boolean;
     requiresAutocommit: boolean;
+    /** Analysis-only SQL with trailing trivia removed when limit wrapping needs it. */
+    limitSql?: string;
 }
 export declare function analyzeSql(sql: string, driver: SqlDriver): SqlAnalysis;
 /** @internal Compatibility for existing connection records during Mongo rollout. */

package/dist/src/sql.js

@@ -26,6 +26,14 @@ export function analyzeSql(sql, driver) {
             if (postgresCommand)
                 return postgresCommand;
         }
+        else if (driver === "sqlite") {
+            const sqliteCommand = analyzeSqliteCommand(trimmed);
+            if (sqliteCommand)
+                return sqliteCommand;
+        }
+        else if (driver === "mysql") {
+            return analyzeMySqlSql(trimmed);
+        }
         return analyzeParsedSql(trimmed, driver);
     }
     catch (error) {
@@ -35,7 +43,7 @@ export function analyzeSql(sql, driver) {
         throw new StateQLError("INVALID_SQL", message);
     }
 }
-function analyzeParsedSql(sql, driver) {
+function parseSqlStatement(sql, driver) {
     const database = driver === "postgres"
         ? "Postgresql"
         : driver === "mysql"
@@ -49,14 +57,6 @@ function analyzeParsedSql(sql, driver) {
     const ast = (Array.isArray(parsed) ? parsed[0] : parsed);
     if (!ast)
         throw new StateQLError("INVALID_SQL", "SQL is empty.");
-    const rawType = String(ast.type);
-    if (!SUPPORTED_STATEMENTS.has(rawType)) {
-        throw new StateQLError("INVALID_SQL", `Unsupported SQL statement type "${rawType}".`);
-    }
-    const statementType = rawType;
-    if (statementType === "select" && selectContainsWrite(ast)) {
-        throw new StateQLError("INVALID_SQL", "Read statements cannot contain writes or SELECT INTO.");
-    }
     const normalized = parserSql === sql
         ? parser
             .sqlify(ast, { database })
@@ -66,6 +66,24 @@ function analyzeParsedSql(sql, driver) {
         // Keep the exact ordering modifiers in cache and idempotency fingerprints.
         // The parser copy is analysis-only; adapters execute the original SQL.
         : sql.replace(/;\s*$/, "");
+    return { ast, normalized };
+}
+function analyzeParsedSql(sql, driver) {
+    return analyzeParsedStatement(parseSqlStatement(sql, driver), driver);
+}
+function analyzeParsedStatement({ ast, normalized }, driver) {
+    const rawType = String(ast.type);
+    if (!SUPPORTED_STATEMENTS.has(rawType)) {
+        throw new StateQLError("INVALID_SQL", `Unsupported SQL statement type "${rawType}".`);
+    }
+    const rawStatementType = rawType;
+    const insert = rawStatementType === "insert"
+        ? analyzeInsert(ast, driver)
+        : undefined;
+    const statementType = insert?.statementType ?? rawStatementType;
+    if (statementType === "select" && containsUnexpectedWrite(ast)) {
+        throw new StateQLError("INVALID_SQL", "Read statements cannot contain writes or SELECT INTO.");
+    }
     const details = ast;
     const read = statementType === "select";
     const mutation = statementType === "update" ||
@@ -83,7 +101,8 @@ function analyzeParsedSql(sql, driver) {
         normalized,
         statementType,
         read,
-        unboundedMutation: statementType === "truncate" || (mutation && !details.where),
+        unboundedMutation: insert?.unboundedMutation ??
+            (statementType === "truncate" || (mutation && !details.where)),
         destructive,
         ordered: read && Boolean(details.orderby),
         wrapForLimit: read,
@@ -91,11 +110,76 @@ function analyzeParsedSql(sql, driver) {
         requiresAutocommit: false,
     };
 }
+function analyzeInsert(ast, driver) {
+    const details = ast;
+    const conflict = record(details.conflict);
+    const duplicate = record(details.on_duplicate_update);
+    const allowedWrites = new Set([ast]);
+    let upsert = false;
+    let updatesOnConflict = false;
+    if (conflict) {
+        if (driver !== "postgres")
+            invalidUpsertSyntax(driver);
+        const action = record(conflict.action);
+        const expression = record(action?.expr);
+        if (conflict.type !== "conflict" ||
+            conflict.keyword !== "on" ||
+            action?.keyword !== "do" ||
+            !expression) {
+            invalidUpsertSyntax(driver);
+        }
+        upsert = true;
+        if (expression.type === "update") {
+            if (!Array.isArray(expression.set) || expression.set.length === 0) {
+                invalidUpsertSyntax(driver);
+            }
+            allowedWrites.add(expression);
+            updatesOnConflict = true;
+        }
+        else if (expression.type !== "origin" ||
+            String(expression.value).toLowerCase() !== "nothing") {
+            invalidUpsertSyntax(driver);
+        }
+    }
+    if (duplicate) {
+        if (driver !== "mysql" ||
+            duplicate.keyword !== "on duplicate key update" ||
+            !Array.isArray(duplicate.set) ||
+            duplicate.set.length === 0) {
+            invalidUpsertSyntax(driver);
+        }
+        upsert = true;
+        updatesOnConflict = true;
+    }
+    if (containsUnexpectedWrite(ast, allowedWrites)) {
+        throw new StateQLError("INVALID_SQL", "INSERT statements cannot contain additional write statements or SELECT INTO.");
+    }
+    const source = record(details.values);
+    const assignmentSource = driver === "mysql" && !source &&
+        Array.isArray(details.set) && details.set.length > 0;
+    if (upsert && !assignmentSource &&
+        (!source || !["select", "values"].includes(String(source.type)))) {
+        invalidUpsertSyntax(driver);
+    }
+    return {
+        statementType: upsert ? "upsert" : "insert",
+        unboundedMutation: updatesOnConflict && source?.type === "select",
+    };
+}
+function invalidUpsertSyntax(driver) {
+    throw new StateQLError("INVALID_SQL", `Unsupported or invalid ${driver} upsert syntax.`);
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
 const EXPLAIN_INNER_STATEMENTS = new Set([
     "select",
     "insert",
     "update",
     "delete",
+    "upsert",
 ]);
 const EXPLAIN_BOOLEAN_OPTIONS = new Set([
     "ANALYZE",
@@ -111,15 +195,26 @@ const EXPLAIN_BOOLEAN_OPTIONS = new Set([
 ]);
 const EXPLAIN_FORMATS = new Set(["TEXT", "XML", "JSON", "YAML"]);
 const EXPLAIN_SERIALIZE = new Set(["NONE", "TEXT", "BINARY"]);
-const BOOLEAN_VALUES = new Set(["TRUE", "FALSE", "ON", "OFF"]);
+const BOOLEAN_VALUES = new Set(["TRUE", "FALSE", "ON", "OFF", "1", "0"]);
+const POSTGRES_SHOW_SETTINGS = new Set([
+    "default_transaction_isolation",
+    "server_version",
+    "server_version_num",
+    "transaction_isolation",
+    "transaction_read_only",
+]);
 function analyzePostgresCommand(sql) {
-    const scanner = new PostgresPrefixScanner(sql);
+    const scanner = new SqlPrefixScanner(sql, "postgres");
     const command = scanner.readWord();
     if (!command)
         return undefined;
     switch (command.value) {
         case "EXPLAIN":
             return analyzePostgresExplain(sql, scanner);
+        case "SHOW":
+            return analyzePostgresShow(sql);
+        case "VALUES":
+            return analyzePostgresValues(sql);
         case "VACUUM":
         case "ANALYZE":
         case "REINDEX":
@@ -129,6 +224,179 @@ function analyzePostgresCommand(sql) {
             return undefined;
     }
 }
+function analyzePostgresShow(sql) {
+    const parsed = parseSqlStatement(sql, "postgres");
+    const details = parsed.ast;
+    const variable = details.var;
+    if (details.type !== "show" ||
+        details.keyword !== "var" ||
+        variable?.type !== "var" ||
+        typeof variable.name !== "string" ||
+        (Array.isArray(variable.members) && variable.members.length > 0) ||
+        !POSTGRES_SHOW_SETTINGS.has(variable.name.toLowerCase())) {
+        invalidPostgresSyntax("SHOW");
+    }
+    return readDiagnostic(parsed, "show");
+}
+function analyzePostgresValues(sql) {
+    const statement = postgresStatementBody(sql);
+    const wrapped = analyzeParsedSql(`SELECT * FROM (${statement}) AS _stateql_values`, "postgres");
+    return {
+        ...wrapped,
+        normalized: statement,
+        statementType: "values",
+        ordered: false,
+        cacheable: false,
+        limitSql: statement,
+    };
+}
+const MYSQL_SHOW_KEYWORDS = new Set(["columns", "index", "indexes", "tables"]);
+function analyzeMySqlSql(sql) {
+    const scanner = new MySqlPrefixScanner(sql);
+    scanner.validateComments();
+    const command = scanner.readWord();
+    if (command?.value === "ANALYZE" ||
+        command?.value === "OPTIMIZE" ||
+        command?.value === "CHECK") {
+        return analyzeMySqlMaintenance(sql, scanner, command.value);
+    }
+    const parsed = parseSqlStatement(sql, "mysql");
+    const details = parsed.ast;
+    if (details.type === "explain") {
+        const inner = details.expr;
+        if (!inner || String(inner.type) !== "select" || containsUnexpectedWrite(inner)) {
+            throw new StateQLError("INVALID_SQL", "MySQL EXPLAIN accepts read-only SELECT statements only.");
+        }
+        return readDiagnostic(parsed, "explain");
+    }
+    if (details.type === "show") {
+        const keyword = typeof details.keyword === "string"
+            ? details.keyword.toLowerCase()
+            : "";
+        const allowedKeys = keyword === "tables"
+            ? new Set(["type", "keyword"])
+            : new Set(["type", "keyword", "from"]);
+        const hasUnexpectedShape = Object.entries(details).some(([key, value]) => value !== undefined && value !== null && !allowedKeys.has(key));
+        const from = details.from;
+        if (!MYSQL_SHOW_KEYWORDS.has(keyword) ||
+            hasUnexpectedShape ||
+            (keyword !== "tables" && (!Array.isArray(from) || from.length !== 1))) {
+            throw new StateQLError("INVALID_SQL", `Unsupported MySQL SHOW form "${keyword || "unknown"}".`);
+        }
+        return readDiagnostic(parsed, "show");
+    }
+    return analyzeParsedStatement(parsed, "mysql");
+}
+function analyzeMySqlMaintenance(sql, scanner, command) {
+    if (scanner.readWord()?.value !== "TABLE")
+        invalidMySqlSyntax(command);
+    if (!scanner.readQualifiedIdentifier())
+        invalidMySqlSyntax(command);
+    if (scanner.consume(";")) {
+        if (scanner.triviaEnd() !== sql.length)
+            invalidMySqlSyntax(command);
+    }
+    else if (scanner.triviaEnd() !== sql.length) {
+        invalidMySqlSyntax(command);
+    }
+    const read = command === "CHECK";
+    return {
+        ast: { type: command.toLowerCase() },
+        normalized: sql.replace(/;\s*$/, ""),
+        statementType: command.toLowerCase(),
+        read,
+        unboundedMutation: false,
+        destructive: !read,
+        ordered: false,
+        wrapForLimit: false,
+        cacheable: false,
+        requiresAutocommit: true,
+    };
+}
+function invalidMySqlSyntax(command) {
+    throw new StateQLError("INVALID_SQL", `Unsupported or invalid MySQL ${command} TABLE syntax.`);
+}
+function analyzeSqliteCommand(sql) {
+    const scanner = new SqlPrefixScanner(sql, "sqlite");
+    const command = scanner.readWord();
+    switch (command?.value) {
+        case "EXPLAIN":
+            return analyzeSqliteExplain(sql, scanner);
+        case "VACUUM":
+        case "ANALYZE":
+        case "REINDEX":
+            return analyzeSqliteMaintenance(sql, scanner, command.value);
+        default:
+            return undefined;
+    }
+}
+function analyzeSqliteExplain(sql, scanner) {
+    if (scanner.readWord()?.value !== "QUERY" || scanner.readWord()?.value !== "PLAN") {
+        throw new StateQLError("INVALID_SQL", "Only SQLite EXPLAIN QUERY PLAN is supported.");
+    }
+    const innerSql = sql.slice(scanner.triviaEnd());
+    if (!innerSql) {
+        throw new StateQLError("INVALID_SQL", "Invalid SQLite EXPLAIN QUERY PLAN syntax.");
+    }
+    const inner = analyzeParsedSql(innerSql, "sqlite");
+    if (inner.statementType !== "select") {
+        throw new StateQLError("INVALID_SQL", "SQLite EXPLAIN QUERY PLAN accepts read-only SELECT statements only.");
+    }
+    return readDiagnostic({ ast: inner.ast, normalized: sql.replace(/;\s*$/, "") }, "explain");
+}
+function analyzeSqliteMaintenance(sql, scanner, command) {
+    if (command !== "VACUUM" && scanner.peek() !== ";" && scanner.peek() !== undefined) {
+        if (!readSqliteIdentifier(sql, scanner))
+            invalidSqliteSyntax(command);
+    }
+    if (scanner.consume(";")) {
+        if (scanner.triviaEnd() !== sql.length)
+            invalidSqliteSyntax(command);
+    }
+    else if (scanner.triviaEnd() !== sql.length) {
+        invalidSqliteSyntax(command);
+    }
+    return {
+        ast: { type: command.toLowerCase() },
+        normalized: sql.replace(/;\s*$/, ""),
+        statementType: command.toLowerCase(),
+        read: false,
+        unboundedMutation: false,
+        destructive: true,
+        ordered: false,
+        wrapForLimit: false,
+        cacheable: false,
+        requiresAutocommit: true,
+    };
+}
+function readSqliteIdentifier(sql, scanner) {
+    scanner.triviaEnd();
+    if (sql[scanner.position] === '"') {
+        const end = postgresQuotedIdentifierEnd(sql, scanner.position);
+        if (end === undefined)
+            return false;
+        scanner.position = end;
+        return true;
+    }
+    return Boolean(scanner.readWord(false));
+}
+function invalidSqliteSyntax(command) {
+    throw new StateQLError("INVALID_SQL", `Unsupported or invalid SQLite ${command} syntax.`);
+}
+function readDiagnostic({ ast, normalized }, statementType) {
+    return {
+        ast,
+        normalized,
+        statementType,
+        read: true,
+        unboundedMutation: false,
+        destructive: false,
+        ordered: false,
+        wrapForLimit: false,
+        cacheable: false,
+        requiresAutocommit: false,
+    };
+}
 function analyzePostgresExplain(sql, scanner) {
     let analyze = false;
     const seen = new Set();
@@ -217,12 +485,15 @@ const VACUUM_OPTIONS = new Map([
     ["PARALLEL", "number"],
     ["SKIP_DATABASE_STATS", "boolean"],
     ["ONLY_DATABASE_STATS", "boolean"],
+    ["BUFFER_USAGE_LIMIT", "size"],
 ]);
 const ANALYZE_OPTIONS = new Map([
     ["VERBOSE", "boolean"],
     ["SKIP_LOCKED", "boolean"],
+    ["BUFFER_USAGE_LIMIT", "size"],
 ]);
 const REINDEX_OPTIONS = new Map([
+    ["CONCURRENTLY", "boolean"],
     ["VERBOSE", "boolean"],
     ["TABLESPACE", "identifier"],
 ]);
@@ -235,14 +506,14 @@ function analyzePostgresMaintenance(sql, command) {
     switch (command) {
         case "VACUUM":
             parser.options(VACUUM_OPTIONS, ["FULL", "FREEZE", "VERBOSE", "ANALYZE"]);
-            parser.optionalTargets();
+            parser.optionalTargets(true);
             break;
         case "ANALYZE":
             parser.options(ANALYZE_OPTIONS, ["VERBOSE"]);
-            parser.optionalTargets();
+            parser.optionalTargets(true);
             break;
         case "REINDEX": {
-            parser.options(REINDEX_OPTIONS);
+            const options = parser.options(REINDEX_OPTIONS);
             const target = parser.expectOneOf([
                 "INDEX",
                 "TABLE",
@@ -250,12 +521,17 @@ function analyzePostgresMaintenance(sql, command) {
                 "DATABASE",
                 "SYSTEM",
             ]);
-            if (target !== "SYSTEM")
-                parser.consumeWord("CONCURRENTLY");
+            const postTargetConcurrent = parser.consumeWord("CONCURRENTLY");
+            if (postTargetConcurrent && options.has("CONCURRENTLY")) {
+                invalidPostgresSyntax(command);
+            }
             if (target === "INDEX" || target === "TABLE") {
                 parser.qualifiedIdentifier();
             }
-            else {
+            else if (target === "SCHEMA") {
+                parser.identifier();
+            }
+            else if (!parser.done()) {
                 parser.identifier();
             }
             break;
@@ -284,7 +560,7 @@ function analyzePostgresMaintenance(sql, command) {
     };
 }
 function tokenizePostgresMaintenance(sql) {
-    const scanner = new PostgresPrefixScanner(sql);
+    const scanner = new SqlPrefixScanner(sql, "postgres");
     const tokens = [];
     while (scanner.triviaEnd() < sql.length) {
         const character = sql[scanner.position];
@@ -308,6 +584,15 @@ function tokenizePostgresMaintenance(sql) {
             scanner.position = end;
             continue;
         }
+        if (character === "'") {
+            const end = postgresQuotedStringScanEnd(sql, scanner.position);
+            if (end <= scanner.position + 1 || sql[end - 1] !== "'") {
+                invalidPostgresSyntax("maintenance");
+            }
+            tokens.push({ kind: "string", value: sql.slice(scanner.position, end) });
+            scanner.position = end;
+            continue;
+        }
         if (/[0-9]/u.test(character)) {
             const start = scanner.position;
             scanner.position += 1;
@@ -316,7 +601,7 @@ function tokenizePostgresMaintenance(sql) {
             tokens.push({ kind: "number", value: sql.slice(start, scanner.position) });
             continue;
         }
-        if (["(", ")", ",", "."].includes(character)) {
+        if (["(", ")", ",", ".", "*"].includes(character)) {
             tokens.push({ kind: "punctuation", value: character });
             scanner.position += 1;
             continue;
@@ -396,11 +681,15 @@ class UtilityParser {
             this.index += 1;
         }
     }
-    optionalTargets() {
+    optionalTargets(allowOnlyAndStar = false) {
         if (this.done())
             return;
         while (true) {
+            if (allowOnlyAndStar)
+                this.consumeWord("ONLY");
             this.qualifiedIdentifier();
+            if (allowOnlyAndStar)
+                this.consumePunctuation("*");
             if (this.consumePunctuation("(")) {
                 this.identifier();
                 while (this.consumePunctuation(","))
@@ -429,7 +718,8 @@ class UtilityParser {
         if (!token)
             invalidPostgresSyntax(this.command);
         if (kind === "boolean") {
-            if (token.kind !== "word" || !BOOLEAN_VALUES.has(token.value)) {
+            if ((token.kind !== "word" && token.kind !== "number") ||
+                !BOOLEAN_VALUES.has(token.value)) {
                 invalidPostgresSyntax(this.command);
             }
         }
@@ -442,6 +732,10 @@ class UtilityParser {
                 invalidPostgresSyntax(this.command);
             }
         }
+        else if (kind === "size") {
+            if (!validMaintenanceSize(token))
+                invalidPostgresSyntax(this.command);
+        }
         else if (token.kind !== "word" || !kind.has(token.value)) {
             invalidPostgresSyntax(this.command);
         }
@@ -455,12 +749,151 @@ class UtilityParser {
         return true;
     }
 }
-class PostgresPrefixScanner {
+function validMaintenanceSize(token) {
+    let amountText;
+    let unit;
+    if (token.kind === "number") {
+        amountText = token.value;
+        unit = "KB";
+    }
+    else if (token.kind === "string") {
+        const match = token.value.match(/^'([0-9]+)(?:\s*(B|KB|MB|GB|TB))?'$/iu);
+        if (!match)
+            return false;
+        amountText = match[1];
+        unit = (match[2]?.toUpperCase() ?? "KB");
+    }
+    else {
+        return false;
+    }
+    const factors = {
+        B: 1n,
+        KB: 1024n,
+        MB: 1024n ** 2n,
+        GB: 1024n ** 3n,
+        TB: 1024n ** 4n,
+    };
+    const bytes = BigInt(amountText) * factors[unit];
+    return bytes === 0n ||
+        (bytes >= 128n * factors.KB && bytes <= 16n * factors.GB);
+}
+class MySqlPrefixScanner {
     sql;
     position = 0;
     constructor(sql) {
         this.sql = sql;
     }
+    validateComments() {
+        if (!this.sql.includes("/*!"))
+            return;
+        // sql_mode is unknown: cover string escapes, ANSI_QUOTES, and
+        // NO_BACKSLASH_ESCAPES. Reject mode-dependent executable comments.
+        for (const [singleEscapes, doubleEscapes] of [
+            [true, true], [true, false], [false, false],
+        ]) {
+            this.position = 0;
+            while (this.triviaEnd() < this.sql.length) {
+                const quote = this.sql[this.position];
+                if (quote === "'" || quote === '"' || quote === "`") {
+                    const escaped = quote === "'" ? singleEscapes : quote === '"' && doubleEscapes;
+                    if (!this.readQuoted(quote, escaped)) {
+                        throw new StateQLError("INVALID_SQL", "Unterminated quoted SQL value.");
+                    }
+                }
+                else {
+                    this.position += 1;
+                }
+            }
+        }
+        this.position = 0;
+    }
+    triviaEnd() {
+        while (this.position < this.sql.length) {
+            if (/\s/u.test(this.sql[this.position])) {
+                this.position += 1;
+            }
+            else if (this.sql[this.position] === "#") {
+                this.position = lineCommentEnd(this.sql, this.position + 1);
+            }
+            else if (this.sql.startsWith("--", this.position) &&
+                (this.sql[this.position + 2] === undefined || /[\x00-\x20]/u.test(this.sql[this.position + 2]))) {
+                this.position = lineCommentEnd(this.sql, this.position + 2);
+            }
+            else if (this.sql.startsWith("/*", this.position)) {
+                if (this.sql[this.position + 2] === "!") {
+                    throw new StateQLError("INVALID_SQL", "MySQL executable comments are not supported.");
+                }
+                const end = nonNestedBlockCommentEnd(this.sql, this.position + 2);
+                if (end === undefined) {
+                    throw new StateQLError("INVALID_SQL", "Unterminated SQL comment.");
+                }
+                this.position = end;
+            }
+            else {
+                break;
+            }
+        }
+        return this.position;
+    }
+    readWord(skipTrivia = true) {
+        if (skipTrivia)
+            this.triviaEnd();
+        const start = this.position;
+        if (!identifierStart(this.sql[start]))
+            return undefined;
+        this.position += 1;
+        while (identifierPart(this.sql[this.position]))
+            this.position += 1;
+        return { value: this.sql.slice(start, this.position).toUpperCase() };
+    }
+    readQualifiedIdentifier() {
+        if (!this.readIdentifier())
+            return false;
+        if (!this.consume("."))
+            return true;
+        return this.readIdentifier();
+    }
+    consume(value) {
+        this.triviaEnd();
+        if (!this.sql.startsWith(value, this.position))
+            return false;
+        this.position += value.length;
+        return true;
+    }
+    readIdentifier() {
+        this.triviaEnd();
+        if (this.sql[this.position] !== "`")
+            return Boolean(this.readWord(false));
+        return this.readQuoted("`", false);
+    }
+    readQuoted(quote, backslashEscapes) {
+        let index = this.position + 1;
+        while (index < this.sql.length) {
+            if (backslashEscapes && this.sql[index] === "\\") {
+                index += 2;
+            }
+            else if (this.sql[index] !== quote) {
+                index += 1;
+            }
+            else if (this.sql[index + 1] === quote) {
+                index += 2;
+            }
+            else {
+                this.position = index + 1;
+                return true;
+            }
+        }
+        return false;
+    }
+}
+class SqlPrefixScanner {
+    sql;
+    dialect;
+    position = 0;
+    constructor(sql, dialect) {
+        this.sql = sql;
+        this.dialect = dialect;
+    }
     triviaEnd() {
         while (this.position < this.sql.length) {
             if (/\s/u.test(this.sql[this.position])) {
@@ -470,7 +903,9 @@ class PostgresPrefixScanner {
                 this.position = lineCommentEnd(this.sql, this.position + 2);
             }
             else if (this.sql.startsWith("/*", this.position)) {
-                const end = postgresBlockCommentEnd(this.sql, this.position + 2);
+                const end = this.dialect === "postgres"
+                    ? postgresBlockCommentEnd(this.sql, this.position + 2)
+                    : nonNestedBlockCommentEnd(this.sql, this.position + 2);
                 if (end === undefined) {
                     throw new StateQLError("INVALID_SQL", "Unterminated SQL comment.");
                 }
@@ -515,6 +950,61 @@ class PostgresPrefixScanner {
         return true;
     }
 }
+function postgresStatementBody(sql) {
+    let index = 0;
+    let lastTokenStart = 0;
+    let lastTokenEnd = 0;
+    while (index < sql.length) {
+        if (/\s/u.test(sql[index])) {
+            index += 1;
+            continue;
+        }
+        if (sql.startsWith("--", index)) {
+            index = lineCommentEnd(sql, index + 2);
+            continue;
+        }
+        if (sql.startsWith("/*", index)) {
+            const end = postgresBlockCommentEnd(sql, index + 2);
+            if (end === undefined) {
+                throw new StateQLError("INVALID_SQL", "Unterminated SQL comment.");
+            }
+            index = end;
+            continue;
+        }
+        const start = index;
+        const character = sql[index];
+        if (character === "'") {
+            index = postgresQuotedStringScanEnd(sql, index);
+        }
+        else if (character === '"') {
+            const end = postgresQuotedIdentifierEnd(sql, index);
+            if (end === undefined) {
+                throw new StateQLError("INVALID_SQL", "Unterminated quoted SQL identifier.");
+            }
+            index = end;
+        }
+        else if (character === "$") {
+            const delimiter = sql.slice(index).match(/^\$(?:[A-Za-z_][A-Za-z0-9_]*)?\$/)?.[0];
+            if (delimiter) {
+                const end = sql.indexOf(delimiter, index + delimiter.length);
+                if (end < 0) {
+                    throw new StateQLError("INVALID_SQL", "Unterminated dollar-quoted SQL value.");
+                }
+                index = end + delimiter.length;
+            }
+            else {
+                index += 1;
+            }
+        }
+        else {
+            index += 1;
+        }
+        lastTokenStart = start;
+        lastTokenEnd = index;
+    }
+    const end = sql[lastTokenStart] === ";" ? lastTokenStart : lastTokenEnd;
+    return sql.slice(0, end).trim();
+}
 function invalidPostgresSyntax(command) {
     throw new StateQLError("INVALID_SQL", `Unsupported or invalid PostgreSQL ${command} syntax.`);
 }
@@ -551,6 +1041,10 @@ function postgresQuotedStringScanEnd(sql, start) {
     }
     return index;
 }
+function nonNestedBlockCommentEnd(sql, start) {
+    const end = sql.indexOf("*/", start);
+    return end < 0 ? undefined : end + 2;
+}
 function postgresBlockCommentEnd(sql, start) {
     let depth = 1;
     let index = start;
@@ -714,7 +1208,7 @@ function identifierStart(value) {
 function identifierPart(value) {
     return value !== undefined && /[A-Za-z0-9_$\u0080-\uFFFF]/u.test(value);
 }
-function selectContainsWrite(ast) {
+function containsUnexpectedWrite(ast, allowedWrites = new Set()) {
     const visited = new Set();
     const writeTypes = new Set([
         "insert",
@@ -736,7 +1230,7 @@ function selectContainsWrite(ast) {
             return value.some(visit);
         const details = value;
         const type = typeof details.type === "string" ? details.type : undefined;
-        if (type && writeTypes.has(type))
+        if (type && writeTypes.has(type) && !allowedWrites.has(value))
             return true;
         if (type === "select") {
             const into = details.into;

package/dist/src/sqlite-process.js

@@ -83,6 +83,22 @@ function execute(request) {
                 }
             }
         }
+        case "writeAutocommit": {
+            if (readOnly)
+                throw new SQLiteBatchError("Connection is read-only.", false);
+            const [sql, params] = request.args;
+            if ((Array.isArray(params) && params.length > 0) ||
+                (!Array.isArray(params) && Object.keys(params).length > 0)) {
+                throw new SQLiteBatchError("SQLite maintenance statements do not accept parameters.", false);
+            }
+            try {
+                database.exec(sql);
+                return { affectedRows: 0 };
+            }
+            catch (error) {
+                throw new SQLiteBatchError(errorText(error), true);
+            }
+        }
         case "writeBatch": {
             if (readOnly)
                 throw new Error("Connection is read-only.");

package/dist/src/stateql.js

@@ -680,6 +680,9 @@ export class StateQL {
                 });
             }
             const parameters = options.params ?? [];
+            if (analysis.requiresAutocommit && sqlParametersLength(parameters) > 0) {
+                throw new StateQLError("INVALID_SQL", "Autocommit diagnostic statements do not accept StateQL parameters.");
+            }
             const context = this.executionContext(options);
             const adapterSource = await this.resolveConnectionSource(connection, session, "query", "read", context);
             const adapter = await this.openAdapter(connection, context, adapterSource);
@@ -716,9 +719,15 @@ export class StateQL {
                         suggestedAction: "Run with --cache auto or --cache bypass.",
                     });
                 }
-                const result = await adapter.read(analysis.wrapForLimit
-                    ? boundedReadSql(sql, this.maxResultRows + 1)
-                    : sql, parameters);
+                const executionSql = analysis.wrapForLimit
+                    ? boundedReadSql(analysis.limitSql ?? sql, this.maxResultRows + 1)
+                    : sql;
+                if (analysis.requiresAutocommit && !adapter.readAutocommit) {
+                    throw new StateQLError("UNSUPPORTED_DRIVER", `${analysis.statementType.toUpperCase()} requires adapter autocommit reads.`);
+                }
+                const result = analysis.requiresAutocommit
+                    ? await adapter.readAutocommit(executionSql, parameters)
+                    : await adapter.read(executionSql, parameters);
                 if (result.rows.length > this.maxResultRows) {
                     throw new StateQLError("OUTPUT_LIMIT_EXCEEDED", `Query exceeds the ${this.maxResultRows}-row materialization limit.`, { suggestedAction: "Add a narrower WHERE clause or LIMIT." });
                 }
@@ -2211,7 +2220,7 @@ export class StateQL {
         const parameters = options.params ?? [];
         if (analysis.requiresAutocommit &&
             (options.expectedRows !== undefined || sqlParametersLength(parameters) > 0)) {
-            throw new StateQLError("INVALID_SQL", "PostgreSQL maintenance statements do not accept StateQL parameters or row-count preconditions.");
+            throw new StateQLError("INVALID_SQL", "Autocommit maintenance statements do not accept StateQL parameters or row-count preconditions.");
         }
         const transactionId = session.active_transaction_id ?? undefined;
         if (analysis.requiresAutocommit && transactionId) {
@@ -2322,7 +2331,7 @@ export class StateQL {
         }
         try {
             if (analysis.requiresAutocommit && !adapter.writeAutocommit) {
-                throw new AdapterWriteError(`${analysis.statementType.toUpperCase()} requires PostgreSQL autocommit execution.`, false);
+                throw new AdapterWriteError(`${analysis.statementType.toUpperCase()} requires adapter autocommit execution.`, false);
             }
             const write = analysis.requiresAutocommit
                 ? await adapter.writeAutocommit(sql, parameters)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fadhilp/stateql",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Stateful, agent-oriented database CLI for safe result reuse",
   "repository": {
     "type": "git",