@fadhilp/stateql 0.13.3 → 0.15.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/agent-response.d.ts +3 -0
- package/dist/src/agent-response.js +213 -0
- package/dist/src/cli.js +12 -91
- package/dist/src/errors.d.ts +1 -0
- package/dist/src/errors.js +40 -0
- package/dist/src/index.d.ts +1 -0
- package/dist/src/index.js +1 -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 +24 -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)
|
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
import { isColumns, isRecord } from "./util.js";
|
|
2
|
+
const RESULT_COMMANDS = new Set(["query", "mongo.query", "redis.query", "filter", "show"]);
|
|
3
|
+
const FALSE_DEFAULT_KEYS = ["cached", "duplicate", "duplicate_override"];
|
|
4
|
+
const SHARED_HISTORY_KEYS = ["session_id", "actor_id", "actor_name", "origin"];
|
|
5
|
+
// The caller already holds the handle it passed to these commands.
|
|
6
|
+
const HANDLE_ECHO_COMMANDS = new Set(["rows", "count", "columns"]);
|
|
7
|
+
const WRITE_COMMANDS = new Set(["exec", "mongo.exec", "redis.exec", "apply"]);
|
|
8
|
+
const COMMAND_ALIASES = {
|
|
9
|
+
"objects.list": "objects",
|
|
10
|
+
"object.describe": "object",
|
|
11
|
+
};
|
|
12
|
+
/** Compacts a response for model context, as the CLI `agent` output mode does. */
|
|
13
|
+
export function agentResponse(result, commandName) {
|
|
14
|
+
const currentCommand = COMMAND_ALIASES[commandName] ?? commandName;
|
|
15
|
+
if (!result.ok)
|
|
16
|
+
return { ok: false, error: result.error };
|
|
17
|
+
if (!isRecord(result.data))
|
|
18
|
+
return { ok: true, data: result.data };
|
|
19
|
+
const data = { ...result.data };
|
|
20
|
+
const handleKey = primaryHandleKey(currentCommand);
|
|
21
|
+
let handle = handleKey && typeof data[handleKey] === "string" && data[handleKey]
|
|
22
|
+
? data[handleKey]
|
|
23
|
+
: undefined;
|
|
24
|
+
if (handle && handleKey)
|
|
25
|
+
delete data[handleKey];
|
|
26
|
+
const generatedAlias = data.display_alias;
|
|
27
|
+
delete data.display_alias;
|
|
28
|
+
// Generated aliases cannot be reassigned, so they are stable short result handles.
|
|
29
|
+
if (RESULT_COMMANDS.has(currentCommand) && typeof generatedAlias === "string") {
|
|
30
|
+
handle = generatedAlias;
|
|
31
|
+
if (data.alias === generatedAlias)
|
|
32
|
+
delete data.alias;
|
|
33
|
+
}
|
|
34
|
+
const isResult = RESULT_COMMANDS.has(currentCommand) &&
|
|
35
|
+
typeof data.rows === "number" &&
|
|
36
|
+
Array.isArray(data.preview);
|
|
37
|
+
if (isResult) {
|
|
38
|
+
data.total = data.rows;
|
|
39
|
+
data.next_offset = data.truncated ? data.preview.length : null;
|
|
40
|
+
data.rows = data.preview;
|
|
41
|
+
delete data.preview;
|
|
42
|
+
delete data.preview_count;
|
|
43
|
+
delete data.truncated;
|
|
44
|
+
delete data.storage;
|
|
45
|
+
delete data.state_version;
|
|
46
|
+
delete data.duplicate_of;
|
|
47
|
+
}
|
|
48
|
+
else if (currentCommand === "rows") {
|
|
49
|
+
delete data.offset;
|
|
50
|
+
delete data.limit;
|
|
51
|
+
delete data.returned;
|
|
52
|
+
delete data.truncated;
|
|
53
|
+
}
|
|
54
|
+
else if (currentCommand === "count" && typeof data.rows === "number") {
|
|
55
|
+
data.total = data.rows;
|
|
56
|
+
delete data.rows;
|
|
57
|
+
}
|
|
58
|
+
else if (WRITE_COMMANDS.has(currentCommand)) {
|
|
59
|
+
delete data.actor_id;
|
|
60
|
+
delete data.plan_id;
|
|
61
|
+
delete data.state_version_before;
|
|
62
|
+
if (typeof data.status === "string")
|
|
63
|
+
delete data.committed;
|
|
64
|
+
}
|
|
65
|
+
else if (currentCommand === "history" &&
|
|
66
|
+
Array.isArray(data.history) &&
|
|
67
|
+
data.history.every(isRecord)) {
|
|
68
|
+
Object.assign(data, compactHistory(data.history));
|
|
69
|
+
}
|
|
70
|
+
else if (currentCommand === "inspect" && Array.isArray(data.columns)) {
|
|
71
|
+
data.columns = data.columns.map(withoutFalsePrimaryKey);
|
|
72
|
+
}
|
|
73
|
+
else if (currentCommand === "capabilities" && isRecord(data.features)) {
|
|
74
|
+
const features = data.features;
|
|
75
|
+
data.features = Object.keys(features).filter((key) => features[key] === true);
|
|
76
|
+
}
|
|
77
|
+
else if (currentCommand === "objects" &&
|
|
78
|
+
Array.isArray(data.objects) &&
|
|
79
|
+
data.objects.every(isRecord)) {
|
|
80
|
+
const objects = data.objects.every(hasDerivedIdentity)
|
|
81
|
+
? data.objects.map(withoutIdentity)
|
|
82
|
+
: data.objects;
|
|
83
|
+
const table = columnarRows(objects, undefined);
|
|
84
|
+
delete data.objects;
|
|
85
|
+
Object.assign(data, { columns: table.columns, objects: table.rows });
|
|
86
|
+
}
|
|
87
|
+
else if (currentCommand === "object" &&
|
|
88
|
+
isRecord(data.object) &&
|
|
89
|
+
hasDerivedIdentity(data.object)) {
|
|
90
|
+
data.object = withoutIdentity(data.object);
|
|
91
|
+
}
|
|
92
|
+
if (isResult || (currentCommand === "rows" && Array.isArray(data.rows))) {
|
|
93
|
+
const table = columnarRows(data.rows, data.columns);
|
|
94
|
+
delete data.columns;
|
|
95
|
+
delete data.rows;
|
|
96
|
+
Object.assign(data, table);
|
|
97
|
+
}
|
|
98
|
+
const hasMoreRows = data.next_offset !== null && data.next_offset !== undefined;
|
|
99
|
+
const warnings = result.warnings.filter((warning) => warning.code !== "NON_DETERMINISTIC_PAGINATION" || hasMoreRows);
|
|
100
|
+
dropFalseDefaults(data);
|
|
101
|
+
for (const key of ["ok", "error", "handle", "warnings"]) {
|
|
102
|
+
if (!(key in data))
|
|
103
|
+
continue;
|
|
104
|
+
data[`data_${key}`] = data[key];
|
|
105
|
+
delete data[key];
|
|
106
|
+
}
|
|
107
|
+
return {
|
|
108
|
+
ok: true,
|
|
109
|
+
...(handle && !HANDLE_ECHO_COMMANDS.has(currentCommand) ? { handle } : {}),
|
|
110
|
+
...withoutNulls(data),
|
|
111
|
+
...(warnings.length ? { warnings } : {}),
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
// Rows with differing keys (e.g. MongoDB documents) stay objects so missing and null remain distinct.
|
|
115
|
+
function columnarRows(rows, columns) {
|
|
116
|
+
const names = isColumns(columns)
|
|
117
|
+
? columns.map((column) => column.name)
|
|
118
|
+
: Object.keys(rows[0] ?? {});
|
|
119
|
+
if (names.length === 0)
|
|
120
|
+
return { rows };
|
|
121
|
+
const nameSet = new Set(names);
|
|
122
|
+
const hasColumnKeys = (row) => {
|
|
123
|
+
if (!isRecord(row))
|
|
124
|
+
return false;
|
|
125
|
+
const keys = Object.keys(row);
|
|
126
|
+
return keys.length === names.length && keys.every((key) => nameSet.has(key));
|
|
127
|
+
};
|
|
128
|
+
if (!rows.every(hasColumnKeys))
|
|
129
|
+
return { rows };
|
|
130
|
+
return {
|
|
131
|
+
columns: names,
|
|
132
|
+
rows: rows.map((row) => names.map((name) => row[name])),
|
|
133
|
+
};
|
|
134
|
+
}
|
|
135
|
+
function compactHistory(entries) {
|
|
136
|
+
const shared = {};
|
|
137
|
+
for (const key of SHARED_HISTORY_KEYS) {
|
|
138
|
+
const value = entries[0]?.[key];
|
|
139
|
+
if (value === undefined)
|
|
140
|
+
continue;
|
|
141
|
+
if (entries.every((entry) => entry[key] === value))
|
|
142
|
+
shared[key] = value;
|
|
143
|
+
}
|
|
144
|
+
const history = entries.map((entry) => {
|
|
145
|
+
const compact = withoutNulls(entry);
|
|
146
|
+
dropFalseDefaults(compact);
|
|
147
|
+
for (const key of Object.keys(shared))
|
|
148
|
+
delete compact[key];
|
|
149
|
+
return compact;
|
|
150
|
+
});
|
|
151
|
+
return { ...shared, history };
|
|
152
|
+
}
|
|
153
|
+
function hasDerivedIdentity(object) {
|
|
154
|
+
const qualifiedName = typeof object.schema === "string"
|
|
155
|
+
? `${object.schema}.${String(object.name)}`
|
|
156
|
+
: object.name;
|
|
157
|
+
return object.identity === undefined || object.identity === qualifiedName;
|
|
158
|
+
}
|
|
159
|
+
function withoutIdentity(object) {
|
|
160
|
+
const compact = { ...object };
|
|
161
|
+
delete compact.identity;
|
|
162
|
+
return compact;
|
|
163
|
+
}
|
|
164
|
+
function withoutFalsePrimaryKey(column) {
|
|
165
|
+
if (!isRecord(column) || column.primary_key !== false)
|
|
166
|
+
return column;
|
|
167
|
+
const compact = { ...column };
|
|
168
|
+
delete compact.primary_key;
|
|
169
|
+
return compact;
|
|
170
|
+
}
|
|
171
|
+
function dropFalseDefaults(record) {
|
|
172
|
+
for (const key of FALSE_DEFAULT_KEYS) {
|
|
173
|
+
if (record[key] === false)
|
|
174
|
+
delete record[key];
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
function withoutNulls(record) {
|
|
178
|
+
return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== null));
|
|
179
|
+
}
|
|
180
|
+
function primaryHandleKey(currentCommand) {
|
|
181
|
+
const keys = {
|
|
182
|
+
query: "result_id",
|
|
183
|
+
"mongo.query": "result_id",
|
|
184
|
+
"redis.query": "result_id",
|
|
185
|
+
filter: "result_id",
|
|
186
|
+
show: "result_id",
|
|
187
|
+
rows: "result_id",
|
|
188
|
+
count: "result_id",
|
|
189
|
+
columns: "result_id",
|
|
190
|
+
export: "result_id",
|
|
191
|
+
alias: "result_id",
|
|
192
|
+
"alias.set": "result_id",
|
|
193
|
+
exec: "operation_id",
|
|
194
|
+
"mongo.exec": "operation_id",
|
|
195
|
+
"redis.exec": "operation_id",
|
|
196
|
+
receipt: "operation_id",
|
|
197
|
+
apply: "operation_id",
|
|
198
|
+
plan: "plan_id",
|
|
199
|
+
"mongo.plan": "plan_id",
|
|
200
|
+
"redis.plan": "plan_id",
|
|
201
|
+
connect: "connection_id",
|
|
202
|
+
transaction: "transaction_id",
|
|
203
|
+
"transaction.begin": "transaction_id",
|
|
204
|
+
"transaction.status": "transaction_id",
|
|
205
|
+
"transaction.commit": "transaction_id",
|
|
206
|
+
"transaction.rollback": "transaction_id",
|
|
207
|
+
session: "session_id",
|
|
208
|
+
"session.start": "session_id",
|
|
209
|
+
"session.show": "session_id",
|
|
210
|
+
"session.close": "session_id",
|
|
211
|
+
};
|
|
212
|
+
return keys[currentCommand];
|
|
213
|
+
}
|
package/dist/src/cli.js
CHANGED
|
@@ -6,6 +6,7 @@ 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 { agentResponse } from "./agent-response.js";
|
|
9
10
|
const parsed = parseArgs({
|
|
10
11
|
allowPositionals: true,
|
|
11
12
|
strict: true,
|
|
@@ -21,6 +22,7 @@ const parsed = parseArgs({
|
|
|
21
22
|
"params-file": { type: "string" },
|
|
22
23
|
cache: { type: "string" },
|
|
23
24
|
"preview-rows": { type: "string" },
|
|
25
|
+
"max-cell-characters": { type: "string" },
|
|
24
26
|
replay: { type: "boolean" },
|
|
25
27
|
"idempotency-key": { type: "string" },
|
|
26
28
|
"allow-unbounded": { type: "boolean" },
|
|
@@ -51,7 +53,7 @@ if (values.version) {
|
|
|
51
53
|
console.log(packageVersion());
|
|
52
54
|
process.exit(0);
|
|
53
55
|
}
|
|
54
|
-
if (values.help || !command) {
|
|
56
|
+
if (values.help || !command || command === "help") {
|
|
55
57
|
console.log(helpText());
|
|
56
58
|
process.exit(0);
|
|
57
59
|
}
|
|
@@ -71,6 +73,9 @@ const stateql = new StateQL({
|
|
|
71
73
|
...(values["result-ttl-seconds"] === undefined
|
|
72
74
|
? {}
|
|
73
75
|
: { resultTtlSeconds: Number(values["result-ttl-seconds"]) }),
|
|
76
|
+
...(values["max-cell-characters"] === undefined
|
|
77
|
+
? {}
|
|
78
|
+
: { maxCellCharacters: Number(values["max-cell-characters"]) }),
|
|
74
79
|
signal: abortController.signal,
|
|
75
80
|
});
|
|
76
81
|
try {
|
|
@@ -94,8 +99,8 @@ async function runSingle() {
|
|
|
94
99
|
catch (error) {
|
|
95
100
|
response = cliFailure(error);
|
|
96
101
|
}
|
|
97
|
-
const responseCommand = command === "mongo" && subcommand
|
|
98
|
-
?
|
|
102
|
+
const responseCommand = (command === "mongo" || command === "redis") && subcommand
|
|
103
|
+
? `${command}.${subcommand}`
|
|
99
104
|
: command ?? "";
|
|
100
105
|
print(response, mode, responseCommand);
|
|
101
106
|
if (!response.ok)
|
|
@@ -526,98 +531,11 @@ function print(result, mode, currentCommand) {
|
|
|
526
531
|
return;
|
|
527
532
|
}
|
|
528
533
|
if (mode === "agent") {
|
|
529
|
-
console.log(JSON.stringify(
|
|
534
|
+
console.log(JSON.stringify(agentResponse(result, currentCommand)));
|
|
530
535
|
return;
|
|
531
536
|
}
|
|
532
537
|
console.log(mode === "json" ? JSON.stringify(result, null, 2) : JSON.stringify(result));
|
|
533
538
|
}
|
|
534
|
-
function toAgentResponse(result, currentCommand) {
|
|
535
|
-
if (!result.ok)
|
|
536
|
-
return { ok: false, error: result.error };
|
|
537
|
-
if (!result.data ||
|
|
538
|
-
typeof result.data !== "object" ||
|
|
539
|
-
Array.isArray(result.data)) {
|
|
540
|
-
return { ok: true, data: result.data };
|
|
541
|
-
}
|
|
542
|
-
const data = { ...result.data };
|
|
543
|
-
const handleKey = primaryHandleKey(currentCommand);
|
|
544
|
-
const handle = handleKey && typeof data[handleKey] === "string" && data[handleKey]
|
|
545
|
-
? data[handleKey]
|
|
546
|
-
: undefined;
|
|
547
|
-
if (handle && handleKey)
|
|
548
|
-
delete data[handleKey];
|
|
549
|
-
if ((currentCommand === "query" ||
|
|
550
|
-
currentCommand === "mongo.query" ||
|
|
551
|
-
currentCommand === "filter" ||
|
|
552
|
-
currentCommand === "show") &&
|
|
553
|
-
typeof data.rows === "number" &&
|
|
554
|
-
Array.isArray(data.preview)) {
|
|
555
|
-
const total = data.rows;
|
|
556
|
-
const rows = data.preview;
|
|
557
|
-
const truncated = Boolean(data.truncated);
|
|
558
|
-
data.rows = rows;
|
|
559
|
-
data.total = total;
|
|
560
|
-
data.next_offset = truncated ? rows.length : null;
|
|
561
|
-
delete data.preview;
|
|
562
|
-
delete data.preview_count;
|
|
563
|
-
delete data.columns;
|
|
564
|
-
delete data.storage;
|
|
565
|
-
delete data.state_version;
|
|
566
|
-
delete data.duplicate_of;
|
|
567
|
-
}
|
|
568
|
-
else if (currentCommand === "rows") {
|
|
569
|
-
delete data.offset;
|
|
570
|
-
delete data.limit;
|
|
571
|
-
delete data.returned;
|
|
572
|
-
}
|
|
573
|
-
else if (currentCommand === "count" && typeof data.rows === "number") {
|
|
574
|
-
data.total = data.rows;
|
|
575
|
-
delete data.rows;
|
|
576
|
-
}
|
|
577
|
-
for (const key of ["ok", "error", "handle", "warnings"]) {
|
|
578
|
-
if (!(key in data))
|
|
579
|
-
continue;
|
|
580
|
-
data[`data_${key}`] = data[key];
|
|
581
|
-
delete data[key];
|
|
582
|
-
}
|
|
583
|
-
return {
|
|
584
|
-
ok: true,
|
|
585
|
-
...(handle ? { handle } : {}),
|
|
586
|
-
...data,
|
|
587
|
-
...(result.warnings.length ? { warnings: result.warnings } : {}),
|
|
588
|
-
};
|
|
589
|
-
}
|
|
590
|
-
function primaryHandleKey(currentCommand) {
|
|
591
|
-
const keys = {
|
|
592
|
-
query: "result_id",
|
|
593
|
-
"mongo.query": "result_id",
|
|
594
|
-
filter: "result_id",
|
|
595
|
-
show: "result_id",
|
|
596
|
-
rows: "result_id",
|
|
597
|
-
count: "result_id",
|
|
598
|
-
columns: "result_id",
|
|
599
|
-
export: "result_id",
|
|
600
|
-
alias: "result_id",
|
|
601
|
-
"alias.set": "result_id",
|
|
602
|
-
exec: "operation_id",
|
|
603
|
-
"mongo.exec": "operation_id",
|
|
604
|
-
receipt: "operation_id",
|
|
605
|
-
apply: "operation_id",
|
|
606
|
-
plan: "plan_id",
|
|
607
|
-
"mongo.plan": "plan_id",
|
|
608
|
-
connect: "connection_id",
|
|
609
|
-
transaction: "transaction_id",
|
|
610
|
-
"transaction.begin": "transaction_id",
|
|
611
|
-
"transaction.status": "transaction_id",
|
|
612
|
-
"transaction.commit": "transaction_id",
|
|
613
|
-
"transaction.rollback": "transaction_id",
|
|
614
|
-
session: "session_id",
|
|
615
|
-
"session.start": "session_id",
|
|
616
|
-
"session.show": "session_id",
|
|
617
|
-
"session.close": "session_id",
|
|
618
|
-
};
|
|
619
|
-
return keys[currentCommand];
|
|
620
|
-
}
|
|
621
539
|
function cliFailure(error) {
|
|
622
540
|
return {
|
|
623
541
|
ok: false,
|
|
@@ -674,10 +592,13 @@ Commands:
|
|
|
674
592
|
|
|
675
593
|
SQL parameters: --params JSON, repeated --param VALUE, or --params-file FILE.
|
|
676
594
|
Query preview: --preview-rows N (default: 5, maximum: 200).
|
|
595
|
+
Long cells: --max-cell-characters N (default: 200); use export for full values.
|
|
677
596
|
Deadline: --timeout-ms N (default: 30000). Ctrl+C cancels database work.
|
|
678
597
|
Credential refs require a trusted host CredentialResolver; the standalone CLI cannot resolve them.
|
|
679
598
|
State: --max-state-bytes N, --cache-ttl-seconds N, --result-ttl-seconds N.
|
|
680
599
|
Output: --output agent|json|jsonl|text|silent (default: agent).
|
|
600
|
+
Agent rows: arrays in "columns" order (objects when shapes differ). next_offset only when more rows exist.
|
|
601
|
+
Agent output omits null fields and false cached/duplicate flags. Guide: docs/agents.md.
|
|
681
602
|
Batch/pipe accept JSON array files or JSONL streams. Stop on first error.`;
|
|
682
603
|
}
|
|
683
604
|
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/index.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
export { StateQL } from "./stateql.js";
|
|
2
|
+
export { agentResponse } from "./agent-response.js";
|
|
2
3
|
export { CredentialResolutionError, StateQLError, exitCodeFor, } from "./errors.js";
|
|
3
4
|
export type { CredentialResolutionFailure } from "./errors.js";
|
|
4
5
|
export type { TableChange, TableIdentity, TableUpdate } from "./table-editor.js";
|
package/dist/src/index.js
CHANGED
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);
|