@fadhilp/stateql 0.13.3 → 0.14.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/README.md +29 -67
- package/dist/src/cli.js +145 -21
- package/dist/src/errors.d.ts +1 -0
- package/dist/src/errors.js +40 -0
- package/dist/src/sql.js +18 -1
- package/dist/src/stateql.js +7 -7
- package/dist/src/util.d.ts +1 -0
- package/dist/src/util.js +1 -1
- package/docs/agents.md +72 -0
- package/docs/batch.md +49 -0
- package/docs/cli.md +152 -0
- package/docs/connections.md +84 -0
- package/docs/databases.md +4 -4
- package/docs/library.md +6 -5
- package/docs/results.md +78 -0
- package/docs/writes.md +40 -0
- package/package.json +1 -1
- package/docs/usage.md +0 -372
package/README.md
CHANGED
|
@@ -1,98 +1,60 @@
|
|
|
1
1
|
# StateQL
|
|
2
2
|
|
|
3
3
|
StateQL is a stateful database CLI and TypeScript library for AI agents and
|
|
4
|
-
automation.
|
|
5
|
-
|
|
4
|
+
automation. It keeps query results as durable handles, so later commands can
|
|
5
|
+
page, filter, count, or export them without querying the database again.
|
|
6
6
|
|
|
7
7
|
- **SQL:** SQLite, PostgreSQL, and MySQL.
|
|
8
8
|
- **Native commands:** MongoDB (EJSON) and Redis (JSON).
|
|
9
|
-
- **
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
where supported by the database.
|
|
9
|
+
- **Compact output:** one-line JSON with a 5-row preview and column names sent once.
|
|
10
|
+
- **Safe writes:** read-only by default, explicit approval for unbounded or
|
|
11
|
+
destructive statements, idempotency keys, plans, and staged transactions.
|
|
13
12
|
|
|
14
|
-
Requires **Node.js 22.16 or newer
|
|
13
|
+
Requires **Node.js 22.16 or newer**.
|
|
15
14
|
|
|
16
|
-
##
|
|
17
|
-
|
|
18
|
-
Install the CLI:
|
|
15
|
+
## Install
|
|
19
16
|
|
|
20
17
|
```bash
|
|
21
|
-
npm install -g @fadhilp/stateql
|
|
18
|
+
npm install -g @fadhilp/stateql # CLI (stql)
|
|
19
|
+
npm install @fadhilp/stateql # TypeScript library
|
|
22
20
|
```
|
|
23
21
|
|
|
24
|
-
|
|
25
|
-
examples use Bash; see the [usage guide](docs/usage.md) for connection options and
|
|
26
|
-
SQL parameter handling.
|
|
22
|
+
## Quick start
|
|
27
23
|
|
|
28
24
|
```bash
|
|
29
25
|
export STQL_SESSION=audit
|
|
30
|
-
stql
|
|
31
|
-
stql connect local
|
|
26
|
+
stql connect ./app.sqlite
|
|
32
27
|
|
|
33
|
-
stql query
|
|
34
|
-
"SELECT id, name, email FROM users WHERE status = ? AND created_at >= ? ORDER BY id LIMIT 50" \
|
|
35
|
-
--param active \
|
|
36
|
-
--param 2026-01-01
|
|
28
|
+
stql query "SELECT id, name FROM users WHERE status = ? ORDER BY id" --param active
|
|
37
29
|
```
|
|
38
30
|
|
|
39
|
-
Parameters keep values separate from SQL. `ORDER BY` makes paging stable, and
|
|
40
|
-
`LIMIT` bounds work at the database. The default `agent` output is compact,
|
|
41
|
-
one-line JSON. An example response:
|
|
42
|
-
|
|
43
31
|
```json
|
|
44
|
-
{"ok":true,"handle":"
|
|
32
|
+
{"ok":true,"handle":"katcitg6un","total":333,"next_offset":5,"columns":["id","name"],"rows":[[2,"Ada"],[3,"Grace"],[5,"Linus"],[6,"Alan"],[8,"Edsger"]]}
|
|
45
33
|
```
|
|
46
34
|
|
|
47
|
-
|
|
48
|
-
Give the snapshot a readable alias, then work with the stored data:
|
|
35
|
+
Reuse the result by its handle. These commands do not access the database:
|
|
49
36
|
|
|
50
37
|
```bash
|
|
51
|
-
stql
|
|
52
|
-
stql
|
|
53
|
-
stql
|
|
54
|
-
stql export active-users --output active-users.csv --format csv
|
|
55
|
-
stql filter active-users "email LIKE ?" --param "%@example.com"
|
|
38
|
+
stql rows katcitg6un --offset 5 --limit 20
|
|
39
|
+
stql filter katcitg6un "name LIKE ?" --param "A%"
|
|
40
|
+
stql export katcitg6un --output users.csv
|
|
56
41
|
```
|
|
57
42
|
|
|
58
|
-
These commands do not access the original database. `filter` creates a new
|
|
59
|
-
snapshot with its own handle. Repeating a query can reuse a valid cached result;
|
|
60
|
-
use `--cache bypass` when a fresh database read is required.
|
|
61
|
-
|
|
62
|
-
## Safety and state
|
|
63
|
-
|
|
64
|
-
- Connections are **read-only by default**. Writes require a read-write connection.
|
|
65
|
-
- Destructive and unbounded SQL/MongoDB operations require independent
|
|
66
|
-
`--allow-destructive` and `--allow-unbounded` approvals, respectively.
|
|
67
|
-
- `plan` stores a write for review; `apply` never adds authorization. Use
|
|
68
|
-
idempotency keys to protect retryable writes from duplicate execution.
|
|
69
|
-
- A write reported as `OUTCOME_UNKNOWN` must be inspected at the database before
|
|
70
|
-
replaying it. Transactions are staged locally, not live interactive SQL
|
|
71
|
-
transactions.
|
|
72
|
-
- Supply credential-bearing URLs through environment variables or a trusted
|
|
73
|
-
library credential resolver, not literal command arguments or profiles.
|
|
74
|
-
- Results and history persist under `STQL_HOME` (or the platform data directory).
|
|
75
|
-
Treat that state as database data; retention and size limits are configurable.
|
|
76
|
-
|
|
77
|
-
See [write safety](docs/usage.md#write-safety),
|
|
78
|
-
[credentials](docs/usage.md#environment-backed-credentials), and
|
|
79
|
-
[database restrictions](docs/databases.md) before using production data.
|
|
80
|
-
|
|
81
43
|
## Documentation
|
|
82
44
|
|
|
83
|
-
|
|
|
45
|
+
| Page | Contents |
|
|
84
46
|
| --- | --- |
|
|
85
|
-
| [
|
|
86
|
-
| [
|
|
87
|
-
| [
|
|
88
|
-
|
|
89
|
-
|
|
47
|
+
| [Agent guide](docs/agents.md) | The short version for agents: connect, query, reuse, save tokens |
|
|
48
|
+
| [Connections](docs/connections.md) | Targets, environment credentials, profiles |
|
|
49
|
+
| [CLI reference](docs/cli.md) | Commands, parameters, catalog, output modes, deadlines |
|
|
50
|
+
| [Results and state](docs/results.md) | Sessions, actors, limits, caching, local filtering |
|
|
51
|
+
| [Write safety](docs/writes.md) | Approvals, plans, idempotency, transactions |
|
|
52
|
+
| [Batch and pipes](docs/batch.md) | Run many commands in one call |
|
|
53
|
+
| [Database support](docs/databases.md) | Dialects, diagnostics, MongoDB and Redis commands |
|
|
54
|
+
| [TypeScript library](docs/library.md) | API, responses, actors, credential resolution |
|
|
90
55
|
|
|
91
|
-
|
|
56
|
+
Run `stql help` for command syntax and `stql capabilities` for feature details.
|
|
92
57
|
|
|
93
|
-
|
|
94
|
-
npm install @fadhilp/stateql
|
|
95
|
-
```
|
|
58
|
+
## License
|
|
96
59
|
|
|
97
|
-
|
|
98
|
-
[connected, cleanup-safe example](docs/library.md#getting-started).
|
|
60
|
+
[MIT](LICENSE)
|
package/dist/src/cli.js
CHANGED
|
@@ -6,6 +6,13 @@ import { parseArgs } from "node:util";
|
|
|
6
6
|
import { BSON } from "mongodb";
|
|
7
7
|
import { exitCodeFor } from "./errors.js";
|
|
8
8
|
import { StateQL } from "./stateql.js";
|
|
9
|
+
import { isColumns, isRecord } from "./util.js";
|
|
10
|
+
const RESULT_COMMANDS = new Set(["query", "mongo.query", "filter", "show"]);
|
|
11
|
+
const FALSE_DEFAULT_KEYS = ["cached", "duplicate", "duplicate_override"];
|
|
12
|
+
const SHARED_HISTORY_KEYS = ["session_id", "actor_id", "actor_name", "origin"];
|
|
13
|
+
// The caller already holds the handle it passed to these commands.
|
|
14
|
+
const HANDLE_ECHO_COMMANDS = new Set(["rows", "count", "columns"]);
|
|
15
|
+
const WRITE_COMMANDS = new Set(["exec", "mongo.exec", "apply"]);
|
|
9
16
|
const parsed = parseArgs({
|
|
10
17
|
allowPositionals: true,
|
|
11
18
|
strict: true,
|
|
@@ -21,6 +28,7 @@ const parsed = parseArgs({
|
|
|
21
28
|
"params-file": { type: "string" },
|
|
22
29
|
cache: { type: "string" },
|
|
23
30
|
"preview-rows": { type: "string" },
|
|
31
|
+
"max-cell-characters": { type: "string" },
|
|
24
32
|
replay: { type: "boolean" },
|
|
25
33
|
"idempotency-key": { type: "string" },
|
|
26
34
|
"allow-unbounded": { type: "boolean" },
|
|
@@ -51,7 +59,7 @@ if (values.version) {
|
|
|
51
59
|
console.log(packageVersion());
|
|
52
60
|
process.exit(0);
|
|
53
61
|
}
|
|
54
|
-
if (values.help || !command) {
|
|
62
|
+
if (values.help || !command || command === "help") {
|
|
55
63
|
console.log(helpText());
|
|
56
64
|
process.exit(0);
|
|
57
65
|
}
|
|
@@ -71,6 +79,9 @@ const stateql = new StateQL({
|
|
|
71
79
|
...(values["result-ttl-seconds"] === undefined
|
|
72
80
|
? {}
|
|
73
81
|
: { resultTtlSeconds: Number(values["result-ttl-seconds"]) }),
|
|
82
|
+
...(values["max-cell-characters"] === undefined
|
|
83
|
+
? {}
|
|
84
|
+
: { maxCellCharacters: Number(values["max-cell-characters"]) }),
|
|
74
85
|
signal: abortController.signal,
|
|
75
86
|
});
|
|
76
87
|
try {
|
|
@@ -534,33 +545,33 @@ function print(result, mode, currentCommand) {
|
|
|
534
545
|
function toAgentResponse(result, currentCommand) {
|
|
535
546
|
if (!result.ok)
|
|
536
547
|
return { ok: false, error: result.error };
|
|
537
|
-
if (!result.data
|
|
538
|
-
typeof result.data !== "object" ||
|
|
539
|
-
Array.isArray(result.data)) {
|
|
548
|
+
if (!isRecord(result.data))
|
|
540
549
|
return { ok: true, data: result.data };
|
|
541
|
-
}
|
|
542
550
|
const data = { ...result.data };
|
|
543
551
|
const handleKey = primaryHandleKey(currentCommand);
|
|
544
|
-
|
|
552
|
+
let handle = handleKey && typeof data[handleKey] === "string" && data[handleKey]
|
|
545
553
|
? data[handleKey]
|
|
546
554
|
: undefined;
|
|
547
555
|
if (handle && handleKey)
|
|
548
556
|
delete data[handleKey];
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
557
|
+
const generatedAlias = data.display_alias;
|
|
558
|
+
delete data.display_alias;
|
|
559
|
+
// Generated aliases cannot be reassigned, so they are stable short result handles.
|
|
560
|
+
if (RESULT_COMMANDS.has(currentCommand) && typeof generatedAlias === "string") {
|
|
561
|
+
handle = generatedAlias;
|
|
562
|
+
if (data.alias === generatedAlias)
|
|
563
|
+
delete data.alias;
|
|
564
|
+
}
|
|
565
|
+
const isResult = RESULT_COMMANDS.has(currentCommand) &&
|
|
553
566
|
typeof data.rows === "number" &&
|
|
554
|
-
Array.isArray(data.preview)
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
data.rows =
|
|
559
|
-
data.total = total;
|
|
560
|
-
data.next_offset = truncated ? rows.length : null;
|
|
567
|
+
Array.isArray(data.preview);
|
|
568
|
+
if (isResult) {
|
|
569
|
+
data.total = data.rows;
|
|
570
|
+
data.next_offset = data.truncated ? data.preview.length : null;
|
|
571
|
+
data.rows = data.preview;
|
|
561
572
|
delete data.preview;
|
|
562
573
|
delete data.preview_count;
|
|
563
|
-
delete data.
|
|
574
|
+
delete data.truncated;
|
|
564
575
|
delete data.storage;
|
|
565
576
|
delete data.state_version;
|
|
566
577
|
delete data.duplicate_of;
|
|
@@ -569,11 +580,55 @@ function toAgentResponse(result, currentCommand) {
|
|
|
569
580
|
delete data.offset;
|
|
570
581
|
delete data.limit;
|
|
571
582
|
delete data.returned;
|
|
583
|
+
delete data.truncated;
|
|
572
584
|
}
|
|
573
585
|
else if (currentCommand === "count" && typeof data.rows === "number") {
|
|
574
586
|
data.total = data.rows;
|
|
575
587
|
delete data.rows;
|
|
576
588
|
}
|
|
589
|
+
else if (WRITE_COMMANDS.has(currentCommand)) {
|
|
590
|
+
delete data.actor_id;
|
|
591
|
+
delete data.plan_id;
|
|
592
|
+
delete data.state_version_before;
|
|
593
|
+
if (typeof data.status === "string")
|
|
594
|
+
delete data.committed;
|
|
595
|
+
}
|
|
596
|
+
else if (currentCommand === "history" &&
|
|
597
|
+
Array.isArray(data.history) &&
|
|
598
|
+
data.history.every(isRecord)) {
|
|
599
|
+
Object.assign(data, compactHistory(data.history));
|
|
600
|
+
}
|
|
601
|
+
else if (currentCommand === "inspect" && Array.isArray(data.columns)) {
|
|
602
|
+
data.columns = data.columns.map(withoutFalsePrimaryKey);
|
|
603
|
+
}
|
|
604
|
+
else if (currentCommand === "capabilities" && isRecord(data.features)) {
|
|
605
|
+
const features = data.features;
|
|
606
|
+
data.features = Object.keys(features).filter((key) => features[key] === true);
|
|
607
|
+
}
|
|
608
|
+
else if (currentCommand === "objects" &&
|
|
609
|
+
Array.isArray(data.objects) &&
|
|
610
|
+
data.objects.every(isRecord)) {
|
|
611
|
+
const objects = data.objects.every(hasDerivedIdentity)
|
|
612
|
+
? data.objects.map(withoutIdentity)
|
|
613
|
+
: data.objects;
|
|
614
|
+
const table = columnarRows(objects, undefined);
|
|
615
|
+
delete data.objects;
|
|
616
|
+
Object.assign(data, { columns: table.columns, objects: table.rows });
|
|
617
|
+
}
|
|
618
|
+
else if (currentCommand === "object" &&
|
|
619
|
+
isRecord(data.object) &&
|
|
620
|
+
hasDerivedIdentity(data.object)) {
|
|
621
|
+
data.object = withoutIdentity(data.object);
|
|
622
|
+
}
|
|
623
|
+
if (isResult || (currentCommand === "rows" && Array.isArray(data.rows))) {
|
|
624
|
+
const table = columnarRows(data.rows, data.columns);
|
|
625
|
+
delete data.columns;
|
|
626
|
+
delete data.rows;
|
|
627
|
+
Object.assign(data, table);
|
|
628
|
+
}
|
|
629
|
+
const hasMoreRows = data.next_offset !== null && data.next_offset !== undefined;
|
|
630
|
+
const warnings = result.warnings.filter((warning) => warning.code !== "NON_DETERMINISTIC_PAGINATION" || hasMoreRows);
|
|
631
|
+
dropFalseDefaults(data);
|
|
577
632
|
for (const key of ["ok", "error", "handle", "warnings"]) {
|
|
578
633
|
if (!(key in data))
|
|
579
634
|
continue;
|
|
@@ -582,11 +637,77 @@ function toAgentResponse(result, currentCommand) {
|
|
|
582
637
|
}
|
|
583
638
|
return {
|
|
584
639
|
ok: true,
|
|
585
|
-
...(handle ? { handle } : {}),
|
|
586
|
-
...data,
|
|
587
|
-
...(
|
|
640
|
+
...(handle && !HANDLE_ECHO_COMMANDS.has(currentCommand) ? { handle } : {}),
|
|
641
|
+
...withoutNulls(data),
|
|
642
|
+
...(warnings.length ? { warnings } : {}),
|
|
588
643
|
};
|
|
589
644
|
}
|
|
645
|
+
// Rows with differing keys (e.g. MongoDB documents) stay objects so missing and null remain distinct.
|
|
646
|
+
function columnarRows(rows, columns) {
|
|
647
|
+
const names = isColumns(columns)
|
|
648
|
+
? columns.map((column) => column.name)
|
|
649
|
+
: Object.keys(rows[0] ?? {});
|
|
650
|
+
if (names.length === 0)
|
|
651
|
+
return { rows };
|
|
652
|
+
const nameSet = new Set(names);
|
|
653
|
+
const hasColumnKeys = (row) => {
|
|
654
|
+
if (!isRecord(row))
|
|
655
|
+
return false;
|
|
656
|
+
const keys = Object.keys(row);
|
|
657
|
+
return keys.length === names.length && keys.every((key) => nameSet.has(key));
|
|
658
|
+
};
|
|
659
|
+
if (!rows.every(hasColumnKeys))
|
|
660
|
+
return { rows };
|
|
661
|
+
return {
|
|
662
|
+
columns: names,
|
|
663
|
+
rows: rows.map((row) => names.map((name) => row[name])),
|
|
664
|
+
};
|
|
665
|
+
}
|
|
666
|
+
function compactHistory(entries) {
|
|
667
|
+
const shared = {};
|
|
668
|
+
for (const key of SHARED_HISTORY_KEYS) {
|
|
669
|
+
const value = entries[0]?.[key];
|
|
670
|
+
if (value === undefined)
|
|
671
|
+
continue;
|
|
672
|
+
if (entries.every((entry) => entry[key] === value))
|
|
673
|
+
shared[key] = value;
|
|
674
|
+
}
|
|
675
|
+
const history = entries.map((entry) => {
|
|
676
|
+
const compact = withoutNulls(entry);
|
|
677
|
+
dropFalseDefaults(compact);
|
|
678
|
+
for (const key of Object.keys(shared))
|
|
679
|
+
delete compact[key];
|
|
680
|
+
return compact;
|
|
681
|
+
});
|
|
682
|
+
return { ...shared, history };
|
|
683
|
+
}
|
|
684
|
+
function hasDerivedIdentity(object) {
|
|
685
|
+
const qualifiedName = typeof object.schema === "string"
|
|
686
|
+
? `${object.schema}.${String(object.name)}`
|
|
687
|
+
: object.name;
|
|
688
|
+
return object.identity === undefined || object.identity === qualifiedName;
|
|
689
|
+
}
|
|
690
|
+
function withoutIdentity(object) {
|
|
691
|
+
const compact = { ...object };
|
|
692
|
+
delete compact.identity;
|
|
693
|
+
return compact;
|
|
694
|
+
}
|
|
695
|
+
function withoutFalsePrimaryKey(column) {
|
|
696
|
+
if (!isRecord(column) || column.primary_key !== false)
|
|
697
|
+
return column;
|
|
698
|
+
const compact = { ...column };
|
|
699
|
+
delete compact.primary_key;
|
|
700
|
+
return compact;
|
|
701
|
+
}
|
|
702
|
+
function dropFalseDefaults(record) {
|
|
703
|
+
for (const key of FALSE_DEFAULT_KEYS) {
|
|
704
|
+
if (record[key] === false)
|
|
705
|
+
delete record[key];
|
|
706
|
+
}
|
|
707
|
+
}
|
|
708
|
+
function withoutNulls(record) {
|
|
709
|
+
return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== null));
|
|
710
|
+
}
|
|
590
711
|
function primaryHandleKey(currentCommand) {
|
|
591
712
|
const keys = {
|
|
592
713
|
query: "result_id",
|
|
@@ -674,10 +795,13 @@ Commands:
|
|
|
674
795
|
|
|
675
796
|
SQL parameters: --params JSON, repeated --param VALUE, or --params-file FILE.
|
|
676
797
|
Query preview: --preview-rows N (default: 5, maximum: 200).
|
|
798
|
+
Long cells: --max-cell-characters N (default: 200); use export for full values.
|
|
677
799
|
Deadline: --timeout-ms N (default: 30000). Ctrl+C cancels database work.
|
|
678
800
|
Credential refs require a trusted host CredentialResolver; the standalone CLI cannot resolve them.
|
|
679
801
|
State: --max-state-bytes N, --cache-ttl-seconds N, --result-ttl-seconds N.
|
|
680
802
|
Output: --output agent|json|jsonl|text|silent (default: agent).
|
|
803
|
+
Agent rows: arrays in "columns" order (objects when shapes differ). next_offset only when more rows exist.
|
|
804
|
+
Agent output omits null fields and false cached/duplicate flags. Guide: docs/agents.md.
|
|
681
805
|
Batch/pipe accept JSON array files or JSONL streams. Stop on first error.`;
|
|
682
806
|
}
|
|
683
807
|
function packageVersion() {
|
package/dist/src/errors.d.ts
CHANGED
|
@@ -14,4 +14,5 @@ export declare class StateQLError extends Error {
|
|
|
14
14
|
});
|
|
15
15
|
}
|
|
16
16
|
export declare function exitCodeFor(code: string): number;
|
|
17
|
+
export declare function isTransientDatabaseError(error: unknown): boolean;
|
|
17
18
|
export declare function asStateQLError(error: unknown): StateQLError;
|
package/dist/src/errors.js
CHANGED
|
@@ -49,6 +49,46 @@ export function exitCodeFor(code) {
|
|
|
49
49
|
return 9;
|
|
50
50
|
return 1;
|
|
51
51
|
}
|
|
52
|
+
const TRANSIENT_NETWORK_CODES = new Set([
|
|
53
|
+
"ECONNRESET",
|
|
54
|
+
"ECONNREFUSED",
|
|
55
|
+
"ETIMEDOUT",
|
|
56
|
+
"EPIPE",
|
|
57
|
+
"EAI_AGAIN",
|
|
58
|
+
"PROTOCOL_CONNECTION_LOST",
|
|
59
|
+
]);
|
|
60
|
+
// SQLSTATE classes: connection, transaction rollback, resources, operator intervention, system.
|
|
61
|
+
const TRANSIENT_SQLSTATE_CLASSES = new Set(["08", "40", "53", "57", "58"]);
|
|
62
|
+
// MySQL: too many connections, lock wait timeout, deadlock.
|
|
63
|
+
const TRANSIENT_MYSQL_ERRNOS = new Set([1040, 1205, 1213]);
|
|
64
|
+
const TRANSIENT_ERROR_NAMES = new Set([
|
|
65
|
+
"MongoNetworkError",
|
|
66
|
+
"MongoNetworkTimeoutError",
|
|
67
|
+
"MongoServerSelectionError",
|
|
68
|
+
"SocketClosedUnexpectedlyError",
|
|
69
|
+
"ConnectionTimeoutError",
|
|
70
|
+
]);
|
|
71
|
+
const TRANSIENT_SQLITE_MESSAGE = /database (table )?is locked|SQLITE_BUSY/i;
|
|
72
|
+
// Permanent failures such as a missing table must not invite retries; unknown errors are not retryable.
|
|
73
|
+
export function isTransientDatabaseError(error) {
|
|
74
|
+
if (!(error instanceof Error))
|
|
75
|
+
return false;
|
|
76
|
+
const details = error;
|
|
77
|
+
if (typeof details.code === "string" && TRANSIENT_NETWORK_CODES.has(details.code))
|
|
78
|
+
return true;
|
|
79
|
+
if (TRANSIENT_ERROR_NAMES.has(error.name))
|
|
80
|
+
return true;
|
|
81
|
+
if (typeof details.errno === "number" && TRANSIENT_MYSQL_ERRNOS.has(details.errno))
|
|
82
|
+
return true;
|
|
83
|
+
if (Array.isArray(details.errorLabels) && details.errorLabels.includes("TransientTransactionError")) {
|
|
84
|
+
return true;
|
|
85
|
+
}
|
|
86
|
+
const sqlState = typeof details.sqlState === "string" ? details.sqlState : details.code;
|
|
87
|
+
if (typeof sqlState === "string" && /^[0-9A-Z]{5}$/.test(sqlState)) {
|
|
88
|
+
return TRANSIENT_SQLSTATE_CLASSES.has(sqlState.slice(0, 2));
|
|
89
|
+
}
|
|
90
|
+
return TRANSIENT_SQLITE_MESSAGE.test(error.message);
|
|
91
|
+
}
|
|
52
92
|
export function asStateQLError(error) {
|
|
53
93
|
if (error instanceof StateQLError)
|
|
54
94
|
return error;
|
package/dist/src/sql.js
CHANGED
|
@@ -58,7 +58,13 @@ function parseSqlStatement(sql, driver) {
|
|
|
58
58
|
? "MySQL"
|
|
59
59
|
: "Sqlite";
|
|
60
60
|
const parserSql = driver === "postgres" ? postgresParserSql(sql) : sql;
|
|
61
|
-
|
|
61
|
+
let parsed;
|
|
62
|
+
try {
|
|
63
|
+
parsed = parser.astify(parserSql, { database });
|
|
64
|
+
}
|
|
65
|
+
catch (error) {
|
|
66
|
+
throw new StateQLError("INVALID_SQL", syntaxErrorMessage(error, parserSql));
|
|
67
|
+
}
|
|
62
68
|
if (Array.isArray(parsed) && parsed.length !== 1) {
|
|
63
69
|
throw new StateQLError("INVALID_SQL", "Exactly one SQL statement is required.");
|
|
64
70
|
}
|
|
@@ -1073,6 +1079,17 @@ function postgresBlockCommentEnd(sql, start) {
|
|
|
1073
1079
|
}
|
|
1074
1080
|
return undefined;
|
|
1075
1081
|
}
|
|
1082
|
+
// The parser lists every expected token (often 500+ characters); position and nearby text are enough to fix the SQL.
|
|
1083
|
+
function syntaxErrorMessage(error, sql) {
|
|
1084
|
+
const start = error.location?.start;
|
|
1085
|
+
if (!start)
|
|
1086
|
+
return error instanceof Error ? error.message : "Invalid SQL.";
|
|
1087
|
+
const near = sql.slice(start.offset, start.offset + 20).split("\n")[0];
|
|
1088
|
+
const position = `line ${start.line}, column ${start.column}`;
|
|
1089
|
+
return near
|
|
1090
|
+
? `Syntax error at ${position} near "${near}".`
|
|
1091
|
+
: `Syntax error at ${position}: unexpected end of input.`;
|
|
1092
|
+
}
|
|
1076
1093
|
function postgresParserSql(sql) {
|
|
1077
1094
|
const output = sql.split("");
|
|
1078
1095
|
const orderDepths = new Set();
|
package/dist/src/stateql.js
CHANGED
|
@@ -6,7 +6,7 @@ import { basename, resolve } from "node:path";
|
|
|
6
6
|
import { env } from "node:process";
|
|
7
7
|
import { AdapterExecutionError, AdapterWriteError, BatchWriteError, createAdapter, createAdapterContext, } from "./adapters.js";
|
|
8
8
|
import { confidence, credentialSource, databaseIdentity, databaseUrlHasSecret, detectDriver, isEnvironmentName, injectPassword, mongoDatabaseName, redisDatabaseName, normalizeSqliteSource, validateCredentialRef, validatePasswordReferenceTarget, validateProfileName, version, } from "./connection.js";
|
|
9
|
-
import { asStateQLError, CredentialResolutionError, StateQLError, } from "./errors.js";
|
|
9
|
+
import { asStateQLError, CredentialResolutionError, isTransientDatabaseError, StateQLError, } from "./errors.js";
|
|
10
10
|
import { analyzeMongoWriteSafety, deserializeMongoWriteCommand, serializeMongoCommand, validateMongoReadCommand, validateMongoWriteCommand, MongoAdapter, } from "./mongodb.js";
|
|
11
11
|
import { deserializeRedisCommand, RedisAdapter, serializeRedisCommand, validateRedisReadCommand, validateRedisWriteCommand, } from "./redis.js";
|
|
12
12
|
import { filterMaterializedRows, prepareFilterStatement, validateFilterParameters, } from "./filter.js";
|
|
@@ -811,7 +811,7 @@ export class StateQL {
|
|
|
811
811
|
throw stoppedStateQLError(error, true);
|
|
812
812
|
}
|
|
813
813
|
throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), {
|
|
814
|
-
retryable:
|
|
814
|
+
retryable: isTransientDatabaseError(error),
|
|
815
815
|
executed: true,
|
|
816
816
|
});
|
|
817
817
|
}
|
|
@@ -902,7 +902,7 @@ export class StateQL {
|
|
|
902
902
|
if (error instanceof AdapterExecutionError) {
|
|
903
903
|
throw stoppedStateQLError(error, true);
|
|
904
904
|
}
|
|
905
|
-
throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable:
|
|
905
|
+
throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: isTransientDatabaseError(error), executed: true });
|
|
906
906
|
}
|
|
907
907
|
finally {
|
|
908
908
|
await closeAdapterQuietly(adapter);
|
|
@@ -947,7 +947,7 @@ export class StateQL {
|
|
|
947
947
|
throw error;
|
|
948
948
|
if (error instanceof AdapterExecutionError)
|
|
949
949
|
throw stoppedStateQLError(error, true);
|
|
950
|
-
throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, source), { retryable:
|
|
950
|
+
throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, source), { retryable: isTransientDatabaseError(error), executed: true });
|
|
951
951
|
}
|
|
952
952
|
finally {
|
|
953
953
|
await closeAdapterQuietly(adapter);
|
|
@@ -1694,7 +1694,7 @@ export class StateQL {
|
|
|
1694
1694
|
if (error instanceof AdapterExecutionError) {
|
|
1695
1695
|
throw stoppedStateQLError(error, true);
|
|
1696
1696
|
}
|
|
1697
|
-
throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable:
|
|
1697
|
+
throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: isTransientDatabaseError(error), executed: true });
|
|
1698
1698
|
}
|
|
1699
1699
|
finally {
|
|
1700
1700
|
await closeAdapterQuietly(adapter);
|
|
@@ -1759,7 +1759,7 @@ export class StateQL {
|
|
|
1759
1759
|
if (error instanceof AdapterExecutionError) {
|
|
1760
1760
|
throw stoppedStateQLError(error, true);
|
|
1761
1761
|
}
|
|
1762
|
-
throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable:
|
|
1762
|
+
throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: isTransientDatabaseError(error), executed: true });
|
|
1763
1763
|
}
|
|
1764
1764
|
finally {
|
|
1765
1765
|
await closeAdapterQuietly(adapter);
|
|
@@ -1886,7 +1886,7 @@ export class StateQL {
|
|
|
1886
1886
|
if (error instanceof AdapterExecutionError) {
|
|
1887
1887
|
throw stoppedStateQLError(error, true);
|
|
1888
1888
|
}
|
|
1889
|
-
throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable:
|
|
1889
|
+
throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: isTransientDatabaseError(error), executed: true });
|
|
1890
1890
|
}
|
|
1891
1891
|
finally {
|
|
1892
1892
|
await closeAdapterQuietly(adapter);
|
package/dist/src/util.d.ts
CHANGED
|
@@ -6,6 +6,7 @@ export declare function parseJson<T>(value: string, context: string, validate?:
|
|
|
6
6
|
export declare function isSqlParameters(value: unknown): value is SqlParameters;
|
|
7
7
|
export declare function isRows(value: unknown): value is Row[];
|
|
8
8
|
export declare function isColumns(value: unknown): value is Column[];
|
|
9
|
+
export declare function isRecord(value: unknown): value is Record<string, unknown>;
|
|
9
10
|
export declare function redact(value: string): string;
|
|
10
11
|
export declare function compactRows(rows: Row[], maxCellCharacters: number): Row[];
|
|
11
12
|
export declare function toJsonSafe<T>(value: T): T;
|
package/dist/src/util.js
CHANGED
|
@@ -49,7 +49,7 @@ export function isColumns(value) {
|
|
|
49
49
|
typeof column.name === "string" &&
|
|
50
50
|
typeof column.type === "string");
|
|
51
51
|
}
|
|
52
|
-
function isRecord(value) {
|
|
52
|
+
export function isRecord(value) {
|
|
53
53
|
return Boolean(value) && typeof value === "object" && !Array.isArray(value);
|
|
54
54
|
}
|
|
55
55
|
function corruptedState(context) {
|
package/docs/agents.md
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Agent guide
|
|
2
|
+
|
|
3
|
+
[StateQL](../README.md) · [Agents](agents.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
|
|
4
|
+
|
|
5
|
+
The minimum an agent needs to query a database with `stql`. Read the other pages
|
|
6
|
+
only for the topic at hand.
|
|
7
|
+
|
|
8
|
+
## Setup
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
export STQL_SESSION=task-42 # keeps handles and aliases across calls
|
|
12
|
+
stql connect ./app.sqlite # read-only by default
|
|
13
|
+
stql connect --env DATABASE_URL # remote URL from an environment variable
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Read
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
stql objects table --search user # find tables
|
|
20
|
+
stql object table users # table DDL
|
|
21
|
+
stql query "SELECT id, name FROM users WHERE status = ? ORDER BY id" --param active
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
```json
|
|
25
|
+
{"ok":true,"handle":"katcitg6un","total":333,"next_offset":5,"columns":["id","name"],"rows":[[2,"Ada"],[3,"Grace"],[5,"Linus"],[6,"Alan"],[8,"Edsger"]]}
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
- Rows are arrays in `columns` order. If rows have different keys, they stay
|
|
29
|
+
objects and `columns` is omitted.
|
|
30
|
+
- `next_offset` is present only when more rows exist.
|
|
31
|
+
- Null fields and false `cached`/`duplicate` flags are omitted.
|
|
32
|
+
- Long cells come back as `{"type":"text","length":N,"preview":"..."}`.
|
|
33
|
+
- `objects` uses the same `columns` + arrays shape.
|
|
34
|
+
- `rows`, `count`, and `columns` do not repeat the handle you passed.
|
|
35
|
+
- Result handles are short, stable aliases. Full `q_...` IDs also work.
|
|
36
|
+
- Writes return `handle`, `statement_type`, `affected_rows`, `status`, and
|
|
37
|
+
`state_version_after`.
|
|
38
|
+
|
|
39
|
+
## Reuse a result without querying again
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
stql rows katcitg6un --offset 5 --limit 20
|
|
43
|
+
stql count katcitg6un
|
|
44
|
+
stql filter katcitg6un "name LIKE ?" --param "A%"
|
|
45
|
+
stql export katcitg6un --output users.csv
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Save tokens
|
|
49
|
+
|
|
50
|
+
- Select only the columns you need, and add `ORDER BY` and `LIMIT`.
|
|
51
|
+
- Use `--preview-rows 0` when you need only the handle and `total`.
|
|
52
|
+
- Use `stql pipe` to run several commands in one call:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
printf '%s\n' \
|
|
56
|
+
'{"command":"query","sql":"SELECT id, email FROM users ORDER BY id","as":"users"}' \
|
|
57
|
+
'{"command":"count","handle":"users"}' | stql pipe
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Errors
|
|
61
|
+
|
|
62
|
+
Errors are `{"ok":false,"error":{"code":...,"message":...}}`. Follow
|
|
63
|
+
`suggested_action` or `override_flag` when present. Retry only when
|
|
64
|
+
`retryable` is true (lost connection, deadlock, lock timeout). SQL syntax errors
|
|
65
|
+
give the line, column, and nearby text. Do not replay a write that
|
|
66
|
+
returned `OUTCOME_UNKNOWN` until you have checked the database.
|
|
67
|
+
|
|
68
|
+
## Writes
|
|
69
|
+
|
|
70
|
+
Connect with `--read-write`. Use `stql exec` with `--idempotency-key KEY` for
|
|
71
|
+
retryable writes. Writes without `WHERE` need `--allow-unbounded`, and
|
|
72
|
+
destructive statements need `--allow-destructive`. See [write safety](writes.md).
|
package/docs/batch.md
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# Batch and pipes
|
|
2
|
+
|
|
3
|
+
[StateQL](../README.md) · [Agents](agents.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
|
|
4
|
+
|
|
5
|
+
`batch` reads a JSON array from a `.json` file or JSONL from a `.jsonl` file.
|
|
6
|
+
`pipe` reads JSONL from standard input. Commands run sequentially and stop on
|
|
7
|
+
the first error unless `--continue-on-error` is set. Output defaults to one
|
|
8
|
+
compact `agent` JSON object per line.
|
|
9
|
+
|
|
10
|
+
Pipe commands directly:
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
printf '%s\n' \
|
|
14
|
+
'{"command":"query","sql":"SELECT id, email FROM users ORDER BY id","as":"users"}' \
|
|
15
|
+
'{"command":"filter","handle":"users","where":"email LIKE ?","params":["%@example.com"],"as":"example_users"}' \
|
|
16
|
+
'{"command":"rows","handle":"example_users","limit":10}' |
|
|
17
|
+
stql pipe
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Or save a JSON array as `commands.json`:
|
|
21
|
+
|
|
22
|
+
```json
|
|
23
|
+
[
|
|
24
|
+
{
|
|
25
|
+
"command": "exec",
|
|
26
|
+
"sql": "UPDATE jobs SET claimed = 1 WHERE id = ?",
|
|
27
|
+
"params": [42],
|
|
28
|
+
"idempotency_key": "claim-job-42"
|
|
29
|
+
},
|
|
30
|
+
{
|
|
31
|
+
"command": "query",
|
|
32
|
+
"sql": "SELECT * FROM jobs WHERE id = ?",
|
|
33
|
+
"params": [42]
|
|
34
|
+
}
|
|
35
|
+
]
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
stql batch commands.json
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Batch fields use snake case. Supported command names match CLI paths, such as
|
|
43
|
+
`actor.show`, `actor.set-name`, `filter`, `transaction.begin`, `session.summary`,
|
|
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. Native MongoDB
|
|
46
|
+
batches use `mongo.query`, `mongo.exec`, or `mongo.plan` with the command object
|
|
47
|
+
in `mongo`; the same cache, replay, idempotency, safety, and timeout fields
|
|
48
|
+
apply. Database commands may set `timeout_ms`; otherwise they use the 30-second
|
|
49
|
+
default.
|