@fadhilp/stateql 0.11.1 → 0.13.0

package/README.md

@@ -216,6 +216,116 @@ 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`:
+
+```bash
+stql query "EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) SELECT * FROM jobs WHERE id = 42"
+```
+
+Plain `EXPLAIN` may plan a structurally validated `SELECT`, `INSERT`, `UPDATE`,
+or `DELETE`. Because `EXPLAIN ANALYZE` executes its inner statement, StateQL
+accepts only a validated read-only `SELECT`; `SELECT INTO`, writing CTEs, and
+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
+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
+reported as `OUTCOME_UNKNOWN`; inspect database state before replaying it. Raw
+`BEGIN`, `COMMIT`, `ROLLBACK`, savepoint, and other transaction-control SQL
+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,7 +32,9 @@ 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[]>;
     signature(): Promise<string>;
     inspect(kind: string, table?: string): Promise<unknown>;

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() {
@@ -218,6 +226,12 @@ export function normalizePostgresConnectionString(source) {
         return source;
     }
 }
+const POSTGRES_AUTOCOMMIT_STATEMENTS = new Set([
+    "vacuum",
+    "analyze",
+    "reindex",
+    "cluster",
+]);
 class PostgresAdapter {
     readOnly;
     context;
@@ -294,9 +308,36 @@ class PostgresAdapter {
             throw new AdapterWriteError(errorText(error), true);
         }
     }
+    async writeAutocommit(sql, params) {
+        if (this.readOnly)
+            throw new Error("Connection is read-only.");
+        let values;
+        try {
+            values = postgresParams(params);
+            await this.connect();
+        }
+        catch (error) {
+            if (error instanceof AdapterExecutionError)
+                throw error;
+            throw new AdapterWriteError(errorText(error), false);
+        }
+        try {
+            const result = await this.query(sql, values, true, false);
+            return { affectedRows: result.rowCount ?? 0 };
+        }
+        catch (error) {
+            if (error instanceof AdapterExecutionError)
+                throw error;
+            throw new AdapterWriteError(errorText(error), true);
+        }
+    }
     async writeBatch(operations, isolation) {
         if (this.readOnly)
             throw new Error("Connection is read-only.");
+        const unsupported = operations.find((operation) => POSTGRES_AUTOCOMMIT_STATEMENTS.has(operation.statement_type));
+        if (unsupported) {
+            throw new BatchWriteError(`PostgreSQL transactions cannot include ${unsupported.statement_type.toUpperCase()} maintenance statements.`, false);
+        }
         await this.connect();
         const level = isolation.toUpperCase();
         if (!POSTGRES_ISOLATION_LEVELS.has(level)) {
@@ -491,8 +532,8 @@ class PostgresAdapter {
     async setLocalDeadline() {
         await this.query(`SET LOCAL statement_timeout = ${remainingMilliseconds(this.context)}`, [], false);
     }
-    async query(sql, params, outcomeUnknown) {
-        throwIfStopped(this.context, outcomeUnknown);
+    async query(sql, params, outcomeUnknown, preDispatchOutcomeUnknown = outcomeUnknown) {
+        throwIfStopped(this.context, preDispatchOutcomeUnknown);
         try {
             return await withContext(this.client.query(sql, params), this.context, () => this.stop(), outcomeUnknown);
         }
@@ -557,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.");
@@ -596,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.");
@@ -868,6 +948,7 @@ const MYSQL_ISOLATION_LEVELS = new Set([
 const MYSQL_TRANSACTIONAL_STATEMENTS = new Set([
     "delete",
     "insert",
+    "upsert",
     "replace",
     "update",
 ]);
@@ -894,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";
+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;
@@ -9,6 +9,11 @@ export interface SqlAnalysis {
     unboundedMutation: boolean;
     destructive: boolean;
     ordered: boolean;
+    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. */