@fadhilp/stateql 0.15.1 → 0.17.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/agent-response.js +6 -1
- package/dist/src/cli.js +119 -32
- package/dist/src/index.d.ts +1 -1
- package/dist/src/os-credentials.d.ts +6 -0
- package/dist/src/os-credentials.js +96 -0
- package/dist/src/sql.d.ts +7 -1
- package/dist/src/sql.js +88 -8
- package/dist/src/stateql.d.ts +3 -2
- package/dist/src/stateql.js +92 -6
- package/dist/src/types.d.ts +17 -1
- package/dist/src/util.d.ts +1 -0
- package/dist/src/util.js +1 -1
- package/docs/batch.md +2 -1
- package/docs/cli.md +16 -10
- package/docs/connections.md +29 -7
- package/docs/databases.md +2 -2
- package/docs/library.md +3 -1
- package/docs/results.md +12 -0
- package/docs/writes.md +6 -0
- package/package.json +2 -1
- package/skills/stateql/SKILL.md +20 -7
- package/skills/stateql/reference/writes.md +4 -1
|
@@ -3,7 +3,7 @@ const RESULT_COMMANDS = new Set(["query", "mongo.query", "redis.query", "filter"
|
|
|
3
3
|
const FALSE_DEFAULT_KEYS = ["cached", "duplicate", "duplicate_override"];
|
|
4
4
|
const SHARED_HISTORY_KEYS = ["session_id", "actor_id", "actor_name", "origin"];
|
|
5
5
|
// The caller already holds the handle it passed to these commands.
|
|
6
|
-
const HANDLE_ECHO_COMMANDS = new Set(["rows", "count", "columns"]);
|
|
6
|
+
const HANDLE_ECHO_COMMANDS = new Set(["rows", "count", "columns", "summarize"]);
|
|
7
7
|
const WRITE_COMMANDS = new Set(["exec", "mongo.exec", "redis.exec", "apply"]);
|
|
8
8
|
const COMMAND_ALIASES = {
|
|
9
9
|
"objects.list": "objects",
|
|
@@ -55,6 +55,10 @@ export function agentResponse(result, commandName) {
|
|
|
55
55
|
data.total = data.rows;
|
|
56
56
|
delete data.rows;
|
|
57
57
|
}
|
|
58
|
+
else if (currentCommand === "summarize" && Array.isArray(data.columns)) {
|
|
59
|
+
const table = columnarRows(data.columns, undefined);
|
|
60
|
+
Object.assign(data, { columns: table.columns, rows: table.rows });
|
|
61
|
+
}
|
|
58
62
|
else if (WRITE_COMMANDS.has(currentCommand)) {
|
|
59
63
|
delete data.actor_id;
|
|
60
64
|
delete data.plan_id;
|
|
@@ -187,6 +191,7 @@ function primaryHandleKey(currentCommand) {
|
|
|
187
191
|
rows: "result_id",
|
|
188
192
|
count: "result_id",
|
|
189
193
|
columns: "result_id",
|
|
194
|
+
summarize: "result_id",
|
|
190
195
|
export: "result_id",
|
|
191
196
|
alias: "result_id",
|
|
192
197
|
"alias.set": "result_id",
|
package/dist/src/cli.js
CHANGED
|
@@ -7,6 +7,42 @@ import { BSON } from "mongodb";
|
|
|
7
7
|
import { exitCodeFor } from "./errors.js";
|
|
8
8
|
import { StateQL } from "./stateql.js";
|
|
9
9
|
import { agentResponse } from "./agent-response.js";
|
|
10
|
+
import { askPassword, cliCredentialResolver, deleteOsPassword, saveOsPassword } from "./os-credentials.js";
|
|
11
|
+
const USAGE = `stql connect <target> [--name NAME] [--read-only|--read-write]
|
|
12
|
+
stql connect --env ENV | --credential-ref REF | --profile NAME [--name NAME] [--read-only|--read-write]
|
|
13
|
+
stql disconnect|status
|
|
14
|
+
stql actor show | set-name <display-name>
|
|
15
|
+
stql profile add|update NAME [TARGET [--ask-password] | --env ENV | --credential-ref REF]
|
|
16
|
+
[--read-only|--read-write]
|
|
17
|
+
stql profile list|show|remove NAME
|
|
18
|
+
stql session start|list|show|summary|close
|
|
19
|
+
stql query <sql> | --file FILE [--params JSON | --param VALUE... | --params-file FILE]
|
|
20
|
+
[--cache auto|bypass|require] [--preview-rows 0..200]
|
|
21
|
+
stql filter <result-handle> <predicate> [--params JSON | --param VALUE...]
|
|
22
|
+
stql exec <sql> | --file FILE [--params JSON | --param VALUE...] [--idempotency-key KEY]
|
|
23
|
+
[--replay] [--allow-unbounded] [--allow-destructive]
|
|
24
|
+
stql plan <sql> | --file FILE [--params JSON | --param VALUE...] [--allow-unbounded]
|
|
25
|
+
[--allow-destructive]
|
|
26
|
+
stql apply <plan-handle>
|
|
27
|
+
stql mongo query|exec|plan '<EJSON command>' | --file FILE [--cache MODE] [--idempotency-key KEY]
|
|
28
|
+
[--replay] [--allow-unbounded] [--allow-destructive]
|
|
29
|
+
stql redis query|exec|plan '<JSON command>' | --file FILE [--cache MODE] [--idempotency-key KEY]
|
|
30
|
+
[--replay]
|
|
31
|
+
stql show|count|columns|summarize <result-handle>
|
|
32
|
+
stql rows <result-handle> [--offset N] [--limit N] [--columns a,b]
|
|
33
|
+
stql alias set <name> <result-handle>
|
|
34
|
+
stql export <result-handle> --output FILE [--format json|jsonl|csv] [--columns a,b]
|
|
35
|
+
stql inspect schema|table|collection|collections|columns|indexes|constraints [name]
|
|
36
|
+
stql objects [KIND] [--schema NAME] [--search TEXT] [--offset N|--cursor CURSOR] [--limit N]
|
|
37
|
+
stql object KIND NAME [IDENTITY] [--schema NAME]
|
|
38
|
+
stql transaction begin|status|commit|rollback [--isolation LEVEL]
|
|
39
|
+
stql history [--limit N] [--offset N] [--category statement|introspection|management]
|
|
40
|
+
[--internal|--external]
|
|
41
|
+
stql receipt <operation-handle>
|
|
42
|
+
stql doctor|capabilities
|
|
43
|
+
stql purge [expired|results|history|all]
|
|
44
|
+
stql batch [commands.json|commands.jsonl|-] [--continue-on-error]
|
|
45
|
+
stql pipe [--continue-on-error]`;
|
|
10
46
|
const parsed = parseArgs({
|
|
11
47
|
allowPositionals: true,
|
|
12
48
|
strict: true,
|
|
@@ -15,11 +51,14 @@ const parsed = parseArgs({
|
|
|
15
51
|
profile: { type: "string" },
|
|
16
52
|
env: { type: "string" },
|
|
17
53
|
"credential-ref": { type: "string" },
|
|
54
|
+
"ask-password": { type: "boolean" },
|
|
18
55
|
"read-only": { type: "boolean" },
|
|
19
56
|
"read-write": { type: "boolean" },
|
|
20
57
|
params: { type: "string" },
|
|
21
58
|
param: { type: "string", multiple: true },
|
|
22
59
|
"params-file": { type: "string" },
|
|
60
|
+
file: { type: "string" },
|
|
61
|
+
columns: { type: "string" },
|
|
23
62
|
cache: { type: "string" },
|
|
24
63
|
"preview-rows": { type: "string" },
|
|
25
64
|
"max-cell-characters": { type: "string" },
|
|
@@ -54,7 +93,13 @@ if (values.version) {
|
|
|
54
93
|
process.exit(0);
|
|
55
94
|
}
|
|
56
95
|
if (values.help || !command || command === "help") {
|
|
57
|
-
|
|
96
|
+
const topic = command === "help" ? subcommand : command;
|
|
97
|
+
const usage = topic ? commandUsage(topic) : helpText();
|
|
98
|
+
if (usage === undefined) {
|
|
99
|
+
console.error(`Unknown command "${topic}". Run "stql help" to list commands.`);
|
|
100
|
+
process.exit(exitCodeFor("INVALID_COMMAND"));
|
|
101
|
+
}
|
|
102
|
+
console.log(usage);
|
|
58
103
|
process.exit(0);
|
|
59
104
|
}
|
|
60
105
|
const abortController = new AbortController();
|
|
@@ -76,6 +121,7 @@ const stateql = new StateQL({
|
|
|
76
121
|
...(values["max-cell-characters"] === undefined
|
|
77
122
|
? {}
|
|
78
123
|
: { maxCellCharacters: Number(values["max-cell-characters"]) }),
|
|
124
|
+
credentialResolver: cliCredentialResolver,
|
|
79
125
|
signal: abortController.signal,
|
|
80
126
|
});
|
|
81
127
|
try {
|
|
@@ -144,7 +190,7 @@ async function runBatch() {
|
|
|
144
190
|
}
|
|
145
191
|
async function dispatch() {
|
|
146
192
|
const params = parseParameters(values.params, values.param, values["params-file"]);
|
|
147
|
-
const sql = [subcommand, ...rest]
|
|
193
|
+
const sql = () => statementText([subcommand, ...rest]);
|
|
148
194
|
switch (command) {
|
|
149
195
|
case "connect": {
|
|
150
196
|
if (values["read-only"] && values["read-write"]) {
|
|
@@ -180,7 +226,7 @@ async function dispatch() {
|
|
|
180
226
|
case "redis":
|
|
181
227
|
return dispatchRedis(subcommand, rest);
|
|
182
228
|
case "query":
|
|
183
|
-
return stateql.query(sql, {
|
|
229
|
+
return stateql.query(sql(), {
|
|
184
230
|
params,
|
|
185
231
|
cache: cacheMode(values.cache),
|
|
186
232
|
...(values["preview-rows"] === undefined
|
|
@@ -190,7 +236,7 @@ async function dispatch() {
|
|
|
190
236
|
case "filter":
|
|
191
237
|
return stateql.filter(requireValue(subcommand, "result handle"), requireValue(rest.join(" ").trim(), "filter predicate"), { params });
|
|
192
238
|
case "exec":
|
|
193
|
-
return stateql.exec(sql, {
|
|
239
|
+
return stateql.exec(sql(), {
|
|
194
240
|
params,
|
|
195
241
|
replay: values.replay ?? false,
|
|
196
242
|
...(values["idempotency-key"]
|
|
@@ -205,13 +251,16 @@ async function dispatch() {
|
|
|
205
251
|
return stateql.rows(requireValue(subcommand, "result handle"), {
|
|
206
252
|
offset: numberOption(values.offset, 0),
|
|
207
253
|
limit: numberOption(values.limit, 20),
|
|
254
|
+
...(values.columns === undefined ? {} : { columns: columnList(values.columns) }),
|
|
208
255
|
});
|
|
209
256
|
case "count":
|
|
210
257
|
return stateql.count(requireValue(subcommand, "result handle"));
|
|
211
258
|
case "columns":
|
|
212
259
|
return stateql.columns(requireValue(subcommand, "result handle"));
|
|
260
|
+
case "summarize":
|
|
261
|
+
return stateql.summarize(requireValue(subcommand, "result handle"));
|
|
213
262
|
case "export":
|
|
214
|
-
return stateql.exportResult(requireValue(subcommand, "result handle"), requireValue(values.output, "--output"), exportFormat(values.format));
|
|
263
|
+
return stateql.exportResult(requireValue(subcommand, "result handle"), requireValue(values.output, "--output"), exportFormat(values.format), values.columns === undefined ? undefined : columnList(values.columns));
|
|
215
264
|
case "alias":
|
|
216
265
|
if (subcommand !== "set")
|
|
217
266
|
throw new Error("Expected: alias set NAME RESULT");
|
|
@@ -238,7 +287,7 @@ async function dispatch() {
|
|
|
238
287
|
case "transaction":
|
|
239
288
|
return dispatchTransaction(subcommand, rest[0]);
|
|
240
289
|
case "plan":
|
|
241
|
-
return stateql.plan(sql, {
|
|
290
|
+
return stateql.plan(sql(), {
|
|
242
291
|
params,
|
|
243
292
|
allowUnbounded: values["allow-unbounded"] ?? false,
|
|
244
293
|
...(values["allow-destructive"]
|
|
@@ -268,7 +317,7 @@ async function dispatch() {
|
|
|
268
317
|
}
|
|
269
318
|
}
|
|
270
319
|
async function dispatchMongo(action, args) {
|
|
271
|
-
const payload = requireValue(args
|
|
320
|
+
const payload = requireValue(statementText(args), "MongoDB EJSON command");
|
|
272
321
|
switch (action) {
|
|
273
322
|
case "query":
|
|
274
323
|
return stateql.mongoQuery(parseMongoCommand(payload), {
|
|
@@ -295,7 +344,7 @@ async function dispatchMongo(action, args) {
|
|
|
295
344
|
}
|
|
296
345
|
}
|
|
297
346
|
async function dispatchRedis(action, args) {
|
|
298
|
-
const payload = parseRedisCommand(requireValue(args
|
|
347
|
+
const payload = parseRedisCommand(requireValue(statementText(args), "Redis JSON command"));
|
|
299
348
|
switch (action) {
|
|
300
349
|
case "query": return stateql.redisQuery(payload, { cache: cacheMode(values.cache) });
|
|
301
350
|
case "exec": return stateql.redisExec(payload, { replay: values.replay ?? false, ...(values["idempotency-key"] ? { idempotencyKey: values["idempotency-key"] } : {}) });
|
|
@@ -350,30 +399,62 @@ async function dispatchSession(action, args) {
|
|
|
350
399
|
}
|
|
351
400
|
async function dispatchProfile(action, args) {
|
|
352
401
|
switch (action) {
|
|
353
|
-
case "add":
|
|
402
|
+
case "add": {
|
|
354
403
|
if (values["read-only"] && values["read-write"]) {
|
|
355
404
|
throw new Error("--read-only and --read-write are mutually exclusive.");
|
|
356
405
|
}
|
|
357
|
-
|
|
406
|
+
const name = requireValue(args[0], "profile name");
|
|
407
|
+
const passwordRef = values["ask-password"]
|
|
408
|
+
? await saveOsPassword(await askPassword(name, requireValue(args[1], "TARGET for --ask-password")))
|
|
409
|
+
: undefined;
|
|
410
|
+
const added = await stateql.addProfile(name, args[1], {
|
|
358
411
|
...(values.env ? { secretEnv: values.env } : {}),
|
|
359
412
|
...(values["credential-ref"] ? { credentialRef: values["credential-ref"] } : {}),
|
|
413
|
+
...(passwordRef ? { passwordRef } : {}),
|
|
360
414
|
readOnly: !values["read-write"],
|
|
361
415
|
});
|
|
362
|
-
|
|
416
|
+
if (!added.ok)
|
|
417
|
+
await deleteOsPassword(passwordRef);
|
|
418
|
+
return added;
|
|
419
|
+
}
|
|
420
|
+
case "update": {
|
|
363
421
|
if (values["read-only"] && values["read-write"])
|
|
364
422
|
throw new Error("--read-only and --read-write are mutually exclusive.");
|
|
365
|
-
|
|
423
|
+
const name = requireValue(args[0], "profile name");
|
|
424
|
+
const before = await stateql.showProfile(name);
|
|
425
|
+
if (!before.ok)
|
|
426
|
+
return before;
|
|
427
|
+
const target = args[1] ?? before.data.target;
|
|
428
|
+
const passwordRef = values["ask-password"]
|
|
429
|
+
? await saveOsPassword(await askPassword(name, requireValue(target ?? undefined, "TARGET for --ask-password")))
|
|
430
|
+
: undefined;
|
|
431
|
+
const updated = await stateql.updateProfile(name, {
|
|
366
432
|
...(args[1] !== undefined ? { target: args[1] } : {}),
|
|
367
433
|
...(values.env ? { secretEnv: values.env } : {}),
|
|
368
434
|
...(values["credential-ref"] ? { credentialRef: values["credential-ref"] } : {}),
|
|
435
|
+
...(passwordRef ? { passwordRef } : {}),
|
|
369
436
|
...(values["read-only"] ? { readOnly: true } : values["read-write"] ? { readOnly: false } : {}),
|
|
370
437
|
});
|
|
438
|
+
if (!updated.ok) {
|
|
439
|
+
await deleteOsPassword(passwordRef);
|
|
440
|
+
return updated;
|
|
441
|
+
}
|
|
442
|
+
if (updated.data.password_ref !== before.data.password_ref)
|
|
443
|
+
await deleteOsPassword(before.data.password_ref);
|
|
444
|
+
return updated;
|
|
445
|
+
}
|
|
371
446
|
case "list":
|
|
372
447
|
return stateql.listProfiles();
|
|
373
448
|
case "show":
|
|
374
449
|
return stateql.showProfile(requireValue(args[0], "profile name"));
|
|
375
|
-
case "remove":
|
|
376
|
-
|
|
450
|
+
case "remove": {
|
|
451
|
+
const name = requireValue(args[0], "profile name");
|
|
452
|
+
const before = await stateql.showProfile(name);
|
|
453
|
+
const removed = await stateql.removeProfile(name);
|
|
454
|
+
if (removed.ok && before.ok)
|
|
455
|
+
await deleteOsPassword(before.data.password_ref);
|
|
456
|
+
return removed;
|
|
457
|
+
}
|
|
377
458
|
default:
|
|
378
459
|
throw new Error(`Unknown profile command "${action ?? ""}".`);
|
|
379
460
|
}
|
|
@@ -418,6 +499,21 @@ function parseParameters(value, values, file) {
|
|
|
418
499
|
}
|
|
419
500
|
return parsedValue;
|
|
420
501
|
}
|
|
502
|
+
function statementText(args) {
|
|
503
|
+
const inline = args.filter(Boolean).join(" ").trim();
|
|
504
|
+
const file = values.file;
|
|
505
|
+
if (file === undefined)
|
|
506
|
+
return inline;
|
|
507
|
+
if (inline)
|
|
508
|
+
throw new Error("Use either inline text or --file, not both.");
|
|
509
|
+
if (file === "-" && values["params-file"] === "-") {
|
|
510
|
+
throw new Error("--file and --params-file cannot both read standard input.");
|
|
511
|
+
}
|
|
512
|
+
return withoutBom(readFileSync(file === "-" ? 0 : resolve(file), "utf8")).trim();
|
|
513
|
+
}
|
|
514
|
+
function columnList(value) {
|
|
515
|
+
return value.split(",").map((name) => name.trim()).filter(Boolean);
|
|
516
|
+
}
|
|
421
517
|
function parseParameter(value) {
|
|
422
518
|
try {
|
|
423
519
|
return JSON.parse(value);
|
|
@@ -571,34 +667,25 @@ function extractHandle(data) {
|
|
|
571
667
|
}
|
|
572
668
|
return undefined;
|
|
573
669
|
}
|
|
670
|
+
function commandUsage(name) {
|
|
671
|
+
const entries = USAGE.split(/\n(?=stql )/).filter((entry) => entry.slice("stql ".length).split(" ")[0].split("|").includes(name));
|
|
672
|
+
return entries.length > 0 ? entries.join("\n") : undefined;
|
|
673
|
+
}
|
|
574
674
|
function helpText() {
|
|
575
675
|
return `StateQL ${packageVersion()}
|
|
576
676
|
|
|
577
677
|
Usage: stql <command> [arguments] [options]
|
|
578
678
|
|
|
579
|
-
Commands:
|
|
580
|
-
|
|
581
|
-
disconnect, status
|
|
582
|
-
actor show | set-name NAME
|
|
583
|
-
profile add|update NAME [TARGET | --env ENV | --credential-ref REF]
|
|
584
|
-
profile list|show|remove
|
|
585
|
-
query, filter, exec, show, rows, count, columns, export
|
|
586
|
-
mongo query|exec|plan '<EJSON command>'
|
|
587
|
-
redis query|exec|plan '<JSON command>'
|
|
588
|
-
alias set
|
|
589
|
-
inspect schema|table|collection|collections|columns|indexes|constraints
|
|
590
|
-
objects [KIND] [--schema NAME] [--search TEXT] [--offset N|--cursor CURSOR]
|
|
591
|
-
object KIND NAME [IDENTITY] [--schema NAME]
|
|
592
|
-
transaction begin|status|commit|rollback
|
|
593
|
-
plan, apply, history [--category CATEGORY] [--internal|--external], receipt, doctor, purge, capabilities
|
|
594
|
-
batch [file.json|file.jsonl|-]
|
|
595
|
-
pipe
|
|
679
|
+
Commands (stql help COMMAND shows one):
|
|
680
|
+
${USAGE}
|
|
596
681
|
|
|
597
682
|
SQL parameters: --params JSON, repeated --param VALUE, or --params-file FILE.
|
|
683
|
+
Long SQL or native commands: --file FILE (- reads standard input) instead of inline text.
|
|
598
684
|
Query preview: --preview-rows N (default: 5, maximum: 200).
|
|
599
685
|
Long cells: --max-cell-characters N (default: 200); use export for full values.
|
|
600
686
|
Deadline: --timeout-ms N (default: 30000). Ctrl+C cancels database work.
|
|
601
|
-
|
|
687
|
+
Saved passwords: --ask-password opens a dialog and keeps the password in the OS credential store.
|
|
688
|
+
Other credential refs require a trusted host CredentialResolver; the standalone CLI cannot resolve them.
|
|
602
689
|
State: --max-state-bytes N, --cache-ttl-seconds N, --result-ttl-seconds N.
|
|
603
690
|
Output: --output agent|json|jsonl|text|silent (default: agent).
|
|
604
691
|
Agent rows: arrays in "columns" order (objects when shapes differ). next_offset only when more rows exist.
|
package/dist/src/index.d.ts
CHANGED
|
@@ -3,4 +3,4 @@ export { agentResponse } from "./agent-response.js";
|
|
|
3
3
|
export { CredentialResolutionError, StateQLError, exitCodeFor, } from "./errors.js";
|
|
4
4
|
export type { CredentialResolutionFailure } from "./errors.js";
|
|
5
5
|
export type { TableChange, TableIdentity, TableUpdate } from "./table-editor.js";
|
|
6
|
-
export type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, BatchCommandName, BatchOptions, CatalogObject, CatalogObjectKind, DescribeObjectData, ListObjectsData, ListObjectsFilter, CapabilitiesData, CommandExecutionContext, CommandOrigin, CloseSessionData, Column, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, CredentialAccess, CredentialOperation, CredentialRequest, CredentialSource, CredentialResolver, DisconnectData, DoctorData, Driver, ExecData, ExecOptions, ExecutionOptions, ExportData, Failure, FilterOptions, HistoryData, HistoryEntry, HistoryCategory, HistoryOptions, MongoAggregateOptions, MongoDocument, MongoFindOptions, MongoMutationOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, MongoWriteOutcome, OperationData, PlanData, PlanOptions, ProfileData, ProfileOptions, ProfileUpdateOptions, ProfilesData, PurgeData, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, RedisWriteOutcome, QueryOptions, RecentOperationData, RecentResultData, RemovedProfileData, Response, ResultData, RollbackTransactionData, Row, RowsData, RowsOptions, SqlParameters, SqlDriver, StateQLActorOptions, StateQLOptions, StateConfidence, StateQLSnapshot, StateQLSnapshotOptions, StateQLWorkspaceOptions, StatusConnectionData, StatusData, Success, SessionData, SessionListItem, SessionsData, SessionSummaryData, TransactionData, TransactionReferenceData, Warning, } from "./types.js";
|
|
6
|
+
export type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, BatchCommandName, BatchOptions, CatalogObject, CatalogObjectKind, DescribeObjectData, ListObjectsData, ListObjectsFilter, CapabilitiesData, CommandExecutionContext, CommandOrigin, CloseSessionData, Column, ColumnsData, ColumnSummary, CommitTransactionData, ConnectOptions, ConnectionData, CountData, CredentialAccess, CredentialOperation, CredentialRequest, CredentialSource, CredentialResolver, DisconnectData, DoctorData, Driver, ExecData, ExecOptions, ExecutionOptions, ExportData, Failure, FilterOptions, HistoryData, HistoryEntry, HistoryCategory, HistoryOptions, MongoAggregateOptions, MongoDocument, MongoFindOptions, MongoMutationOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, MongoWriteOutcome, OperationData, PlanData, PlanOptions, ProfileData, ProfileOptions, ProfileUpdateOptions, ProfilesData, PurgeData, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, RedisWriteOutcome, QueryOptions, RecentOperationData, RecentResultData, RemovedProfileData, Response, ResultData, RollbackTransactionData, Row, RowsData, RowsOptions, SqlParameters, SqlDriver, StateQLActorOptions, StateQLOptions, StateConfidence, StateQLSnapshot, StateQLSnapshotOptions, StateQLWorkspaceOptions, StatusConnectionData, StatusData, SummaryData, Success, SessionData, SessionListItem, SessionsData, SessionSummaryData, TransactionData, TransactionReferenceData, Warning, } from "./types.js";
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import type { CredentialRequest } from "./types.js";
|
|
2
|
+
export declare function isOsPasswordRef(reference: string | null | undefined): reference is string;
|
|
3
|
+
export declare function cliCredentialResolver(request: CredentialRequest): Promise<string | undefined>;
|
|
4
|
+
export declare function saveOsPassword(password: string): Promise<string>;
|
|
5
|
+
export declare function deleteOsPassword(reference: string | null | undefined): Promise<void>;
|
|
6
|
+
export declare function askPassword(profile: string, target: string): Promise<string>;
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
import { execFile } from "node:child_process";
|
|
2
|
+
import { randomUUID } from "node:crypto";
|
|
3
|
+
import { env, platform } from "node:process";
|
|
4
|
+
import { promisify } from "node:util";
|
|
5
|
+
const SERVICE = "stql";
|
|
6
|
+
const PREFIX = "os:";
|
|
7
|
+
const run = promisify(execFile);
|
|
8
|
+
export function isOsPasswordRef(reference) {
|
|
9
|
+
return reference?.startsWith(PREFIX) ?? false;
|
|
10
|
+
}
|
|
11
|
+
export async function cliCredentialResolver(request) {
|
|
12
|
+
if (request.source === "credential_ref")
|
|
13
|
+
return undefined;
|
|
14
|
+
if (request.source !== "password_ref")
|
|
15
|
+
return env[request.reference];
|
|
16
|
+
if (!isOsPasswordRef(request.reference))
|
|
17
|
+
return undefined;
|
|
18
|
+
return (await osEntry(request.reference)).getPassword() ?? undefined;
|
|
19
|
+
}
|
|
20
|
+
export async function saveOsPassword(password) {
|
|
21
|
+
const reference = `${PREFIX}${randomUUID()}`;
|
|
22
|
+
(await osEntry(reference)).setPassword(password);
|
|
23
|
+
return reference;
|
|
24
|
+
}
|
|
25
|
+
export async function deleteOsPassword(reference) {
|
|
26
|
+
if (!isOsPasswordRef(reference))
|
|
27
|
+
return;
|
|
28
|
+
(await osEntry(reference)).deletePassword();
|
|
29
|
+
}
|
|
30
|
+
async function osEntry(reference) {
|
|
31
|
+
const { Entry } = await import("@napi-rs/keyring");
|
|
32
|
+
return new Entry(SERVICE, reference.slice(PREFIX.length));
|
|
33
|
+
}
|
|
34
|
+
export async function askPassword(profile, target) {
|
|
35
|
+
const url = new URL(target);
|
|
36
|
+
const user = decodeURIComponent(url.username);
|
|
37
|
+
const message = `Password for ${user ? `${user}@` : ""}${url.host} (StateQL profile "${profile}")`;
|
|
38
|
+
let output;
|
|
39
|
+
try {
|
|
40
|
+
output = await passwordDialog(message);
|
|
41
|
+
}
|
|
42
|
+
catch (error) {
|
|
43
|
+
if (isMissingCommand(error)) {
|
|
44
|
+
throw new Error("--ask-password needs a password dialog: zenity on Linux, osascript on macOS.");
|
|
45
|
+
}
|
|
46
|
+
throw new Error("Password entry was cancelled.");
|
|
47
|
+
}
|
|
48
|
+
const password = platform === "win32" ? output : output.replace(/\r?\n$/, "");
|
|
49
|
+
if (password === "")
|
|
50
|
+
throw new Error("No password was entered.");
|
|
51
|
+
return password;
|
|
52
|
+
}
|
|
53
|
+
async function passwordDialog(message) {
|
|
54
|
+
if (platform === "win32") {
|
|
55
|
+
// Get-Credential opens behind the active window; a TopMost form stays visible.
|
|
56
|
+
// windowsHide makes the first ShowWindow hide the form, so show it again explicitly.
|
|
57
|
+
const script = [
|
|
58
|
+
"$ErrorActionPreference = 'Stop'",
|
|
59
|
+
"[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding $false",
|
|
60
|
+
"Add-Type -AssemblyName System.Windows.Forms",
|
|
61
|
+
"Add-Type -Namespace StateQL -Name Win32 -MemberDefinition '[DllImport(\"user32.dll\")] public static extern bool ShowWindow(IntPtr window, int command);'",
|
|
62
|
+
"[Windows.Forms.Application]::EnableVisualStyles()",
|
|
63
|
+
"$form = New-Object Windows.Forms.Form -Property @{ Text = 'StateQL'; TopMost = $true; StartPosition = 'CenterScreen'; FormBorderStyle = 'FixedDialog'; MaximizeBox = $false; MinimizeBox = $false; AutoSize = $true; AutoSizeMode = 'GrowAndShrink'; Padding = 12 }",
|
|
64
|
+
"$layout = New-Object Windows.Forms.FlowLayoutPanel -Property @{ FlowDirection = 'TopDown'; AutoSize = $true }",
|
|
65
|
+
"$label = New-Object Windows.Forms.Label -Property @{ Text = $env:STQL_PROMPT_MESSAGE; AutoSize = $true; MaximumSize = '360,0' }",
|
|
66
|
+
"$box = New-Object Windows.Forms.TextBox -Property @{ UseSystemPasswordChar = $true; Width = 360 }",
|
|
67
|
+
"$buttons = New-Object Windows.Forms.FlowLayoutPanel -Property @{ FlowDirection = 'RightToLeft'; Width = 366; Height = 34 }",
|
|
68
|
+
"$cancel = New-Object Windows.Forms.Button -Property @{ Text = 'Cancel'; DialogResult = 'Cancel' }",
|
|
69
|
+
"$ok = New-Object Windows.Forms.Button -Property @{ Text = 'OK'; DialogResult = 'OK' }",
|
|
70
|
+
"$buttons.Controls.AddRange(@($cancel, $ok))",
|
|
71
|
+
"$layout.Controls.AddRange(@($label, $box, $buttons))",
|
|
72
|
+
"$form.Controls.Add($layout)",
|
|
73
|
+
"$form.AcceptButton = $ok",
|
|
74
|
+
"$form.CancelButton = $cancel",
|
|
75
|
+
"$form.Add_Shown({ [void][StateQL.Win32]::ShowWindow($form.Handle, 5); $form.Activate(); [void]$box.Focus() })",
|
|
76
|
+
"if ($form.ShowDialog() -ne 'OK') { exit 1 }",
|
|
77
|
+
"[Console]::Out.Write($box.Text)",
|
|
78
|
+
].join("\n");
|
|
79
|
+
const { stdout } = await run("powershell.exe", ["-NoProfile", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], { env: { ...env, STQL_PROMPT_MESSAGE: message }, windowsHide: true });
|
|
80
|
+
return stdout;
|
|
81
|
+
}
|
|
82
|
+
if (platform === "darwin") {
|
|
83
|
+
const { stdout } = await run("osascript", [
|
|
84
|
+
"-e", "on run argv",
|
|
85
|
+
"-e", 'text returned of (display dialog (item 1 of argv) default answer "" with hidden answer with title "StateQL")',
|
|
86
|
+
"-e", "end run",
|
|
87
|
+
message,
|
|
88
|
+
]);
|
|
89
|
+
return stdout;
|
|
90
|
+
}
|
|
91
|
+
const { stdout } = await run("zenity", ["--password", "--title", message]);
|
|
92
|
+
return stdout;
|
|
93
|
+
}
|
|
94
|
+
function isMissingCommand(error) {
|
|
95
|
+
return error.code === "ENOENT";
|
|
96
|
+
}
|
package/dist/src/sql.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { AST } from "node-sql-parser";
|
|
2
|
-
import type { Driver, SqlDriver } from "./types.js";
|
|
2
|
+
import type { Driver, SqlDriver, SqlParameters } from "./types.js";
|
|
3
3
|
export type StatementType = "select" | "insert" | "upsert" | "replace" | "update" | "delete" | "create" | "alter" | "drop" | "truncate" | "values" | "show" | "explain" | "vacuum" | "analyze" | "reindex" | "optimize" | "check" | "cluster";
|
|
4
4
|
export interface SqlAnalysis {
|
|
5
5
|
ast: AST;
|
|
@@ -18,3 +18,9 @@ export interface SqlAnalysis {
|
|
|
18
18
|
export declare function analyzeSql(sql: string, driver: SqlDriver): SqlAnalysis;
|
|
19
19
|
/** @internal Compatibility for existing connection records during Mongo rollout. */
|
|
20
20
|
export declare function analyzeSql(sql: string, driver: Driver): SqlAnalysis;
|
|
21
|
+
export interface CountStatement {
|
|
22
|
+
sql: string;
|
|
23
|
+
params: unknown[];
|
|
24
|
+
}
|
|
25
|
+
/** A COUNT(*) of the rows a single-table UPDATE or DELETE matches, or undefined when it cannot be derived safely. */
|
|
26
|
+
export declare function matchedRowsCount(analysis: SqlAnalysis, params: SqlParameters, driver: SqlDriver): CountStatement | undefined;
|
package/dist/src/sql.js
CHANGED
|
@@ -50,13 +50,93 @@ export function analyzeSql(sql, driver) {
|
|
|
50
50
|
throw new StateQLError("INVALID_SQL", message);
|
|
51
51
|
}
|
|
52
52
|
}
|
|
53
|
+
function parserDatabase(driver) {
|
|
54
|
+
if (driver === "postgres")
|
|
55
|
+
return "Postgresql";
|
|
56
|
+
if (driver === "mysql")
|
|
57
|
+
return "MySQL";
|
|
58
|
+
return "Sqlite";
|
|
59
|
+
}
|
|
60
|
+
/** A COUNT(*) of the rows a single-table UPDATE or DELETE matches, or undefined when it cannot be derived safely. */
|
|
61
|
+
export function matchedRowsCount(analysis, params, driver) {
|
|
62
|
+
const ast = analysis.ast;
|
|
63
|
+
const isUpdate = analysis.statementType === "update";
|
|
64
|
+
const isDelete = analysis.statementType === "delete";
|
|
65
|
+
if (!isUpdate && !isDelete)
|
|
66
|
+
return undefined;
|
|
67
|
+
const tables = isUpdate ? ast.table : ast.from;
|
|
68
|
+
const singleTable = Array.isArray(tables) && tables.length === 1 && !record(tables[0])?.join;
|
|
69
|
+
const limit = record(ast.limit)?.value;
|
|
70
|
+
const hasLimit = Array.isArray(limit) && limit.length > 0;
|
|
71
|
+
if (!Array.isArray(params) || !singleTable)
|
|
72
|
+
return undefined;
|
|
73
|
+
if (ast.with || ast.orderby || hasLimit || (isUpdate && ast.from))
|
|
74
|
+
return undefined;
|
|
75
|
+
// The parser drops NULLS FIRST/LAST, which can change a subquery that also has a LIMIT.
|
|
76
|
+
if (/\bnulls\s+(?:first|last)\b/i.test(analysis.normalized))
|
|
77
|
+
return undefined;
|
|
78
|
+
const where = structuredClone(ast.where ?? null);
|
|
79
|
+
const setPlaceholders = placeholders(ast.set);
|
|
80
|
+
const wherePlaceholders = placeholders(where);
|
|
81
|
+
const placeholderCount = setPlaceholders.length + wherePlaceholders.length;
|
|
82
|
+
if (placeholders(ast).length !== placeholderCount)
|
|
83
|
+
return undefined;
|
|
84
|
+
let countParams;
|
|
85
|
+
if ([...setPlaceholders, ...wherePlaceholders].every(isQuestionMark)) {
|
|
86
|
+
if (params.length !== placeholderCount)
|
|
87
|
+
return undefined;
|
|
88
|
+
countParams = params.slice(setPlaceholders.length);
|
|
89
|
+
}
|
|
90
|
+
else if (driver === "postgres" && wherePlaceholders.every(isNumberedVar)) {
|
|
91
|
+
const renumbered = new Map();
|
|
92
|
+
for (const node of wherePlaceholders) {
|
|
93
|
+
const number = node.name;
|
|
94
|
+
if (!renumbered.has(number))
|
|
95
|
+
renumbered.set(number, renumbered.size + 1);
|
|
96
|
+
node.name = renumbered.get(number);
|
|
97
|
+
}
|
|
98
|
+
countParams = [...renumbered.keys()].map((number) => params[number - 1]);
|
|
99
|
+
}
|
|
100
|
+
else {
|
|
101
|
+
return undefined;
|
|
102
|
+
}
|
|
103
|
+
const select = {
|
|
104
|
+
type: "select",
|
|
105
|
+
columns: [{ expr: { type: "aggr_func", name: "COUNT", args: { expr: { type: "star", value: "*" } } }, as: null }],
|
|
106
|
+
from: tables,
|
|
107
|
+
where,
|
|
108
|
+
};
|
|
109
|
+
return {
|
|
110
|
+
sql: sqlParser().sqlify(select, { database: parserDatabase(driver) }),
|
|
111
|
+
params: countParams,
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
function placeholders(node, found = []) {
|
|
115
|
+
if (Array.isArray(node)) {
|
|
116
|
+
for (const item of node)
|
|
117
|
+
placeholders(item, found);
|
|
118
|
+
return found;
|
|
119
|
+
}
|
|
120
|
+
const value = record(node);
|
|
121
|
+
if (!value)
|
|
122
|
+
return found;
|
|
123
|
+
if (value.type === "var" || isQuestionMark(value)) {
|
|
124
|
+
found.push(value);
|
|
125
|
+
return found;
|
|
126
|
+
}
|
|
127
|
+
for (const child of Object.values(value))
|
|
128
|
+
placeholders(child, found);
|
|
129
|
+
return found;
|
|
130
|
+
}
|
|
131
|
+
function isQuestionMark(node) {
|
|
132
|
+
return node.type === "origin" && node.value === "?";
|
|
133
|
+
}
|
|
134
|
+
function isNumberedVar(node) {
|
|
135
|
+
return node.type === "var" && node.prefix === "$" && Number.isInteger(node.name);
|
|
136
|
+
}
|
|
53
137
|
function parseSqlStatement(sql, driver) {
|
|
54
138
|
const parser = sqlParser();
|
|
55
|
-
const database = driver
|
|
56
|
-
? "Postgresql"
|
|
57
|
-
: driver === "mysql"
|
|
58
|
-
? "MySQL"
|
|
59
|
-
: "Sqlite";
|
|
139
|
+
const database = parserDatabase(driver);
|
|
60
140
|
const parserSql = driver === "postgres" ? postgresParserSql(sql) : sql;
|
|
61
141
|
let parsed;
|
|
62
142
|
try {
|
|
@@ -699,10 +779,10 @@ class UtilityParser {
|
|
|
699
779
|
if (this.done())
|
|
700
780
|
return;
|
|
701
781
|
while (true) {
|
|
702
|
-
|
|
703
|
-
this.consumeWord("ONLY");
|
|
782
|
+
const only = allowOnlyAndStar && this.consumeWord("ONLY");
|
|
704
783
|
this.qualifiedIdentifier();
|
|
705
|
-
|
|
784
|
+
// PostgreSQL accepts ONLY name or name *, never both.
|
|
785
|
+
if (allowOnlyAndStar && !only)
|
|
706
786
|
this.consumePunctuation("*");
|
|
707
787
|
if (this.consumePunctuation("(")) {
|
|
708
788
|
this.identifier();
|
package/dist/src/stateql.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { type TableChange } from "./table-editor.js";
|
|
2
|
-
import type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, CommandExecutionContext, CommandOrigin, BatchOptions, CapabilitiesData, CatalogObject, DescribeObjectData, ListObjectsData, ListObjectsFilter, CloseSessionData, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, DisconnectData, DoctorData, ExecData, ExecOptions, ExecutionOptions, ExportData, FilterOptions, HistoryData, HistoryOptions, OperationData, PlanData, PlanOptions, ProfileData, ProfilesData, ProfileOptions, ProfileUpdateOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, PurgeData, QueryOptions, RemovedProfileData, Response, ResultData, RollbackTransactionData, RowsData, RowsOptions, Column, StateQLActorOptions, StateQLOptions, StateQLWorkspaceOptions, StateQLSnapshot, StateQLSnapshotOptions, StatusData, SessionData, SessionsData, SessionSummaryData, TransactionData } from "./types.js";
|
|
2
|
+
import type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, CommandExecutionContext, CommandOrigin, BatchOptions, CapabilitiesData, CatalogObject, DescribeObjectData, ListObjectsData, ListObjectsFilter, CloseSessionData, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, DisconnectData, DoctorData, ExecData, ExecOptions, ExecutionOptions, ExportData, FilterOptions, HistoryData, HistoryOptions, OperationData, PlanData, PlanOptions, ProfileData, ProfilesData, ProfileOptions, ProfileUpdateOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, PurgeData, QueryOptions, RemovedProfileData, Response, ResultData, RollbackTransactionData, RowsData, RowsOptions, Column, SummaryData, StateQLActorOptions, StateQLOptions, StateQLWorkspaceOptions, StateQLSnapshot, StateQLSnapshotOptions, StatusData, SessionData, SessionsData, SessionSummaryData, TransactionData } from "./types.js";
|
|
3
3
|
export declare class StateQL {
|
|
4
4
|
/** Runtime contract marker for passwordRef/password_ref support. */
|
|
5
5
|
static readonly passwordReferenceVersion: 1;
|
|
@@ -56,6 +56,7 @@ export declare class StateQL {
|
|
|
56
56
|
rows(idOrAlias: string, options?: RowsOptions): Promise<Response<RowsData>>;
|
|
57
57
|
count(idOrAlias: string): Promise<Response<CountData>>;
|
|
58
58
|
columns(idOrAlias: string): Promise<Response<ColumnsData>>;
|
|
59
|
+
summarize(idOrAlias: string): Promise<Response<SummaryData>>;
|
|
59
60
|
setAlias(name: string, id: string): Promise<Response<AliasData>>;
|
|
60
61
|
/** Owned, full-value pages for host UIs. Reading a page does not add a command to history. */
|
|
61
62
|
readMaterialized(id: string, options?: RowsOptions & {
|
|
@@ -97,7 +98,7 @@ export declare class StateQL {
|
|
|
97
98
|
private editableMetadata;
|
|
98
99
|
private panelResult;
|
|
99
100
|
private fullResultRows;
|
|
100
|
-
exportResult(idOrAlias: string, output: string, format?: "json" | "jsonl" | "csv"): Promise<Response<ExportData>>;
|
|
101
|
+
exportResult(idOrAlias: string, output: string, format?: "json" | "jsonl" | "csv", columns?: string[]): Promise<Response<ExportData>>;
|
|
101
102
|
exec(sql: string, options?: ExecOptions): Promise<Response<ExecData>>;
|
|
102
103
|
mongoExec(command: MongoWriteCommand, options?: MongoExecOptions): Promise<Response<ExecData>>;
|
|
103
104
|
redisExec(command: RedisCommand, options?: RedisExecOptions): Promise<Response<ExecData>>;
|
package/dist/src/stateql.js
CHANGED
|
@@ -11,9 +11,9 @@ import { analyzeMongoWriteSafety, deserializeMongoWriteCommand, serializeMongoCo
|
|
|
11
11
|
import { deserializeRedisCommand, RedisAdapter, serializeRedisCommand, validateRedisReadCommand, validateRedisWriteCommand, } from "./redis.js";
|
|
12
12
|
import { filterMaterializedRows, prepareFilterStatement, validateFilterParameters, } from "./filter.js";
|
|
13
13
|
import { operationData, paginationWarnings, profileData, rowsToCsv, sessionData, transactionData, } from "./response-data.js";
|
|
14
|
-
import { analyzeSql } from "./sql.js";
|
|
14
|
+
import { analyzeSql, matchedRowsCount } from "./sql.js";
|
|
15
15
|
import { StateStore, } from "./store.js";
|
|
16
|
-
import { compactRows, defaultHome, hash, isSqlParameters, parseJson, redact, } from "./util.js";
|
|
16
|
+
import { compactRows, compactValue, defaultHome, hash, isSqlParameters, parseJson, redact, } from "./util.js";
|
|
17
17
|
const DEFAULT_SNAPSHOT_HISTORY_LIMIT = 50;
|
|
18
18
|
const MAX_SNAPSHOT_HISTORY_LIMIT = 100;
|
|
19
19
|
const DEFAULT_CREDENTIAL_RESOLUTION_TIMEOUT_MS = 120_000;
|
|
@@ -1019,7 +1019,7 @@ export class StateQL {
|
|
|
1019
1019
|
throw new StateQLError("OUTPUT_LIMIT_EXCEEDED", "limit cannot exceed 1000 rows.", { suggestedAction: "Fetch another page or use export." });
|
|
1020
1020
|
}
|
|
1021
1021
|
const allRows = this.store.resultRows(result);
|
|
1022
|
-
const rows = allRows.slice(offset, offset + limit);
|
|
1022
|
+
const rows = selectColumns(allRows.slice(offset, offset + limit), this.store.resultColumns(result), options.columns);
|
|
1023
1023
|
return {
|
|
1024
1024
|
data: {
|
|
1025
1025
|
result_id: result.id,
|
|
@@ -1059,6 +1059,22 @@ export class StateQL {
|
|
|
1059
1059
|
confidence: result.state_confidence,
|
|
1060
1060
|
}));
|
|
1061
1061
|
}
|
|
1062
|
+
async summarize(idOrAlias) {
|
|
1063
|
+
return this.withResult("summarize", idOrAlias, async (result) => {
|
|
1064
|
+
const rows = this.store.resultRows(result);
|
|
1065
|
+
return {
|
|
1066
|
+
data: {
|
|
1067
|
+
result_id: result.id,
|
|
1068
|
+
total: result.row_count,
|
|
1069
|
+
columns: this.store.resultColumns(result).map((column) => summarizeColumn(column.name, rows, this.maxCellCharacters)),
|
|
1070
|
+
},
|
|
1071
|
+
handle: result.id,
|
|
1072
|
+
cached: true,
|
|
1073
|
+
stateVersion: result.state_version,
|
|
1074
|
+
confidence: result.state_confidence,
|
|
1075
|
+
};
|
|
1076
|
+
});
|
|
1077
|
+
}
|
|
1062
1078
|
async setAlias(name, id) {
|
|
1063
1079
|
return this.run("alias.set", async (session) => {
|
|
1064
1080
|
const result = this.requireResult(id, session);
|
|
@@ -1321,14 +1337,15 @@ export class StateQL {
|
|
|
1321
1337
|
this.panelRows = { id: result.id, json: result.rows_json, rows: this.store.resultRows(result) };
|
|
1322
1338
|
return this.panelRows.rows;
|
|
1323
1339
|
}
|
|
1324
|
-
async exportResult(idOrAlias, output, format = "csv") {
|
|
1340
|
+
async exportResult(idOrAlias, output, format = "csv", columns) {
|
|
1325
1341
|
return this.withResult("export", idOrAlias, async (result) => {
|
|
1326
|
-
const
|
|
1342
|
+
const resultColumns = this.store.resultColumns(result);
|
|
1343
|
+
const rows = selectColumns(this.store.resultRows(result), resultColumns, columns);
|
|
1327
1344
|
const content = format === "json"
|
|
1328
1345
|
? `${JSON.stringify(rows, null, 2)}\n`
|
|
1329
1346
|
: format === "jsonl"
|
|
1330
1347
|
? `${rows.map((row) => JSON.stringify(row)).join("\n")}\n`
|
|
1331
|
-
: rowsToCsv(rows,
|
|
1348
|
+
: rowsToCsv(rows, columns ?? resultColumns.map((column) => column.name));
|
|
1332
1349
|
writeFileSync(resolve(output), content, "utf8");
|
|
1333
1350
|
return {
|
|
1334
1351
|
data: {
|
|
@@ -1648,6 +1665,7 @@ export class StateQL {
|
|
|
1648
1665
|
const adapter = await this.openAdapter(connection, context, adapterSource);
|
|
1649
1666
|
try {
|
|
1650
1667
|
const stateSignature = await adapter.signature();
|
|
1668
|
+
const estimatedRows = await countMatchedRows(adapter, matchedRowsCount(analysis, options.params ?? [], connection.driver));
|
|
1651
1669
|
const expiresAt = new Date(this.now().getTime() + 10 * 60_000).toISOString();
|
|
1652
1670
|
const plan = this.store.savePlan({
|
|
1653
1671
|
sessionId: session.id,
|
|
@@ -1681,6 +1699,7 @@ export class StateQL {
|
|
|
1681
1699
|
state_version: plan.state_version,
|
|
1682
1700
|
owner_actor_id: plan.owner_actor_id,
|
|
1683
1701
|
expires_at: plan.expires_at,
|
|
1702
|
+
...(estimatedRows === undefined ? {} : { estimated_rows: estimatedRows }),
|
|
1684
1703
|
},
|
|
1685
1704
|
handle: plan.id,
|
|
1686
1705
|
executed: true,
|
|
@@ -1985,6 +2004,9 @@ export class StateQL {
|
|
|
1985
2004
|
multi_row_table_plans: true,
|
|
1986
2005
|
history_classification: true,
|
|
1987
2006
|
actor_display_names: true,
|
|
2007
|
+
result_projection: true,
|
|
2008
|
+
result_summary: true,
|
|
2009
|
+
plan_row_estimates: true,
|
|
1988
2010
|
},
|
|
1989
2011
|
driver_features: {
|
|
1990
2012
|
mongodb: {
|
|
@@ -2155,11 +2177,14 @@ export class StateQL {
|
|
|
2155
2177
|
return this.rows(batchString(command.handle, "handle"), {
|
|
2156
2178
|
offset: command.offset ?? 0,
|
|
2157
2179
|
limit: command.limit ?? 20,
|
|
2180
|
+
...(command.columns ? { columns: command.columns } : {}),
|
|
2158
2181
|
});
|
|
2159
2182
|
case "count":
|
|
2160
2183
|
return this.count(batchString(command.handle, "handle"));
|
|
2161
2184
|
case "columns":
|
|
2162
2185
|
return this.columns(batchString(command.handle, "handle"));
|
|
2186
|
+
case "summarize":
|
|
2187
|
+
return this.summarize(batchString(command.handle, "handle"));
|
|
2163
2188
|
case "alias.set":
|
|
2164
2189
|
return this.setAlias(batchString(command.name, "name"), batchString(command.handle, "handle"));
|
|
2165
2190
|
case "inspect":
|
|
@@ -3372,6 +3397,67 @@ function positiveInteger(value, name) {
|
|
|
3372
3397
|
return value;
|
|
3373
3398
|
throw new StateQLError("INVALID_COMMAND", `${name} must be a positive integer.`);
|
|
3374
3399
|
}
|
|
3400
|
+
function selectColumns(rows, available, selected) {
|
|
3401
|
+
if (!selected)
|
|
3402
|
+
return rows;
|
|
3403
|
+
const names = available.map((column) => column.name);
|
|
3404
|
+
const unknown = selected.filter((name) => !names.includes(name));
|
|
3405
|
+
if (selected.length === 0 || unknown.length > 0) {
|
|
3406
|
+
throw new StateQLError("INVALID_COMMAND", unknown.length > 0 ? `Unknown column: ${unknown.join(", ")}.` : "columns cannot be empty.", { suggestedAction: `Use one or more of: ${names.join(", ")}.` });
|
|
3407
|
+
}
|
|
3408
|
+
// Keep missing keys missing, so MongoDB documents still distinguish missing from null.
|
|
3409
|
+
return rows.map((row) => Object.fromEntries(selected.filter((name) => name in row).map((name) => [name, row[name]])));
|
|
3410
|
+
}
|
|
3411
|
+
function summarizeColumn(name, rows, maxCellCharacters) {
|
|
3412
|
+
const values = rows
|
|
3413
|
+
.map((row) => row[name])
|
|
3414
|
+
.filter((value) => value !== null && value !== undefined);
|
|
3415
|
+
const [min, max] = valueRange(values);
|
|
3416
|
+
return {
|
|
3417
|
+
name,
|
|
3418
|
+
nulls: rows.length - values.length,
|
|
3419
|
+
distinct: new Set(values.map((value) => JSON.stringify(value))).size,
|
|
3420
|
+
min: compactValue(min, maxCellCharacters),
|
|
3421
|
+
max: compactValue(max, maxCellCharacters),
|
|
3422
|
+
};
|
|
3423
|
+
}
|
|
3424
|
+
const NUMERIC_TEXT = /^-?\d+(?:\.\d+)?$/;
|
|
3425
|
+
// Exact numerics (PostgreSQL numeric/bigint, MySQL DECIMAL) arrive as strings, so compare them as numbers.
|
|
3426
|
+
function valueRange(values) {
|
|
3427
|
+
const numeric = values.every((value) => typeof value === "number" || (typeof value === "string" && NUMERIC_TEXT.test(value)));
|
|
3428
|
+
const text = values.every((value) => typeof value === "string");
|
|
3429
|
+
if (values.length === 0)
|
|
3430
|
+
return [null, null];
|
|
3431
|
+
if (!numeric && !text)
|
|
3432
|
+
return [null, null];
|
|
3433
|
+
const compare = numeric
|
|
3434
|
+
? (left, right) => Number(left) - Number(right)
|
|
3435
|
+
: (left, right) => (String(left) < String(right) ? -1 : String(left) > String(right) ? 1 : 0);
|
|
3436
|
+
let min = values[0];
|
|
3437
|
+
let max = values[0];
|
|
3438
|
+
for (const value of values) {
|
|
3439
|
+
if (compare(value, min) < 0)
|
|
3440
|
+
min = value;
|
|
3441
|
+
if (compare(value, max) > 0)
|
|
3442
|
+
max = value;
|
|
3443
|
+
}
|
|
3444
|
+
return [min, max];
|
|
3445
|
+
}
|
|
3446
|
+
async function countMatchedRows(adapter, count) {
|
|
3447
|
+
if (!count)
|
|
3448
|
+
return undefined;
|
|
3449
|
+
try {
|
|
3450
|
+
const { rows } = await adapter.read(count.sql, count.params);
|
|
3451
|
+
const value = Number(Object.values(rows[0] ?? {})[0]);
|
|
3452
|
+
return Number.isSafeInteger(value) ? value : undefined;
|
|
3453
|
+
}
|
|
3454
|
+
catch (error) {
|
|
3455
|
+
if (error instanceof AdapterExecutionError)
|
|
3456
|
+
throw error;
|
|
3457
|
+
// The estimate is advisory; a count the parser cannot express must not block the plan.
|
|
3458
|
+
return undefined;
|
|
3459
|
+
}
|
|
3460
|
+
}
|
|
3375
3461
|
async function closeAdapterQuietly(adapter) {
|
|
3376
3462
|
try {
|
|
3377
3463
|
await adapter.close();
|
package/dist/src/types.d.ts
CHANGED
|
@@ -337,6 +337,7 @@ export interface RedisPlanOptions extends ExecutionOptions {
|
|
|
337
337
|
export interface RowsOptions {
|
|
338
338
|
offset?: number;
|
|
339
339
|
limit?: number;
|
|
340
|
+
columns?: string[];
|
|
340
341
|
}
|
|
341
342
|
export interface PlanOptions extends ExecutionOptions {
|
|
342
343
|
params?: SqlParameters;
|
|
@@ -347,7 +348,7 @@ export interface MongoPlanOptions extends ExecutionOptions {
|
|
|
347
348
|
allowUnbounded?: boolean;
|
|
348
349
|
allowDestructive?: boolean;
|
|
349
350
|
}
|
|
350
|
-
export type BatchCommandName = "connect" | "disconnect" | "status" | "actor.show" | "actor.set-name" | "profile.add" | "profile.list" | "profile.show" | "profile.remove" | "profile.update" | "session.start" | "session.list" | "session.show" | "session.summary" | "session.close" | "query" | "filter" | "exec" | "show" | "rows" | "count" | "columns" | "alias.set" | "inspect" | "transaction.begin" | "transaction.status" | "transaction.commit" | "transaction.rollback" | "plan" | "mongo.query" | "mongo.exec" | "mongo.plan" | "redis.query" | "redis.exec" | "redis.plan" | "objects.list" | "object.describe" | "apply" | "history" | "receipt" | "doctor" | "purge" | "capabilities";
|
|
351
|
+
export type BatchCommandName = "connect" | "disconnect" | "status" | "actor.show" | "actor.set-name" | "profile.add" | "profile.list" | "profile.show" | "profile.remove" | "profile.update" | "session.start" | "session.list" | "session.show" | "session.summary" | "session.close" | "query" | "filter" | "exec" | "show" | "rows" | "count" | "columns" | "summarize" | "alias.set" | "inspect" | "transaction.begin" | "transaction.status" | "transaction.commit" | "transaction.rollback" | "plan" | "mongo.query" | "mongo.exec" | "mongo.plan" | "redis.query" | "redis.exec" | "redis.plan" | "objects.list" | "object.describe" | "apply" | "history" | "receipt" | "doctor" | "purge" | "capabilities";
|
|
351
352
|
export interface BatchCommand {
|
|
352
353
|
command: BatchCommandName;
|
|
353
354
|
target?: string;
|
|
@@ -364,6 +365,7 @@ export interface BatchCommand {
|
|
|
364
365
|
object?: CatalogObject;
|
|
365
366
|
cache?: "auto" | "bypass" | "require";
|
|
366
367
|
preview_rows?: number;
|
|
368
|
+
columns?: string[];
|
|
367
369
|
read_only?: boolean;
|
|
368
370
|
secret_env?: string;
|
|
369
371
|
credential_ref?: string;
|
|
@@ -542,6 +544,18 @@ export interface ColumnsData {
|
|
|
542
544
|
result_id: string;
|
|
543
545
|
columns: Column[];
|
|
544
546
|
}
|
|
547
|
+
export interface ColumnSummary {
|
|
548
|
+
name: string;
|
|
549
|
+
nulls: number;
|
|
550
|
+
distinct: number;
|
|
551
|
+
min: unknown;
|
|
552
|
+
max: unknown;
|
|
553
|
+
}
|
|
554
|
+
export interface SummaryData {
|
|
555
|
+
result_id: string;
|
|
556
|
+
total: number;
|
|
557
|
+
columns: ColumnSummary[];
|
|
558
|
+
}
|
|
545
559
|
export interface AliasData {
|
|
546
560
|
alias: string;
|
|
547
561
|
result_id: string;
|
|
@@ -603,6 +617,8 @@ export interface PlanData {
|
|
|
603
617
|
state_version: string;
|
|
604
618
|
owner_actor_id: string;
|
|
605
619
|
expires_at: string;
|
|
620
|
+
/** Rows a single-table UPDATE or DELETE matched at plan time; absent when not derivable. */
|
|
621
|
+
estimated_rows?: number;
|
|
606
622
|
}
|
|
607
623
|
export interface ApplyData extends ExecData {
|
|
608
624
|
plan_id: string;
|
package/dist/src/util.d.ts
CHANGED
|
@@ -9,4 +9,5 @@ export declare function isColumns(value: unknown): value is Column[];
|
|
|
9
9
|
export declare function isRecord(value: unknown): value is Record<string, unknown>;
|
|
10
10
|
export declare function redact(value: string): string;
|
|
11
11
|
export declare function compactRows(rows: Row[], maxCellCharacters: number): Row[];
|
|
12
|
+
export declare function compactValue(value: unknown, max: number): unknown;
|
|
12
13
|
export declare function toJsonSafe<T>(value: T): T;
|
package/dist/src/util.js
CHANGED
|
@@ -78,7 +78,7 @@ export function compactRows(rows, maxCellCharacters) {
|
|
|
78
78
|
compactValue(value, maxCellCharacters),
|
|
79
79
|
])));
|
|
80
80
|
}
|
|
81
|
-
function compactValue(value, max) {
|
|
81
|
+
export function compactValue(value, max) {
|
|
82
82
|
if (typeof value === "bigint")
|
|
83
83
|
return value.toString();
|
|
84
84
|
if (Buffer.isBuffer(value)) {
|
package/docs/batch.md
CHANGED
|
@@ -42,7 +42,8 @@ stql batch commands.json
|
|
|
42
42
|
Batch fields use snake case. Supported command names match CLI paths, such as
|
|
43
43
|
`actor.show`, `actor.set-name`, `filter`, `transaction.begin`, `session.summary`,
|
|
44
44
|
`alias.set`, `plan`, and `apply`. `actor.set-name` takes the display name in the
|
|
45
|
-
`name` field. Query commands may set `preview_rows` from 0 to 200.
|
|
45
|
+
`name` field. Query commands may set `preview_rows` from 0 to 200. `rows` may
|
|
46
|
+
set `columns` to an array of column names; `summarize` takes `handle`. Native MongoDB
|
|
46
47
|
batches use `mongo.query`, `mongo.exec`, or `mongo.plan` with the command object
|
|
47
48
|
in `mongo`; the same cache, replay, idempotency, safety, and timeout fields
|
|
48
49
|
apply. Database commands may set `timeout_ms`; otherwise they use the 30-second
|
package/docs/cli.md
CHANGED
|
@@ -11,29 +11,29 @@ stql disconnect
|
|
|
11
11
|
stql status
|
|
12
12
|
stql actor show
|
|
13
13
|
stql actor set-name <display-name>
|
|
14
|
-
stql profile add|update NAME [TARGET | --env ENV | --credential-ref REF]
|
|
14
|
+
stql profile add|update NAME [TARGET [--ask-password] | --env ENV | --credential-ref REF]
|
|
15
15
|
[--read-only|--read-write]
|
|
16
16
|
stql profile list|show|remove
|
|
17
17
|
stql session start|list|show|summary|close
|
|
18
|
-
stql query <sql> [--params JSON | --param VALUE...] [--cache auto|bypass|require]
|
|
18
|
+
stql query <sql> | --file FILE [--params JSON | --param VALUE...] [--cache auto|bypass|require]
|
|
19
19
|
[--preview-rows 0..200]
|
|
20
20
|
stql filter <result-handle> <predicate> [--params JSON | --param VALUE...]
|
|
21
|
-
stql exec <sql> [--params JSON | --param VALUE...] [--idempotency-key KEY] [--replay]
|
|
21
|
+
stql exec <sql> | --file FILE [--params JSON | --param VALUE...] [--idempotency-key KEY] [--replay]
|
|
22
22
|
[--allow-unbounded] [--allow-destructive]
|
|
23
|
-
stql mongo query|exec|plan '<EJSON command>' [--cache MODE] [--idempotency-key KEY]
|
|
23
|
+
stql mongo query|exec|plan '<EJSON command>' | --file FILE [--cache MODE] [--idempotency-key KEY]
|
|
24
24
|
[--replay] [--allow-unbounded] [--allow-destructive]
|
|
25
25
|
stql redis query '<JSON command>' [--cache auto|bypass|require]
|
|
26
26
|
stql redis exec '<JSON command>' [--idempotency-key KEY] [--replay]
|
|
27
27
|
stql redis plan '<JSON command>'
|
|
28
|
-
stql show|count|columns <result-handle>
|
|
29
|
-
stql rows <result-handle> [--offset N] [--limit N]
|
|
28
|
+
stql show|count|columns|summarize <result-handle>
|
|
29
|
+
stql rows <result-handle> [--offset N] [--limit N] [--columns a,b]
|
|
30
30
|
stql alias set <name> <result-handle>
|
|
31
|
-
stql export <result-handle> --output FILE [--format json|jsonl|csv]
|
|
31
|
+
stql export <result-handle> --output FILE [--format json|jsonl|csv] [--columns a,b]
|
|
32
32
|
stql inspect schema|table|collection|collections|columns|indexes|constraints [name]
|
|
33
33
|
stql objects [KIND] [--schema NAME] [--search TEXT] [--offset N|--cursor CURSOR] [--limit N]
|
|
34
34
|
stql object KIND NAME [IDENTITY] [--schema NAME]
|
|
35
35
|
stql transaction begin|status|commit|rollback [--isolation LEVEL]
|
|
36
|
-
stql plan <sql> [--params JSON | --param VALUE...] [--allow-unbounded] [--allow-destructive]
|
|
36
|
+
stql plan <sql> | --file FILE [--params JSON | --param VALUE...] [--allow-unbounded] [--allow-destructive]
|
|
37
37
|
stql apply <plan-handle>
|
|
38
38
|
stql history [--limit N] [--offset N] [--category statement|introspection|management]
|
|
39
39
|
[--internal|--external]
|
|
@@ -43,7 +43,7 @@ stql purge [expired|results|history|all]
|
|
|
43
43
|
stql capabilities
|
|
44
44
|
stql batch [commands.json|commands.jsonl|-] [--continue-on-error]
|
|
45
45
|
stql pipe [--continue-on-error]
|
|
46
|
-
stql help
|
|
46
|
+
stql help [command]
|
|
47
47
|
```
|
|
48
48
|
|
|
49
49
|
Global options: `--output MODE`, `--timeout-ms N`, `--max-cell-characters N`,
|
|
@@ -63,6 +63,10 @@ Use `--params JSON` for a JSON array or named parameters. Use
|
|
|
63
63
|
`--params-file FILE` when JSON is awkward to quote; `--params-file -` reads
|
|
64
64
|
JSON from standard input.
|
|
65
65
|
|
|
66
|
+
Use `--file FILE` instead of inline text to read the SQL, or the MongoDB or
|
|
67
|
+
Redis command, from a file. `--file -` reads standard input, so it cannot be
|
|
68
|
+
combined with `--params-file -`. A leading UTF-8 BOM is ignored.
|
|
69
|
+
|
|
66
70
|
## Catalog inspection
|
|
67
71
|
|
|
68
72
|
Use `objects` to list a bounded page and `object` to describe an entry:
|
|
@@ -98,6 +102,8 @@ their complete error object. Empty warnings and tracing metadata are omitted.
|
|
|
98
102
|
|
|
99
103
|
Agent mode also removes data that costs tokens but adds no information:
|
|
100
104
|
|
|
105
|
+
- `summarize` returns `columns` (`name`, `nulls`, `distinct`, `min`, `max`) and
|
|
106
|
+
one row per result column.
|
|
101
107
|
- `query`, `filter`, `show`, `mongo.query`, and `rows` return `columns` once and
|
|
102
108
|
each row as an array in that order. When rows have different keys (for
|
|
103
109
|
example, MongoDB documents), rows stay objects and `columns` is omitted.
|
|
@@ -110,7 +116,7 @@ Agent mode also removes data that costs tokens but adds no information:
|
|
|
110
116
|
- `capabilities` lists enabled `features` as names.
|
|
111
117
|
- `objects` returns `columns` once and each entry as an array. `identity` is
|
|
112
118
|
omitted when it equals `schema.name` (or `name`) for every entry.
|
|
113
|
-
- `rows`, `count`, and `
|
|
119
|
+
- `rows`, `count`, `columns`, and `summarize` do not repeat the handle you passed.
|
|
114
120
|
- Result `handle` is the generated alias, which cannot be reassigned. Full
|
|
115
121
|
`q_...` IDs work too and appear in `--output json`, `silent`, and history.
|
|
116
122
|
`alias` is present only when you chose a different name (batch `as`).
|
package/docs/connections.md
CHANGED
|
@@ -45,9 +45,10 @@ export SQLITE_DATABASE='sqlite:./app.sqlite'
|
|
|
45
45
|
stql connect --env SQLITE_DATABASE --name local --read-only
|
|
46
46
|
```
|
|
47
47
|
|
|
48
|
-
StateQL stores no PostgreSQL, MySQL, MongoDB, or Redis password.
|
|
48
|
+
StateQL stores no PostgreSQL, MySQL, MongoDB, or Redis password in its state.
|
|
49
49
|
Credential-bearing URLs must be supplied through `--env` or an opaque full-URL
|
|
50
|
-
credential reference
|
|
50
|
+
credential reference, or the password can be [saved in the OS credential
|
|
51
|
+
store](#saved-passwords). SQLite paths remain persisted as connection metadata.
|
|
51
52
|
|
|
52
53
|
## Local profiles
|
|
53
54
|
|
|
@@ -70,15 +71,36 @@ stql connect --profile production
|
|
|
70
71
|
```
|
|
71
72
|
|
|
72
73
|
Credential references are bounded nonempty opaque strings; StateQL does not
|
|
73
|
-
apply environment-variable syntax or normalization to them.
|
|
74
|
-
|
|
75
|
-
store them in profiles but
|
|
74
|
+
apply environment-variable syntax or normalization to them. Apart from the
|
|
75
|
+
`os:` password references below, they can only be resolved by a trusted host
|
|
76
|
+
`CredentialResolver`, so the standalone CLI may store them in profiles but
|
|
77
|
+
cannot connect with them.
|
|
78
|
+
|
|
79
|
+
## Saved passwords
|
|
80
|
+
|
|
81
|
+
`--ask-password` opens a password dialog and saves the password in the OS
|
|
82
|
+
credential store: Windows Credential Manager, macOS Keychain, or Linux Secret
|
|
83
|
+
Service. The profile keeps the password-free target and an `os:` password
|
|
84
|
+
reference.
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
stql profile add charlie 'postgres://reader@db.example.com:5432/app?sslmode=verify-full' --ask-password --read-only
|
|
88
|
+
stql profile update charlie --ask-password # replace the saved password
|
|
89
|
+
stql profile remove charlie # also deletes the saved password
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
The dialog uses Windows PowerShell on Windows, `osascript` on macOS, and `zenity`
|
|
93
|
+
on Linux, so it also works when an agent runs the command. Replacing the
|
|
94
|
+
password, changing the target or source, or removing the profile deletes the
|
|
95
|
+
old saved password; reconnect sessions that used it. Any program running as
|
|
96
|
+
your OS user can read the store, so give agent profiles a read-only database
|
|
97
|
+
user.
|
|
76
98
|
|
|
77
99
|
A bare connection target matching a profile name resolves to that profile;
|
|
78
100
|
otherwise it remains a path or database URL.
|
|
79
101
|
|
|
80
102
|
`profile update` changes subsequent connections, not an already-open connection.
|
|
81
103
|
Omitting the source keeps it; supplying a new source replaces the old one.
|
|
82
|
-
|
|
83
|
-
`--password-ref` flag. See [safe profile updates](library.md#safe-profile-updates)
|
|
104
|
+
Other password references are configured through the library or batch API, not
|
|
105
|
+
a CLI `--password-ref` flag. See [safe profile updates](library.md#safe-profile-updates)
|
|
84
106
|
for source-replacement and downgrade restrictions.
|
package/docs/databases.md
CHANGED
|
@@ -95,8 +95,8 @@ stql plan "REINDEX TABLE public.jobs" --allow-destructive
|
|
|
95
95
|
|
|
96
96
|
The PostgreSQL 14–18 grammar includes parenthesized `REINDEX CONCURRENTLY`,
|
|
97
97
|
PostgreSQL 16 `BUFFER_USAGE_LIMIT` for `VACUUM`/`ANALYZE`, optional
|
|
98
|
-
`DATABASE`/`SYSTEM` reindex names, and PostgreSQL 18 `ONLY table *`
|
|
99
|
-
targets. Memory sizes accept an integer number of kilobytes or a quoted
|
|
98
|
+
`DATABASE`/`SYSTEM` reindex names, and PostgreSQL 18 `ONLY table` and `table *`
|
|
99
|
+
maintenance targets (not both on one table). Memory sizes accept an integer number of kilobytes or a quoted
|
|
100
100
|
`B|kB|MB|GB|TB` value. Older servers may reject newer forms after dispatch, so
|
|
101
101
|
StateQL retains conservative unknown-outcome handling.
|
|
102
102
|
|
package/docs/library.md
CHANGED
|
@@ -63,7 +63,9 @@ Library responses retain the full response envelope regardless of the CLI
|
|
|
63
63
|
output mode. Check `response.ok` before reading `response.data`; failures expose
|
|
64
64
|
`response.error`. Queries return typed `ResultData` with `result_id`, `preview`,
|
|
65
65
|
and result metadata. Reuse `result_id` with methods such as `filter`, `rows`,
|
|
66
|
-
`count`, and `exportResult`; the CLI instead presents its primary ID as `handle`.
|
|
66
|
+
`count`, `summarize`, and `exportResult`; the CLI instead presents its primary ID as `handle`.
|
|
67
|
+
`rows(id, { columns })` and `exportResult(id, output, format, columns)` return
|
|
68
|
+
only the named columns.
|
|
67
69
|
Queries preview five rows by default. Set `previewRows` from 0 to 200 on an
|
|
68
70
|
individual query to control its response without changing or rerunning the
|
|
69
71
|
materialized result. The constructor-level `previewRows` option changes the
|
package/docs/results.md
CHANGED
|
@@ -67,6 +67,18 @@ use `results`, `history`, or `all` for explicit session cleanup. On POSIX
|
|
|
67
67
|
systems, StateQL removes group and world access from its state directory,
|
|
68
68
|
database, and SQLite sidecar files.
|
|
69
69
|
|
|
70
|
+
## Column projection and summaries
|
|
71
|
+
|
|
72
|
+
`rows` and `export` accept `--columns a,b` (library: `columns: ["a", "b"]`) to
|
|
73
|
+
return only those columns, in that order. Unknown column names fail with
|
|
74
|
+
`INVALID_COMMAND` and a list of the available columns.
|
|
75
|
+
|
|
76
|
+
`summarize` returns, for each column of a stored result, the null count, the
|
|
77
|
+
distinct count, and the min and max. Min and max are computed only when all
|
|
78
|
+
non-null values are numbers or all are strings. Numeric strings, such as
|
|
79
|
+
PostgreSQL `numeric` values, compare as numbers. Neither command accesses the
|
|
80
|
+
original database.
|
|
81
|
+
|
|
70
82
|
## Local filtering
|
|
71
83
|
|
|
72
84
|
`filter` evaluates one scalar SQLite predicate against a stored result. It
|
package/docs/writes.md
CHANGED
|
@@ -10,6 +10,12 @@ The flags are independent.
|
|
|
10
10
|
the flags explicitly supplied when it is created; `apply` never adds
|
|
11
11
|
authorization.
|
|
12
12
|
|
|
13
|
+
For a single-table SQL `UPDATE` or `DELETE` without `ORDER BY` or `LIMIT`,
|
|
14
|
+
`plan` also returns `estimated_rows`: a `COUNT(*)` of the rows that the `WHERE`
|
|
15
|
+
clause matches at plan time. The field is absent for other statements, or when
|
|
16
|
+
the count cannot be derived. Data can change before `apply`, so treat it as an
|
|
17
|
+
estimate; `affected_rows` on `apply` is the real value.
|
|
18
|
+
|
|
13
19
|
Use an idempotency key to protect retryable writes from duplicate execution:
|
|
14
20
|
|
|
15
21
|
```bash
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fadhilp/stateql",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.17.0",
|
|
4
4
|
"description": "Stateful, agent-oriented database CLI for safe result reuse",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -47,6 +47,7 @@
|
|
|
47
47
|
"node": ">=22.16"
|
|
48
48
|
},
|
|
49
49
|
"dependencies": {
|
|
50
|
+
"@napi-rs/keyring": "^2.1.1",
|
|
50
51
|
"@redis/client": "^5.12.1",
|
|
51
52
|
"bson": "^6.10.4",
|
|
52
53
|
"mongodb": "^6.21.0",
|
package/skills/stateql/SKILL.md
CHANGED
|
@@ -22,7 +22,7 @@ If `stql --version` fails, ask the user before installing
|
|
|
22
22
|
3. Never add `--allow-destructive`, `--allow-unbounded`, or `--replay` unless the
|
|
23
23
|
user explicitly approved that operation. They are approvals, not fixes.
|
|
24
24
|
4. Never put a password in a command. Remote URLs go in an environment variable
|
|
25
|
-
that you pass with `--env
|
|
25
|
+
that you pass with `--env`, or in a profile with a saved password (below).
|
|
26
26
|
5. Pass values as parameters (`--param`), never by building SQL strings.
|
|
27
27
|
6. Do not rerun a query to see more rows. Use its handle.
|
|
28
28
|
|
|
@@ -37,6 +37,11 @@ stql connect --env DATABASE_URL --read-write # only for requested changes
|
|
|
37
37
|
|
|
38
38
|
`status` without a `connection` field means no connection is open.
|
|
39
39
|
|
|
40
|
+
To save a remote database with its password, run
|
|
41
|
+
`stql profile add <name> '<password-free URL>' --ask-password`. The user types
|
|
42
|
+
the password in a dialog; then use `stql connect <name>`. `stql profile list`
|
|
43
|
+
shows saved profiles.
|
|
44
|
+
|
|
40
45
|
## Read workflow
|
|
41
46
|
|
|
42
47
|
1. Find objects: `stql objects table --search order`
|
|
@@ -46,14 +51,18 @@ stql connect --env DATABASE_URL --read-write # only for requested changes
|
|
|
46
51
|
4. Read the response (see below). `total` is the full row count, so you do not
|
|
47
52
|
need a separate `COUNT(*)`.
|
|
48
53
|
5. More rows: `stql rows <handle> --offset <next_offset> --limit 50`
|
|
49
|
-
(default 20, maximum 1000).
|
|
54
|
+
(default 20, maximum 1000). Add `--columns id,email` to return only some
|
|
55
|
+
columns of a wide result.
|
|
56
|
+
To understand the data, run `stql summarize <handle>`: for each column it
|
|
57
|
+
returns the null count, distinct count, min, and max.
|
|
50
58
|
6. Narrow down: `stql filter <handle> 'CAST(total AS REAL) > ?' --param 100`.
|
|
51
59
|
This runs locally on the stored rows in SQLite syntax, always with `?`, and
|
|
52
60
|
returns a new handle. PostgreSQL `numeric`/`bigint` and MySQL `DECIMAL` values
|
|
53
61
|
are stored as strings (`"7.50"`), and SQLite treats every string as greater
|
|
54
62
|
than every number, so `total > ?` silently matches all rows. Wrap such
|
|
55
63
|
columns in `CAST(... AS REAL)`, or filter in SQL with a new query.
|
|
56
|
-
7. Save all rows: `stql export <handle> --output rows.csv` (`--format json|jsonl|csv
|
|
64
|
+
7. Save all rows: `stql export <handle> --output rows.csv` (`--format json|jsonl|csv`,
|
|
65
|
+
optional `--columns`).
|
|
57
66
|
|
|
58
67
|
Use `--preview-rows N` (0 to 200) on `query` to change the preview size. Use
|
|
59
68
|
`--cache bypass` when data may have changed outside this session; writes made
|
|
@@ -67,7 +76,7 @@ through `stql` invalidate the cache automatically.
|
|
|
67
76
|
|
|
68
77
|
| Field | Meaning |
|
|
69
78
|
| --- | --- |
|
|
70
|
-
| `handle` | Stable result handle. Pass it to `rows`, `filter`, `count`, `columns`, `show`, `export`. |
|
|
79
|
+
| `handle` | Stable result handle. Pass it to `rows`, `filter`, `count`, `columns`, `summarize`, `show`, `export`. |
|
|
71
80
|
| `columns` + `rows` | Each row is an array in `columns` order. If rows have different keys (MongoDB documents), rows are objects and `columns` is absent. |
|
|
72
81
|
| `total` | Rows in the stored result. |
|
|
73
82
|
| `next_offset` | Present only when more rows exist. Absent means you have every row. |
|
|
@@ -91,12 +100,16 @@ through `stql` invalidate the cache automatically.
|
|
|
91
100
|
|
|
92
101
|
- Put SQL in single quotes. In bash and PowerShell, `"$1"` expands to an empty
|
|
93
102
|
string and breaks the query.
|
|
103
|
+
- For long SQL, or SQL with quotes, write it to a file and pass
|
|
104
|
+
`--file query.sql` instead of the inline SQL. `--file -` reads standard input.
|
|
105
|
+
This works for `query`, `exec`, `plan`, `stql mongo`, and `stql redis`.
|
|
94
106
|
- Use parameters instead of string literals, so you do not need quotes inside
|
|
95
107
|
quotes: `--param 'Ada Lovelace'`.
|
|
96
108
|
- **Windows PowerShell 5.1** removes the double quotes inside JSON arguments, so
|
|
97
109
|
`--params '[1]'` is fine but `stql redis query '{"command":"GET"}'` breaks.
|
|
98
|
-
Send JSON on standard input instead:
|
|
99
|
-
|
|
110
|
+
Send the JSON on standard input instead:
|
|
111
|
+
`'{"command":"GET","args":["a"]}' | stql redis query --file -`, or
|
|
112
|
+
`'<one JSON command>' | stql pipe` (see below).
|
|
100
113
|
|
|
101
114
|
## Several steps in one call
|
|
102
115
|
|
|
@@ -163,4 +176,4 @@ before you use `stql mongo` or `stql redis`.
|
|
|
163
176
|
| `stql history --limit 10` | Recent commands in this session |
|
|
164
177
|
| `stql receipt <operation-handle>` | Full record of a write |
|
|
165
178
|
| `stql session summary` | Open results and recent writes |
|
|
166
|
-
| `stql help
|
|
179
|
+
| `stql help <command>` | Syntax of one command (`stql help` lists all) |
|
|
@@ -43,10 +43,13 @@ Use a plan when the user should review a write before it runs.
|
|
|
43
43
|
|
|
44
44
|
```bash
|
|
45
45
|
stql plan 'DELETE FROM sessions WHERE expires_at < $1' --param 2026-01-01 --allow-destructive
|
|
46
|
-
# show the user statement_type, required_overrides, and expires_at
|
|
46
|
+
# show the user statement_type, estimated_rows, required_overrides, and expires_at
|
|
47
47
|
stql apply <plan-handle>
|
|
48
48
|
```
|
|
49
49
|
|
|
50
|
+
- `estimated_rows` is the number of rows the `WHERE` clause matched when the
|
|
51
|
+
plan was made. It is present only for single-table `UPDATE` and `DELETE`
|
|
52
|
+
without `ORDER BY`/`LIMIT`. If it is absent, count the rows with a query.
|
|
50
53
|
- A plan keeps only the approval flags given to `plan`; `apply` never adds any.
|
|
51
54
|
- If data changed after `plan`, `apply` returns `STALE_PLAN`. Create a new plan.
|
|
52
55
|
- Plans expire after 10 minutes.
|