@fadhilp/stateql 0.19.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -245,7 +245,9 @@ class PostgresAdapter {
245
245
  await this.query("BEGIN READ ONLY", [], false);
246
246
  try {
247
247
  await this.setLocalDeadline();
248
- const result = await this.query(sql, postgresParams(params), false);
248
+ // The extended protocol rejects multiple statements, so a read cannot COMMIT and continue.
249
+ const extended = { text: sql, queryMode: "extended" };
250
+ const result = await this.query(extended, postgresParams(params), false);
249
251
  await this.query("COMMIT", [], false);
250
252
  return {
251
253
  rows: toJsonSafe(result.rows),
@@ -14,5 +14,7 @@ export declare class StateQLError extends Error {
14
14
  });
15
15
  }
16
16
  export declare function exitCodeFor(code: string): number;
17
+ /** True when the database rejected the SQL text itself, not its tables or data. */
18
+ export declare function isSqlSyntaxError(error: unknown): boolean;
17
19
  export declare function isTransientDatabaseError(error: unknown): boolean;
18
20
  export declare function asStateQLError(error: unknown): StateQLError;
@@ -69,6 +69,16 @@ const TRANSIENT_ERROR_NAMES = new Set([
69
69
  "ConnectionTimeoutError",
70
70
  ]);
71
71
  const TRANSIENT_SQLITE_MESSAGE = /database (table )?is locked|SQLITE_BUSY/i;
72
+ const SQL_SYNTAX_MESSAGE = /syntax error|incomplete input|unrecognized token/i;
73
+ /** True when the database rejected the SQL text itself, not its tables or data. */
74
+ export function isSqlSyntaxError(error) {
75
+ if (!(error instanceof Error))
76
+ return false;
77
+ const details = error;
78
+ if (details.code === "42601" || details.errno === 1064)
79
+ return true;
80
+ return SQL_SYNTAX_MESSAGE.test(error.message);
81
+ }
72
82
  // Permanent failures such as a missing table must not invite retries; unknown errors are not retryable.
73
83
  export function isTransientDatabaseError(error) {
74
84
  if (!(error instanceof Error))
@@ -13,7 +13,13 @@ const FIND_OPTIONS = new Set([
13
13
  "hint",
14
14
  "collation",
15
15
  ]);
16
- const AGGREGATE_OPTIONS = new Set(["allowDiskUse", "hint", "collation"]);
16
+ const READ_OPTIONS = {
17
+ find: FIND_OPTIONS,
18
+ aggregate: new Set(["allowDiskUse", "hint", "collation"]),
19
+ countDocuments: new Set(["skip", "limit", "hint", "collation"]),
20
+ distinct: new Set(["collation"]),
21
+ };
22
+ const EXPLAIN_VERBOSITY = new Set(["queryPlanner", "executionStats", "allPlansExecution"]);
17
23
  const WRITE_OPTIONS = {
18
24
  insertOne: new Set(),
19
25
  insertMany: new Set(["ordered"]),
@@ -22,7 +28,10 @@ const WRITE_OPTIONS = {
22
28
  replaceOne: new Set(["upsert", "collation", "hint"]),
23
29
  deleteOne: new Set(["collation", "hint"]),
24
30
  deleteMany: new Set(["collation", "hint"]),
31
+ createIndex: new Set(["name", "unique", "sparse", "expireAfterSeconds", "partialFilterExpression", "collation"]),
32
+ dropIndex: new Set(),
25
33
  };
34
+ const INDEX_KEY_TYPES = new Set([1, -1, "text", "2dsphere", "2d", "hashed"]);
26
35
  const FORBIDDEN_KEYS = new Set([
27
36
  "$out",
28
37
  "$merge",
@@ -40,8 +49,10 @@ const UPDATE_PIPELINE_STAGES = new Set([
40
49
  "$replaceWith",
41
50
  ]);
42
51
  const READ_KEYS = {
43
- find: new Set(["operation", "collection", "filter", "options"]),
44
- aggregate: new Set(["operation", "collection", "pipeline", "options"]),
52
+ find: new Set(["operation", "collection", "filter", "options", "explain"]),
53
+ aggregate: new Set(["operation", "collection", "pipeline", "options", "explain"]),
54
+ countDocuments: new Set(["operation", "collection", "filter", "options"]),
55
+ distinct: new Set(["operation", "collection", "field", "filter", "options"]),
45
56
  };
46
57
  const WRITE_KEYS = {
47
58
  insertOne: new Set(["operation", "collection", "document", "options"]),
@@ -51,33 +62,47 @@ const WRITE_KEYS = {
51
62
  replaceOne: new Set(["operation", "collection", "filter", "replacement", "options"]),
52
63
  deleteOne: new Set(["operation", "collection", "filter", "options"]),
53
64
  deleteMany: new Set(["operation", "collection", "filter", "options"]),
65
+ createIndex: new Set(["operation", "collection", "keys", "options"]),
66
+ dropIndex: new Set(["operation", "collection", "index"]),
54
67
  };
55
68
  export function validateMongoReadCommand(value) {
56
69
  if (!isRecord(value))
57
70
  throw new Error("MongoDB read command must be an object.");
58
71
  const operation = value.operation;
59
- if (operation !== "find" && operation !== "aggregate") {
60
- throw new Error("MongoDB reads only support find and aggregate.");
72
+ if (!isMongoReadOperation(operation)) {
73
+ throw new Error("MongoDB reads only support find, aggregate, countDocuments, and distinct.");
61
74
  }
62
75
  rejectUnknownKeys(value, READ_KEYS[operation], "read command");
63
76
  validateCollection(value.collection);
64
- validateOptions(value.options, operation === "find" ? FIND_OPTIONS : AGGREGATE_OPTIONS, operation);
65
- if (operation === "find") {
66
- if (value.filter !== undefined && !isDocument(value.filter)) {
67
- throw new Error("MongoDB find filter must be an object.");
68
- }
69
- validateFindOptions(value.options);
77
+ validateOptions(value.options, READ_OPTIONS[operation], operation);
78
+ if (value.explain !== undefined && !EXPLAIN_VERBOSITY.has(value.explain)) {
79
+ throw new Error("MongoDB explain must be queryPlanner, executionStats, or allPlansExecution.");
70
80
  }
71
- else {
72
- if (!Array.isArray(value.pipeline) || !value.pipeline.every(isDocument)) {
73
- throw new Error("MongoDB aggregate pipeline must be an array of stage objects.");
74
- }
75
- for (const stage of value.pipeline) {
76
- if (Object.keys(stage).length !== 1) {
77
- throw new Error("Each MongoDB aggregate pipeline stage must contain exactly one operator.");
81
+ if (operation !== "aggregate" && value.filter !== undefined && !isDocument(value.filter)) {
82
+ throw new Error(`MongoDB ${operation} filter must be an object.`);
83
+ }
84
+ switch (operation) {
85
+ case "find":
86
+ case "countDocuments":
87
+ validateFindOptions(value.options);
88
+ break;
89
+ case "aggregate":
90
+ if (!Array.isArray(value.pipeline) || !value.pipeline.every(isDocument)) {
91
+ throw new Error("MongoDB aggregate pipeline must be an array of stage objects.");
78
92
  }
79
- }
80
- validateAggregateOptions(value.options);
93
+ for (const stage of value.pipeline) {
94
+ if (Object.keys(stage).length !== 1) {
95
+ throw new Error("Each MongoDB aggregate pipeline stage must contain exactly one operator.");
96
+ }
97
+ }
98
+ validateAggregateOptions(value.options);
99
+ break;
100
+ case "distinct":
101
+ if (typeof value.field !== "string" || !value.field || value.field.startsWith("$") || value.field.includes("\0")) {
102
+ throw new Error("MongoDB distinct field must be a field name.");
103
+ }
104
+ validateHintAndCollation((value.options ?? {}), operation);
105
+ break;
81
106
  }
82
107
  rejectForbiddenValues(value);
83
108
  return value;
@@ -118,6 +143,17 @@ export function validateMongoWriteCommand(value) {
118
143
  case "deleteMany":
119
144
  requireDocument(value.filter, `${operation} filter`);
120
145
  break;
146
+ case "createIndex":
147
+ validateIndex(value.keys, value.options);
148
+ break;
149
+ case "dropIndex":
150
+ if (typeof value.index !== "string" || !value.index || value.index.includes("\0")) {
151
+ throw new Error("MongoDB dropIndex index must be an index name.");
152
+ }
153
+ if (value.index === "*" || value.index === "_id_") {
154
+ throw new Error(`MongoDB cannot drop index "${value.index}".`);
155
+ }
156
+ break;
121
157
  }
122
158
  rejectForbiddenValues(value);
123
159
  return value;
@@ -145,6 +181,10 @@ export function analyzeMongoWriteSafety(command) {
145
181
  unbounded: Object.keys(value.filter).length === 0,
146
182
  destructive: true,
147
183
  };
184
+ case "createIndex":
185
+ return { unbounded: false, destructive: false };
186
+ case "dropIndex":
187
+ return { unbounded: false, destructive: true };
148
188
  }
149
189
  }
150
190
  /** Deterministic EJSON preserves BSON types and property order. */
@@ -208,13 +248,32 @@ export class MongoAdapter {
208
248
  const signal = operationSignal(this.context);
209
249
  let cursor;
210
250
  try {
211
- if (value.operation === "find") {
251
+ const filter = "filter" in value && value.filter ? value.filter : {};
252
+ if (value.operation === "countDocuments") {
253
+ const options = findOptions(value.options, this.context, signal, Number.MAX_SAFE_INTEGER);
254
+ if (!value.options?.limit)
255
+ delete options.limit;
256
+ const count = await withContext(collection.countDocuments(filter, options), this.context, () => this.stop(), false);
257
+ return { rows: [{ count }], columns: [{ name: "count", type: "number" }] };
258
+ }
259
+ if (value.operation === "distinct") {
212
260
  const options = findOptions(value.options, this.context, signal, maxRows);
213
- cursor = collection.find(value.filter ?? {}, options);
261
+ delete options.limit;
262
+ const values = await withContext(collection.distinct(value.field, filter, options), this.context, () => this.stop(), false);
263
+ return documentsResult(values.slice(0, maxRows).map((item) => ({ value: item })));
214
264
  }
215
- else {
216
- const options = aggregateOptions(value.options, this.context, signal);
217
- cursor = collection.aggregate(value.pipeline, options).limit(maxRows);
265
+ const options = value.operation === "find"
266
+ ? findOptions(value.options, this.context, signal, maxRows)
267
+ : aggregateOptions(value.options, this.context, signal);
268
+ // The driver rejects explain with both limits; timeoutMS still bounds it.
269
+ if (value.explain)
270
+ delete options.maxTimeMS;
271
+ cursor = value.operation === "find"
272
+ ? collection.find(filter, options)
273
+ : collection.aggregate(value.pipeline, options).limit(maxRows);
274
+ if (value.explain) {
275
+ const plan = await withContext(cursor.explain(value.explain), this.context, () => this.stop(), false);
276
+ return documentsResult([plan]);
218
277
  }
219
278
  const documents = await collectCursor(cursor, maxRows, this.context);
220
279
  return documentsResult(documents);
@@ -504,6 +563,15 @@ export class MongoAdapter {
504
563
  },
505
564
  };
506
565
  }
566
+ case "createIndex": {
567
+ const options = writeOptions(command.options, command.operation, session, timeoutMS);
568
+ const name = await collection.createIndex(command.keys, options);
569
+ return { affectedRows: 0, outcome: { acknowledged: true, index_name: name } };
570
+ }
571
+ case "dropIndex": {
572
+ await collection.dropIndex(command.index, { session, timeoutMS });
573
+ return { affectedRows: 0, outcome: { acknowledged: true, index_name: command.index } };
574
+ }
507
575
  }
508
576
  }
509
577
  async requireCollection(name) {
@@ -695,6 +763,33 @@ function validateHintAndCollation(options, operation) {
695
763
  throw new Error(`MongoDB ${operation} collation must be an object.`);
696
764
  }
697
765
  }
766
+ function validateIndex(keys, value) {
767
+ requireDocument(keys, "createIndex keys");
768
+ const entries = Object.entries(keys);
769
+ if (entries.length === 0)
770
+ throw new Error("MongoDB createIndex keys must name at least one field.");
771
+ for (const [field, type] of entries) {
772
+ if (!field || field.startsWith("$") || !INDEX_KEY_TYPES.has(type)) {
773
+ throw new Error("MongoDB createIndex keys must map field names to 1, -1, text, 2dsphere, 2d, or hashed.");
774
+ }
775
+ }
776
+ if (value === undefined)
777
+ return;
778
+ const options = value;
779
+ if (options.name !== undefined && (typeof options.name !== "string" || !options.name || options.name.includes("\0"))) {
780
+ throw new Error("MongoDB createIndex name must be a non-empty string.");
781
+ }
782
+ for (const key of ["unique", "sparse"]) {
783
+ if (options[key] !== undefined && typeof options[key] !== "boolean") {
784
+ throw new Error(`MongoDB createIndex ${key} must be boolean.`);
785
+ }
786
+ }
787
+ if (options.expireAfterSeconds !== undefined)
788
+ numericOption(options.expireAfterSeconds, "createIndex expireAfterSeconds");
789
+ if (options.partialFilterExpression !== undefined && !isDocument(options.partialFilterExpression)) {
790
+ throw new Error("MongoDB createIndex partialFilterExpression must be an object.");
791
+ }
792
+ }
698
793
  function validateUpdate(value) {
699
794
  if (Array.isArray(value)) {
700
795
  if (value.length === 0 || !value.every(isDocument)) {
@@ -815,10 +910,11 @@ function isDocument(value) {
815
910
  function isRecord(value) {
816
911
  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
817
912
  }
913
+ function isMongoReadOperation(value) {
914
+ return typeof value === "string" && Object.hasOwn(READ_KEYS, value);
915
+ }
818
916
  function isMongoWriteOperation(value) {
819
- return value === "insertOne" || value === "insertMany" ||
820
- value === "updateOne" || value === "updateMany" ||
821
- value === "replaceOne" || value === "deleteOne" || value === "deleteMany";
917
+ return typeof value === "string" && Object.hasOwn(WRITE_KEYS, value);
822
918
  }
823
919
  function bsonTypeName(value) {
824
920
  if (!value || typeof value !== "object")
package/dist/src/plans.js CHANGED
@@ -43,7 +43,7 @@ export function prepareRedisPlan(command) {
43
43
  descriptor: redisDescriptor(value.command),
44
44
  parameters: [],
45
45
  statementType: `redis.${value.command.toLowerCase()}`,
46
- destructive: value.command === "DEL",
46
+ destructive: value.command === "DEL" || value.command === "UNLINK",
47
47
  allowUnbounded: false,
48
48
  allowDestructive: true,
49
49
  requiredOverrides: [],
package/dist/src/reads.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import { version } from "./connection.js";
2
2
  import { adapterOfKind, errorMessage, nonNegativeInteger, } from "./core.js";
3
- import { StateQLError } from "./errors.js";
3
+ import { isSqlSyntaxError, StateQLError } from "./errors.js";
4
4
  import { serializeMongoCommand, validateMongoReadCommand } from "./mongodb.js";
5
5
  import { serializeRedisCommand, validateRedisReadCommand } from "./redis.js";
6
6
  import { paginationWarnings } from "./response-data.js";
@@ -26,8 +26,18 @@ export function prepareSqlRead(connection, sql, parameters) {
26
26
  const executionSql = analysis.wrapForLimit
27
27
  ? boundedReadSql(analysis.limitSql ?? sql, fetchLimit)
28
28
  : sql;
29
- if (!analysis.requiresAutocommit)
30
- return sqlAdapter.read(executionSql, parameters);
29
+ if (!analysis.requiresAutocommit) {
30
+ try {
31
+ return await sqlAdapter.read(executionSql, parameters);
32
+ }
33
+ catch (error) {
34
+ // The parser's message points at the position in the SQL the caller wrote.
35
+ if (analysis.parserError && isSqlSyntaxError(error)) {
36
+ throw new StateQLError("INVALID_SQL", analysis.parserError);
37
+ }
38
+ throw error;
39
+ }
40
+ }
31
41
  if (!sqlAdapter.readAutocommit) {
32
42
  throw new StateQLError("UNSUPPORTED_DRIVER", `${analysis.statementType.toUpperCase()} requires adapter autocommit reads.`);
33
43
  }
@@ -169,9 +179,14 @@ function cacheMiss(message) {
169
179
  }
170
180
  function boundedReadSql(sql, limit) {
171
181
  const statement = sql.trim().replace(/;\s*$/, "");
172
- return `SELECT * FROM (${statement}) AS _stateql_bounded LIMIT ${limit}`;
182
+ // The newline ends a trailing line comment before the closing parenthesis.
183
+ return `SELECT * FROM (${statement}\n) AS _stateql_bounded LIMIT ${limit}`;
173
184
  }
174
185
  function mongoPaginationWarnings(command) {
186
+ if (command.operation === "countDocuments" || command.operation === "distinct")
187
+ return [];
188
+ if (command.explain)
189
+ return [];
175
190
  const ordered = command.operation === "find"
176
191
  ? command.options?.sort !== undefined
177
192
  : command.pipeline.some((stage) => Object.hasOwn(stage, "$sort"));
@@ -39,6 +39,7 @@ export declare class RedisAdapter implements BaseAdapter {
39
39
  close(): Promise<void>;
40
40
  private scanValue;
41
41
  private expirationIdentity;
42
+ private keysFingerprint;
42
43
  private keyFingerprint;
43
44
  private connect;
44
45
  private execute;
package/dist/src/redis.js CHANGED
@@ -11,10 +11,15 @@ const MAX_COLLECTION_VALUES = 200;
11
11
  const READ_COMMANDS = new Set([
12
12
  "GET", "MGET", "TYPE", "EXISTS", "TTL", "PTTL", "HGET", "HMGET",
13
13
  "LRANGE", "SCAN", "HSCAN", "SSCAN", "ZSCAN",
14
+ "HGETALL", "HLEN", "SMEMBERS", "SCARD", "SISMEMBER", "ZRANGE", "ZCARD", "ZSCORE",
15
+ "LLEN", "STRLEN", "DBSIZE", "INFO",
14
16
  ]);
15
17
  const WRITE_COMMANDS = new Set([
16
- "SET", "DEL", "HSET", "HDEL", "LPUSH", "RPUSH", "SADD", "SREM", "ZADD", "ZREM",
18
+ "SET", "DEL", "UNLINK", "HSET", "HDEL", "LPUSH", "RPUSH", "SADD", "SREM", "ZADD", "ZREM",
19
+ "EXPIRE", "PEXPIRE", "PERSIST", "INCR", "INCRBY", "DECR", "DECRBY", "HINCRBY",
17
20
  ]);
21
+ const COUNTERS = new Set(["INCR", "INCRBY", "DECR", "DECRBY", "HINCRBY"]);
22
+ const SIZE_COMMANDS = { HGETALL: "HLEN", SMEMBERS: "SCARD" };
18
23
  export function validateRedisReadCommand(value) {
19
24
  const command = validateCommandShape(value);
20
25
  if (!READ_COMMANDS.has(command.command)) {
@@ -26,6 +31,13 @@ export function validateRedisReadCommand(value) {
26
31
  case "TYPE":
27
32
  case "TTL":
28
33
  case "PTTL":
34
+ case "HGETALL":
35
+ case "HLEN":
36
+ case "SMEMBERS":
37
+ case "SCARD":
38
+ case "ZCARD":
39
+ case "LLEN":
40
+ case "STRLEN":
29
41
  requireCount(args, 1);
30
42
  break;
31
43
  case "MGET":
@@ -33,6 +45,8 @@ export function validateRedisReadCommand(value) {
33
45
  requireRange(args, 1, MAX_ARGUMENTS);
34
46
  break;
35
47
  case "HGET":
48
+ case "SISMEMBER":
49
+ case "ZSCORE":
36
50
  requireCount(args, 2);
37
51
  break;
38
52
  case "HMGET":
@@ -42,6 +56,20 @@ export function validateRedisReadCommand(value) {
42
56
  requireCount(args, 3);
43
57
  boundedRange(args[1], args[2]);
44
58
  break;
59
+ case "ZRANGE":
60
+ requireRange(args, 3, 4);
61
+ boundedRange(args[1], args[2]);
62
+ if (args.length === 4 && args[3].toUpperCase() !== "WITHSCORES")
63
+ throw new Error("Redis ZRANGE only supports index ranges with optional WITHSCORES.");
64
+ break;
65
+ case "DBSIZE":
66
+ requireCount(args, 0);
67
+ break;
68
+ case "INFO":
69
+ requireRange(args, 0, 1);
70
+ if (args[0] !== undefined && !/^[A-Za-z]+$/.test(args[0]))
71
+ throw new Error("Redis INFO section is invalid.");
72
+ break;
45
73
  case "SCAN":
46
74
  validateScanArgs(args, false);
47
75
  break;
@@ -61,17 +89,39 @@ export function validateRedisWriteCommand(value) {
61
89
  const args = command.args ?? [];
62
90
  switch (command.command) {
63
91
  case "SET":
64
- requireCount(args, 2);
92
+ validateSetArgs(args);
65
93
  break;
66
94
  case "DEL":
67
- requireCount(args, 1);
95
+ case "UNLINK":
96
+ requireRange(args, 1, MAX_ARGUMENTS);
68
97
  break;
69
98
  case "HSET":
70
- requireCount(args, 3);
99
+ requireRange(args, 3, MAX_ARGUMENTS + 1);
100
+ if (args.length % 2 === 0)
101
+ throw new Error("Redis HSET requires field and value pairs.");
71
102
  break;
72
103
  case "HDEL":
73
104
  requireCount(args, 2);
74
105
  break;
106
+ case "EXPIRE":
107
+ case "PEXPIRE":
108
+ requireCount(args, 2);
109
+ positiveInteger(args[1], command.command);
110
+ break;
111
+ case "PERSIST":
112
+ case "INCR":
113
+ case "DECR":
114
+ requireCount(args, 1);
115
+ break;
116
+ case "INCRBY":
117
+ case "DECRBY":
118
+ requireCount(args, 2);
119
+ integer(args[1], command.command);
120
+ break;
121
+ case "HINCRBY":
122
+ requireCount(args, 3);
123
+ integer(args[2], command.command);
124
+ break;
75
125
  case "LPUSH":
76
126
  case "RPUSH":
77
127
  case "SADD":
@@ -129,6 +179,13 @@ export class RedisAdapter {
129
179
  async read(input) {
130
180
  const command = validateRedisReadCommand(input);
131
181
  await this.connect();
182
+ const sizeCommand = SIZE_COMMANDS[command.command];
183
+ if (sizeCommand) {
184
+ const size = Number(await this.execute([sizeCommand, command.args[0]], false));
185
+ if (size > MAX_COLLECTION_VALUES) {
186
+ throw new Error(`Redis ${command.command} would return ${size} values; the limit is ${MAX_COLLECTION_VALUES}. Use ${command.command === "HGETALL" ? "HSCAN" : "SSCAN"}.`);
187
+ }
188
+ }
132
189
  const raw = await this.execute([command.command, ...(command.args ?? [])], false);
133
190
  const bytes = Buffer.byteLength(JSON.stringify(toJsonSafe(raw)), "utf8");
134
191
  if (bytes > MAX_RESPONSE_BYTES)
@@ -139,7 +196,7 @@ export class RedisAdapter {
139
196
  const command = validateRedisWriteCommand(input);
140
197
  await this.connect();
141
198
  const key = command.args[0];
142
- const [fingerprint, expiresAt] = await Promise.all([this.keyFingerprint(key), this.expirationIdentity(key)]);
199
+ const [fingerprint, expiresAt] = await Promise.all([this.keysFingerprint(writtenKeys(command)), this.expirationIdentity(key)]);
143
200
  return { key, fingerprint, expiresAt };
144
201
  }
145
202
  async write(input, precondition) {
@@ -155,8 +212,9 @@ export class RedisAdapter {
155
212
  try {
156
213
  let raw;
157
214
  if (precondition) {
158
- await this.execute(["WATCH", key], false);
159
- const [fingerprint, expiresAt] = await Promise.all([this.keyFingerprint(key), this.expirationIdentity(key)]);
215
+ const keys = writtenKeys(command);
216
+ await this.execute(["WATCH", ...keys], false);
217
+ const [fingerprint, expiresAt] = await Promise.all([this.keysFingerprint(keys), this.expirationIdentity(key)]);
160
218
  const expiryChanged = precondition.expiresAt < 0
161
219
  ? expiresAt !== precondition.expiresAt
162
220
  : expiresAt < 0 || Math.abs(expiresAt - precondition.expiresAt) > 2_000;
@@ -271,6 +329,14 @@ export class RedisAdapter {
271
329
  const ttl = Number(await this.execute(["PTTL", key], false));
272
330
  return ttl >= 0 ? Date.now() + ttl : ttl;
273
331
  }
332
+ async keysFingerprint(keys) {
333
+ if (keys.length === 1)
334
+ return this.keyFingerprint(keys[0]);
335
+ const fingerprints = [];
336
+ for (const key of keys)
337
+ fingerprints.push(await this.keyFingerprint(key));
338
+ return hash(fingerprints);
339
+ }
274
340
  async keyFingerprint(key) {
275
341
  const usage = await this.execute(["MEMORY", "USAGE", key], false);
276
342
  if (typeof usage === "number" && usage > MAX_RESPONSE_BYTES) {
@@ -331,6 +397,37 @@ function validateScanArgs(args, keyed) {
331
397
  throw new Error(`Redis SCAN COUNT must be 1-${MAX_COLLECTION_VALUES}.`);
332
398
  }
333
399
  }
400
+ function validateSetArgs(args) {
401
+ requireRange(args, 2, 5);
402
+ let expiry = false;
403
+ let condition = false;
404
+ for (let index = 2; index < args.length; index += 1) {
405
+ const option = args[index].toUpperCase();
406
+ if ((option === "NX" || option === "XX") && !condition) {
407
+ condition = true;
408
+ }
409
+ else if ((option === "EX" || option === "PX") && !expiry && index + 1 < args.length) {
410
+ expiry = true;
411
+ positiveInteger(args[++index], `SET ${option}`);
412
+ }
413
+ else {
414
+ throw new Error("Redis SET only supports one of EX or PX and one of NX or XX.");
415
+ }
416
+ }
417
+ }
418
+ function integer(value, name) {
419
+ const number = Number(value);
420
+ if (!/^-?\d+$/.test(value) || !Number.isSafeInteger(number))
421
+ throw new Error(`Redis ${name} requires an integer.`);
422
+ return number;
423
+ }
424
+ function positiveInteger(value, name) {
425
+ if (integer(value, name) < 1)
426
+ throw new Error(`Redis ${name} requires a positive integer.`);
427
+ }
428
+ function writtenKeys(command) {
429
+ return command.command === "DEL" || command.command === "UNLINK" ? command.args : [command.args[0]];
430
+ }
334
431
  function requireCount(args, count) { if (args.length !== count)
335
432
  throw new Error(`Redis command requires ${count} argument(s).`); }
336
433
  function requireRange(args, minimum, maximum) { if (args.length < minimum || args.length > maximum)
@@ -357,6 +454,17 @@ function redisRows(command, raw) {
357
454
  const cursor = String(raw[0]);
358
455
  return { rows: toJsonSafe(rows), columns: inferColumns(rows), nextCursor: cursor === "0" ? null : cursor };
359
456
  }
457
+ if (command.command === "HGETALL" || (command.command === "ZRANGE" && command.args.length === 4)) {
458
+ if (!Array.isArray(raw))
459
+ throw new Error(`Unexpected Redis ${command.command} response.`);
460
+ const [first, second] = command.command === "HGETALL" ? ["field", "value"] : ["value", "score"];
461
+ const rows = Array.from({ length: Math.ceil(raw.length / 2) }, (_, index) => ({ [first]: raw[index * 2], [second]: raw[index * 2 + 1] }));
462
+ return { rows: toJsonSafe(rows), columns: inferColumns(rows) };
463
+ }
464
+ if (command.command === "INFO" && typeof raw === "string") {
465
+ const rows = infoRows(raw);
466
+ return { rows, columns: inferColumns(rows) };
467
+ }
360
468
  if (Array.isArray(raw)) {
361
469
  const rows = raw.map((value, index) => ({ index, value }));
362
470
  return { rows: toJsonSafe(rows), columns: inferColumns(rows) };
@@ -364,9 +472,28 @@ function redisRows(command, raw) {
364
472
  const rows = [{ value: raw }];
365
473
  return { rows: toJsonSafe(rows), columns: inferColumns(rows) };
366
474
  }
475
+ function infoRows(text) {
476
+ const rows = [];
477
+ let section = "";
478
+ for (const line of text.split(/\r?\n/)) {
479
+ if (line.startsWith("# "))
480
+ section = line.slice(2).trim().toLowerCase();
481
+ const separator = line.indexOf(":");
482
+ if (line.startsWith("#") || separator < 1)
483
+ continue;
484
+ rows.push({ section, field: line.slice(0, separator), value: line.slice(separator + 1) });
485
+ }
486
+ return rows;
487
+ }
367
488
  function inferColumns(rows) { const first = rows[0] ?? {}; return Object.keys(first).map((name) => ({ name, type: typeof first[name] })); }
368
489
  function normalizeScalar(value) { if (value === null || typeof value === "string" || typeof value === "number")
369
490
  return value; return JSON.stringify(toJsonSafe(value)); }
370
- function redisAffectedRows(command, result) { if (typeof result === "number")
371
- return result; return command === "SET" && result === "OK" ? 1 : 0; }
491
+ function redisAffectedRows(command, result) {
492
+ // Counters return the new value, not a count.
493
+ if (COUNTERS.has(command))
494
+ return 1;
495
+ if (typeof result === "number")
496
+ return result;
497
+ return command === "SET" && result === "OK" ? 1 : 0;
498
+ }
372
499
  function errorText(error) { return error instanceof Error ? error.message : String(error); }
package/dist/src/sql.d.ts CHANGED
@@ -14,6 +14,8 @@ export interface SqlAnalysis {
14
14
  requiresAutocommit: boolean;
15
15
  /** Analysis-only SQL with trailing trivia removed when limit wrapping needs it. */
16
16
  limitSql?: string;
17
+ /** Set when the parser could not read this read statement; the database checks it instead. */
18
+ parserError?: string;
17
19
  }
18
20
  export declare function analyzeSql(sql: string, driver: SqlDriver): SqlAnalysis;
19
21
  /** @internal Compatibility for existing connection records during Mongo rollout. */
package/dist/src/sql.js CHANGED
@@ -143,7 +143,7 @@ function parseSqlStatement(sql, driver) {
143
143
  parsed = parser.astify(parserSql, { database });
144
144
  }
145
145
  catch (error) {
146
- throw new StateQLError("INVALID_SQL", syntaxErrorMessage(error, parserSql));
146
+ throw new SqlSyntaxError(syntaxErrorMessage(error, parserSql));
147
147
  }
148
148
  if (Array.isArray(parsed) && parsed.length !== 1) {
149
149
  throw new StateQLError("INVALID_SQL", "Exactly one SQL statement is required.");
@@ -163,7 +163,53 @@ function parseSqlStatement(sql, driver) {
163
163
  return { ast, normalized };
164
164
  }
165
165
  function analyzeParsedSql(sql, driver) {
166
- return analyzeParsedStatement(parseSqlStatement(sql, driver), driver);
166
+ try {
167
+ return analyzeParsedStatement(parseSqlStatement(sql, driver), driver);
168
+ }
169
+ catch (error) {
170
+ return unparsedRead(sql, driver, error);
171
+ }
172
+ }
173
+ const WRITABLE_CTE = /\bAS\s*(?:NOT\s+)?(?:MATERIALIZED\s*)?\(\s*(?:INSERT|UPDATE|DELETE|MERGE)\b/i;
174
+ /** SQL the parser could not read, as opposed to SQL it read and rejected. */
175
+ class SqlSyntaxError extends StateQLError {
176
+ constructor(message) {
177
+ super("INVALID_SQL", message);
178
+ }
179
+ }
180
+ // The parser misses much valid SQL. Adapters run every read in a read-only
181
+ // transaction that accepts one statement, so the database rejects any write.
182
+ function unparsedRead(sql, driver, error) {
183
+ if (!(error instanceof SqlSyntaxError) || !looksLikeRead(sql, driver))
184
+ throw error;
185
+ if (hasStatementSeparator(sql))
186
+ throw error;
187
+ if (WRITABLE_CTE.test(sql)) {
188
+ throw new StateQLError("INVALID_SQL", "Read statements cannot contain writes or SELECT INTO.");
189
+ }
190
+ const normalized = sql.trim().replace(/;\s*$/, "");
191
+ return {
192
+ ast: { type: "select" },
193
+ normalized,
194
+ statementType: "select",
195
+ read: true,
196
+ unboundedMutation: false,
197
+ destructive: false,
198
+ ordered: /\border\s+by\b/i.test(normalized),
199
+ wrapForLimit: true,
200
+ cacheable: true,
201
+ requiresAutocommit: false,
202
+ parserError: error.message,
203
+ };
204
+ }
205
+ function looksLikeRead(sql, driver) {
206
+ const command = driver === "mysql"
207
+ ? new MySqlPrefixScanner(sql).readWord()?.value
208
+ : new SqlPrefixScanner(sql, driver).readWord()?.value;
209
+ if (command !== "SELECT" && command !== "WITH")
210
+ return false;
211
+ // A MySQL read-only transaction does not stop SELECT from writing server files.
212
+ return driver !== "mysql" || !/\binto\s+(?:outfile|dumpfile)\b/i.test(sql);
167
213
  }
168
214
  function analyzeParsedStatement({ ast, normalized }, driver) {
169
215
  const rawType = String(ast.type);
@@ -291,11 +337,31 @@ const EXPLAIN_FORMATS = new Set(["TEXT", "XML", "JSON", "YAML"]);
291
337
  const EXPLAIN_SERIALIZE = new Set(["NONE", "TEXT", "BINARY"]);
292
338
  const BOOLEAN_VALUES = new Set(["TRUE", "FALSE", "ON", "OFF", "1", "0"]);
293
339
  const POSTGRES_SHOW_SETTINGS = new Set([
340
+ "application_name",
341
+ "client_encoding",
342
+ "datestyle",
294
343
  "default_transaction_isolation",
344
+ "default_transaction_read_only",
345
+ "effective_cache_size",
346
+ "idle_in_transaction_session_timeout",
347
+ "intervalstyle",
348
+ "lc_collate",
349
+ "lc_ctype",
350
+ "lock_timeout",
351
+ "maintenance_work_mem",
352
+ "max_connections",
353
+ "random_page_cost",
354
+ "search_path",
355
+ "server_encoding",
295
356
  "server_version",
296
357
  "server_version_num",
358
+ "shared_buffers",
359
+ "standard_conforming_strings",
360
+ "statement_timeout",
361
+ "timezone",
297
362
  "transaction_isolation",
298
363
  "transaction_read_only",
364
+ "work_mem",
299
365
  ]);
300
366
  function analyzePostgresCommand(sql) {
301
367
  const scanner = new SqlPrefixScanner(sql, "postgres");
@@ -354,7 +420,13 @@ function analyzeMySqlSql(sql) {
354
420
  command?.value === "CHECK") {
355
421
  return analyzeMySqlMaintenance(sql, scanner, command.value);
356
422
  }
357
- const parsed = parseSqlStatement(sql, "mysql");
423
+ let parsed;
424
+ try {
425
+ parsed = parseSqlStatement(sql, "mysql");
426
+ }
427
+ catch (error) {
428
+ return unparsedRead(sql, "mysql", error);
429
+ }
358
430
  const details = parsed.ast;
359
431
  if (details.type === "explain") {
360
432
  const inner = details.expr;
@@ -551,6 +623,7 @@ function analyzePostgresExplain(sql, scanner) {
551
623
  wrapForLimit: false,
552
624
  cacheable: false,
553
625
  requiresAutocommit: false,
626
+ ...(inner.parserError ? { parserError: inner.parserError } : {}),
554
627
  };
555
628
  }
556
629
  function validateExplainOption(option, value) {
@@ -1045,9 +1118,24 @@ class SqlPrefixScanner {
1045
1118
  }
1046
1119
  }
1047
1120
  function postgresStatementBody(sql) {
1121
+ let last = [0, 0];
1122
+ for (const token of postgresTokens(sql))
1123
+ last = token;
1124
+ const end = sql[last[0]] === ";" ? last[0] : last[1];
1125
+ return sql.slice(0, end).trim();
1126
+ }
1127
+ /** True when a ; separates two statements; one trailing ; is allowed. */
1128
+ function hasStatementSeparator(sql) {
1129
+ let afterSeparator = false;
1130
+ for (const [start] of postgresTokens(sql)) {
1131
+ if (afterSeparator)
1132
+ return true;
1133
+ afterSeparator = sql[start] === ";";
1134
+ }
1135
+ return false;
1136
+ }
1137
+ function* postgresTokens(sql) {
1048
1138
  let index = 0;
1049
- let lastTokenStart = 0;
1050
- let lastTokenEnd = 0;
1051
1139
  while (index < sql.length) {
1052
1140
  if (/\s/u.test(sql[index])) {
1053
1141
  index += 1;
@@ -1093,11 +1181,8 @@ function postgresStatementBody(sql) {
1093
1181
  else {
1094
1182
  index += 1;
1095
1183
  }
1096
- lastTokenStart = start;
1097
- lastTokenEnd = index;
1184
+ yield [start, index];
1098
1185
  }
1099
- const end = sql[lastTokenStart] === ";" ? lastTokenStart : lastTokenEnd;
1100
- return sql.slice(0, end).trim();
1101
1186
  }
1102
1187
  function invalidPostgresSyntax(command) {
1103
1188
  throw new StateQLError("INVALID_SQL", `Unsupported or invalid PostgreSQL ${command} syntax.`);
@@ -147,16 +147,30 @@ export interface MongoMutationOptions {
147
147
  collation?: MongoDocument;
148
148
  hint?: string | MongoDocument;
149
149
  }
150
+ export type MongoExplainVerbosity = "queryPlanner" | "executionStats" | "allPlansExecution";
150
151
  export type MongoReadCommand = {
151
152
  operation: "find";
152
153
  collection: string;
153
154
  filter?: MongoDocument;
154
155
  options?: MongoFindOptions;
156
+ explain?: MongoExplainVerbosity;
155
157
  } | {
156
158
  operation: "aggregate";
157
159
  collection: string;
158
160
  pipeline: MongoDocument[];
159
161
  options?: MongoAggregateOptions;
162
+ explain?: MongoExplainVerbosity;
163
+ } | {
164
+ operation: "countDocuments";
165
+ collection: string;
166
+ filter?: MongoDocument;
167
+ options?: Pick<MongoFindOptions, "skip" | "limit" | "hint" | "collation">;
168
+ } | {
169
+ operation: "distinct";
170
+ collection: string;
171
+ field: string;
172
+ filter?: MongoDocument;
173
+ options?: Pick<MongoFindOptions, "collation">;
160
174
  };
161
175
  export type MongoWriteCommand = {
162
176
  operation: "insertOne";
@@ -187,7 +201,24 @@ export type MongoWriteCommand = {
187
201
  collection: string;
188
202
  filter: MongoDocument;
189
203
  options?: Omit<MongoMutationOptions, "upsert">;
204
+ } | {
205
+ operation: "createIndex";
206
+ collection: string;
207
+ keys: Record<string, 1 | -1 | "text" | "2dsphere" | "2d" | "hashed">;
208
+ options?: MongoIndexOptions;
209
+ } | {
210
+ operation: "dropIndex";
211
+ collection: string;
212
+ index: string;
190
213
  };
214
+ export interface MongoIndexOptions {
215
+ name?: string;
216
+ unique?: boolean;
217
+ sparse?: boolean;
218
+ expireAfterSeconds?: number;
219
+ partialFilterExpression?: MongoDocument;
220
+ collation?: MongoDocument;
221
+ }
191
222
  export interface MongoWriteOutcome {
192
223
  acknowledged: boolean;
193
224
  inserted_id?: unknown;
@@ -198,6 +229,7 @@ export interface MongoWriteOutcome {
198
229
  upserted_count?: number;
199
230
  upserted_id?: unknown;
200
231
  deleted_count?: number;
232
+ index_name?: string;
201
233
  }
202
234
  export interface RedisCommand {
203
235
  command: string;
@@ -56,6 +56,9 @@ export function prepareMongoWrite(connection, command, safety) {
56
56
  parameters: [serialized],
57
57
  statementType: `mongo.${value.operation}`,
58
58
  fingerprint: hash({ command: serialized, database: databaseIdentity(connection) }),
59
+ ...(value.operation === "createIndex" || value.operation === "dropIndex"
60
+ ? { stagingError: "MongoDB index changes cannot be staged in a transaction." }
61
+ : {}),
59
62
  conflictMessage: "The document changed or was removed. Reload before editing.",
60
63
  unknownAction: REPLAY_ACTION,
61
64
  execute: (adapter) => adapterOfKind(adapter, "mongodb").write(value, safety.expectedRows),
package/docs/databases.md CHANGED
@@ -41,7 +41,12 @@ transaction-control SQL is unsupported: use
41
41
  [staged transactions](writes.md#transactions), not `BEGIN` or `COMMIT` statements.
42
42
  MongoDB and Redis use separate native command APIs.
43
43
 
44
- Unrecognized or parser-unsupported forms remain blocked.
44
+ A single `SELECT` or `WITH` statement that the parser cannot read still runs as
45
+ a read: the database checks it inside its read-only transaction (SQLite
46
+ `query_only`), which rejects writes and a second statement. A database syntax
47
+ error is reported as `INVALID_SQL`. Statement separators, writing CTEs, and
48
+ MySQL `INTO OUTFILE`/`DUMPFILE` are rejected before dispatch. Other
49
+ parser-unsupported forms, including every write, remain blocked.
45
50
 
46
51
  ## Dialect upserts
47
52
 
@@ -80,12 +85,22 @@ user-defined or incorrectly labelled functions.
80
85
 
81
86
  StateQL supports PostgreSQL 14–18. Top-level `VALUES` is a bounded read and
82
87
  accepts normal PostgreSQL positional parameters. It is conservatively
83
- non-cacheable because expressions may be volatile. The following narrow `SHOW`
84
- allowlist is also available as non-cacheable diagnostics:
85
- `server_version`, `server_version_num`, `transaction_read_only`,
86
- `transaction_isolation`, and `default_transaction_isolation`. `SHOW ALL` and
87
- other settings remain blocked. Syntax accepted by StateQL but introduced by a
88
- newer PostgreSQL release may be rejected safely by an older server.
88
+ non-cacheable because expressions may be volatile. `SHOW` of these non-secret
89
+ settings is available as a non-cacheable diagnostic: `application_name`,
90
+ `client_encoding`, `DateStyle`, `default_transaction_isolation`,
91
+ `default_transaction_read_only`, `effective_cache_size`,
92
+ `idle_in_transaction_session_timeout`, `IntervalStyle`, `lc_collate`,
93
+ `lc_ctype`, `lock_timeout`, `maintenance_work_mem`, `max_connections`,
94
+ `random_page_cost`, `search_path`, `server_encoding`, `server_version`,
95
+ `server_version_num`, `shared_buffers`, `standard_conforming_strings`,
96
+ `statement_timeout`, `TimeZone`, `transaction_isolation`,
97
+ `transaction_read_only`, and `work_mem`. `SHOW ALL` and other settings remain
98
+ blocked. Syntax accepted by StateQL but introduced by a newer PostgreSQL release
99
+ may be rejected safely by an older server.
100
+
101
+ To set a session `search_path` (or another setting), add the libpq `options`
102
+ parameter to the connection URL, URL-encoded:
103
+ `postgres://app@db/app?options=-c%20search_path%3Dreporting%2Cpublic`.
89
104
 
90
105
  `VACUUM`, `ANALYZE`, `REINDEX`, and `CLUSTER` are PostgreSQL maintenance writes:
91
106
 
@@ -167,9 +182,15 @@ stql mongo plan '{"operation":"deleteMany","collection":"users","filter":{"disab
167
182
  ```
168
183
 
169
184
  The TypeScript equivalents are `mongoQuery(command)`, `mongoExec(command)`, and
170
- `mongoPlan(command)`. Supported reads are `find` and `aggregate`; writes are
171
- `insertOne`, `insertMany`, `updateOne`, `updateMany`, `replaceOne`, `deleteOne`,
172
- and `deleteMany`. Result documents are JSON-safe, order-preserving EJSON: for example,
185
+ `mongoPlan(command)`. Supported reads are `find`, `aggregate`, `countDocuments`
186
+ (one `{count}` row), and `distinct` (one `{value}` row per value, capped by the
187
+ row limit). `find` and `aggregate` accept `explain: "queryPlanner" |
188
+ "executionStats" | "allPlansExecution"` and return the plan as one document.
189
+ Writes are `insertOne`, `insertMany`, `updateOne`, `updateMany`, `replaceOne`,
190
+ `deleteOne`, `deleteMany`, `createIndex` (`keys`, `options`: `name`, `unique`,
191
+ `sparse`, `expireAfterSeconds`, `partialFilterExpression`, `collation`), and
192
+ `dropIndex` (`index` name; destructive; `*` and `_id_` are rejected). Index
193
+ changes cannot be staged in a transaction. Result documents are JSON-safe, order-preserving EJSON: for example,
173
194
  ObjectIds and dates appear as `{ "$oid": "..." }` and
174
195
  `{ "$date": { "$numberLong": "..." } }`.
175
196
 
@@ -208,9 +229,15 @@ stql object key app:status
208
229
  Writes and plans require a read-write connection. The TypeScript methods are:
209
230
 
210
231
  - `redisQuery`: `GET`, `MGET`, `TYPE`, `EXISTS`, `TTL`, `PTTL`, `HGET`, `HMGET`,
211
- bounded `LRANGE`, and bounded `SCAN`/`HSCAN`/`SSCAN`/`ZSCAN`.
212
- - `redisExec` and `redisPlan`: one-key `SET`, `DEL`, `HSET`, `HDEL`, `LPUSH`,
213
- `RPUSH`, `SADD`, `SREM`, `ZADD`, or `ZREM` mutation.
232
+ `HLEN`, `SCARD`, `SISMEMBER`, `ZCARD`, `ZSCORE`, `LLEN`, `STRLEN`, `DBSIZE`,
233
+ `INFO [section]` (one row per field), bounded `LRANGE`, bounded index
234
+ `ZRANGE [WITHSCORES]`, `HGETALL`/`SMEMBERS` on keys with at most 200 values,
235
+ and bounded `SCAN`/`HSCAN`/`SSCAN`/`ZSCAN`.
236
+ - `redisExec` and `redisPlan`: `SET` (optional `EX`/`PX` and `NX`/`XX`),
237
+ `DEL`/`UNLINK` (up to 100 keys), `HSET` (field/value pairs), `HDEL`,
238
+ `HINCRBY`, `INCR`, `INCRBY`, `DECR`, `DECRBY`, `EXPIRE`, `PEXPIRE`, `PERSIST`,
239
+ `LPUSH`, `RPUSH`, `SADD`, `SREM`, `ZADD`, or `ZREM`. A plan guards every key
240
+ that `DEL`/`UNLINK` names and the first key of other commands.
214
241
  - `describeObject({kind:"key",name})`: bounded string/hash/list/set/zset value
215
242
  inspection with TTL and continuation metadata where applicable.
216
243
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fadhilp/stateql",
3
- "version": "0.19.0",
3
+ "version": "0.20.0",
4
4
  "description": "Stateful, agent-oriented database CLI for safe result reuse",
5
5
  "repository": {
6
6
  "type": "git",
@@ -22,16 +22,23 @@ stql mongo query '{"operation":"aggregate","collection":"orders","pipeline":[{"$
22
22
 
23
23
  | Operation | Keys |
24
24
  | --- | --- |
25
- | `find` | `collection`, `filter`, `options`: `projection`, `sort`, `skip`, `limit`, `hint`, `collation` |
26
- | `aggregate` | `collection`, `pipeline`, `options`: `allowDiskUse`, `hint`, `collation` |
25
+ | `find` | `collection`, `filter`, `options`: `projection`, `sort`, `skip`, `limit`, `hint`, `collation`; `explain` |
26
+ | `aggregate` | `collection`, `pipeline`, `options`: `allowDiskUse`, `hint`, `collation`; `explain` |
27
+ | `countDocuments` | `collection`, `filter`, `options`: `skip`, `limit`, `hint`, `collation`. Returns `{count}`. |
28
+ | `distinct` | `collection`, `field`, `filter`, `options`: `collation`. One `{value}` row per value. |
27
29
  | `insertOne` / `insertMany` | `document` / `documents` |
28
30
  | `updateOne` / `updateMany` | `filter`, `update`, `options`: `upsert`, `collation`, `hint` |
29
31
  | `replaceOne` | `filter`, `replacement` |
30
32
  | `deleteOne` / `deleteMany` | `filter` |
33
+ | `createIndex` | `keys` (`{"field":1}`, `-1`, `"text"`, `"2dsphere"`, `"2d"`, `"hashed"`), `options`: `name`, `unique`, `sparse`, `expireAfterSeconds`, `partialFilterExpression`, `collation` |
34
+ | `dropIndex` | `index` (index name) |
31
35
 
36
+ - `explain` is `"queryPlanner"`, `"executionStats"`, or `"allPlansExecution"`.
37
+ It returns the query plan as one document.
32
38
  - Writes: `stql mongo exec '<command>'`; review first with `stql mongo plan`.
33
- Empty filters need `--allow-unbounded`; deletes and replacements need
34
- `--allow-destructive`. Both need user approval.
39
+ Empty filters need `--allow-unbounded`; deletes, replacements, and
40
+ `dropIndex` need `--allow-destructive`. Both need user approval. Index
41
+ changes cannot run inside a staged transaction.
35
42
  - `$out`, `$merge`, `$where`, `$function`, `$accumulator`, and server-side
36
43
  JavaScript are rejected.
37
44
  - Documents with different fields come back as objects, not row arrays.
@@ -51,8 +58,12 @@ stql redis exec '{"command":"SET","args":["app:status","ready"]}' --idempotency-
51
58
 
52
59
  | Kind | Allowed commands |
53
60
  | --- | --- |
54
- | Read (`redis query`) | `GET`, `MGET`, `TYPE`, `EXISTS`, `TTL`, `PTTL`, `HGET`, `HMGET`, bounded `LRANGE`, bounded `SCAN`/`HSCAN`/`SSCAN`/`ZSCAN` |
55
- | Write (`redis exec`, `redis plan`) | one key: `SET`, `DEL`, `HSET`, `HDEL`, `LPUSH`, `RPUSH`, `SADD`, `SREM`, `ZADD`, `ZREM` |
61
+ | Read (`redis query`) | `GET`, `MGET`, `TYPE`, `EXISTS`, `TTL`, `PTTL`, `HGET`, `HMGET`, `HGETALL`, `HLEN`, `SMEMBERS`, `SCARD`, `SISMEMBER`, `ZCARD`, `ZSCORE`, `LLEN`, `STRLEN`, `DBSIZE`, `INFO [section]`, bounded `LRANGE`, bounded `ZRANGE key start stop [WITHSCORES]`, bounded `SCAN`/`HSCAN`/`SSCAN`/`ZSCAN` |
62
+ | Write (`redis exec`, `redis plan`) | `SET key value [EX s\|PX ms] [NX\|XX]`, `DEL`/`UNLINK` (several keys), `HSET` (several field/value pairs), `HDEL`, `HINCRBY`, `INCR`, `INCRBY`, `DECR`, `DECRBY`, `EXPIRE`, `PEXPIRE`, `PERSIST`, `LPUSH`, `RPUSH`, `SADD`, `SREM`, `ZADD`, `ZREM` |
63
+
64
+ - Ranges (`LRANGE`, `ZRANGE`) return at most 200 values; use non-negative
65
+ indexes. `HGETALL` and `SMEMBERS` fail on keys with more than 200 values; use
66
+ `HSCAN` or `SSCAN` for those.
56
67
 
57
68
  - `KEYS`, scripts, pub/sub, blocking commands, and admin commands are rejected.
58
69
  - Key pages can be empty or repeat keys while data changes. Keep following