@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.
- package/dist/src/adapters.js +3 -1
- package/dist/src/errors.d.ts +2 -0
- package/dist/src/errors.js +10 -0
- package/dist/src/mongodb.js +124 -28
- package/dist/src/plans.js +1 -1
- package/dist/src/reads.js +19 -4
- package/dist/src/redis.d.ts +1 -0
- package/dist/src/redis.js +136 -9
- package/dist/src/sql.d.ts +2 -0
- package/dist/src/sql.js +94 -9
- package/dist/src/types.d.ts +32 -0
- package/dist/src/writes.js +3 -0
- package/docs/databases.md +40 -13
- package/package.json +1 -1
- package/skills/stateql/reference/native.md +17 -6
package/dist/src/adapters.js
CHANGED
|
@@ -245,7 +245,9 @@ class PostgresAdapter {
|
|
|
245
245
|
await this.query("BEGIN READ ONLY", [], false);
|
|
246
246
|
try {
|
|
247
247
|
await this.setLocalDeadline();
|
|
248
|
-
|
|
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),
|
package/dist/src/errors.d.ts
CHANGED
|
@@ -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;
|
package/dist/src/errors.js
CHANGED
|
@@ -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))
|
package/dist/src/mongodb.js
CHANGED
|
@@ -13,7 +13,13 @@ const FIND_OPTIONS = new Set([
|
|
|
13
13
|
"hint",
|
|
14
14
|
"collation",
|
|
15
15
|
]);
|
|
16
|
-
const
|
|
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
|
|
60
|
-
throw new Error("MongoDB reads only support find and
|
|
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
|
|
65
|
-
if (
|
|
66
|
-
|
|
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
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
216
|
-
|
|
217
|
-
|
|
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 === "
|
|
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
|
-
|
|
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
|
-
|
|
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"));
|
package/dist/src/redis.d.ts
CHANGED
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
|
-
|
|
92
|
+
validateSetArgs(args);
|
|
65
93
|
break;
|
|
66
94
|
case "DEL":
|
|
67
|
-
|
|
95
|
+
case "UNLINK":
|
|
96
|
+
requireRange(args, 1, MAX_ARGUMENTS);
|
|
68
97
|
break;
|
|
69
98
|
case "HSET":
|
|
70
|
-
|
|
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.
|
|
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
|
-
|
|
159
|
-
|
|
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) {
|
|
371
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.`);
|
package/dist/src/types.d.ts
CHANGED
|
@@ -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;
|
package/dist/src/writes.js
CHANGED
|
@@ -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
|
-
|
|
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.
|
|
84
|
-
|
|
85
|
-
`
|
|
86
|
-
`
|
|
87
|
-
|
|
88
|
-
|
|
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
|
|
171
|
-
|
|
172
|
-
|
|
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
|
-
|
|
212
|
-
|
|
213
|
-
`
|
|
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
|
@@ -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
|
|
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`) |
|
|
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
|