@fadhilp/stateql 0.14.0 → 0.15.1

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 CHANGED
@@ -40,11 +40,23 @@ stql filter katcitg6un "name LIKE ?" --param "A%"
40
40
  stql export katcitg6un --output users.csv
41
41
  ```
42
42
 
43
+ ## Agent skill
44
+
45
+ `skills/stateql` is an [Agent Skill](https://agentskills.io) that teaches coding
46
+ agents to use `stql` safely and with few tokens. Copy the folder into your
47
+ agent's skills directory, for example for Claude Code:
48
+
49
+ ```bash
50
+ cp -r "$(npm root -g)/@fadhilp/stateql/skills/stateql" ~/.claude/skills/
51
+ ```
52
+
53
+ Use `.claude/skills/` inside a project to share it with your team.
54
+
43
55
  ## Documentation
44
56
 
45
57
  | Page | Contents |
46
58
  | --- | --- |
47
- | [Agent guide](docs/agents.md) | The short version for agents: connect, query, reuse, save tokens |
59
+ | [Agent skill](skills/stateql/SKILL.md) | Rules, workflow, response format, quoting, and errors for coding agents |
48
60
  | [Connections](docs/connections.md) | Targets, environment credentials, profiles |
49
61
  | [CLI reference](docs/cli.md) | Commands, parameters, catalog, output modes, deadlines |
50
62
  | [Results and state](docs/results.md) | Sessions, actors, limits, caching, local filtering |
@@ -0,0 +1,3 @@
1
+ import type { Response } from "./types.js";
2
+ /** Compacts a response for model context, as the CLI `agent` output mode does. */
3
+ export declare function agentResponse(result: Response<unknown>, commandName: string): Record<string, unknown>;
@@ -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,13 +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 { 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
+ import { agentResponse } from "./agent-response.js";
16
10
  const parsed = parseArgs({
17
11
  allowPositionals: true,
18
12
  strict: true,
@@ -105,8 +99,8 @@ async function runSingle() {
105
99
  catch (error) {
106
100
  response = cliFailure(error);
107
101
  }
108
- const responseCommand = command === "mongo" && subcommand
109
- ? `mongo.${subcommand}`
102
+ const responseCommand = (command === "mongo" || command === "redis") && subcommand
103
+ ? `${command}.${subcommand}`
110
104
  : command ?? "";
111
105
  print(response, mode, responseCommand);
112
106
  if (!response.ok)
@@ -412,7 +406,7 @@ function parseParameters(value, values, file) {
412
406
  : value;
413
407
  let parsedValue;
414
408
  try {
415
- parsedValue = JSON.parse(json);
409
+ parsedValue = JSON.parse(withoutBom(json));
416
410
  }
417
411
  catch {
418
412
  throw new Error(`Invalid JSON from ${file ? "--params-file" : "--params"}. ` +
@@ -453,6 +447,10 @@ async function* readBatchCommands(source) {
453
447
  yield parseBatchCommand(parseBatchJson(line, `line ${lineNumber}`), `line ${lineNumber}`);
454
448
  }
455
449
  }
450
+ // PowerShell pipes and Out-File/Notepad files can start with a UTF-8 BOM, which JSON.parse rejects.
451
+ function withoutBom(value) {
452
+ return value.startsWith("") ? value.slice(1) : value;
453
+ }
456
454
  function parseBatchCommand(value, location) {
457
455
  if (!value ||
458
456
  typeof value !== "object" ||
@@ -463,7 +461,7 @@ function parseBatchCommand(value, location) {
463
461
  }
464
462
  function parseBatchJson(value, location) {
465
463
  try {
466
- return JSON.parse(value);
464
+ return JSON.parse(withoutBom(value));
467
465
  }
468
466
  catch {
469
467
  throw new Error(`Invalid JSON at ${location}.`);
@@ -537,208 +535,11 @@ function print(result, mode, currentCommand) {
537
535
  return;
538
536
  }
539
537
  if (mode === "agent") {
540
- console.log(JSON.stringify(toAgentResponse(result, currentCommand)));
538
+ console.log(JSON.stringify(agentResponse(result, currentCommand)));
541
539
  return;
542
540
  }
543
541
  console.log(mode === "json" ? JSON.stringify(result, null, 2) : JSON.stringify(result));
544
542
  }
545
- function toAgentResponse(result, currentCommand) {
546
- if (!result.ok)
547
- return { ok: false, error: result.error };
548
- if (!isRecord(result.data))
549
- return { ok: true, data: result.data };
550
- const data = { ...result.data };
551
- const handleKey = primaryHandleKey(currentCommand);
552
- let handle = handleKey && typeof data[handleKey] === "string" && data[handleKey]
553
- ? data[handleKey]
554
- : undefined;
555
- if (handle && handleKey)
556
- delete data[handleKey];
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) &&
566
- typeof data.rows === "number" &&
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;
572
- delete data.preview;
573
- delete data.preview_count;
574
- delete data.truncated;
575
- delete data.storage;
576
- delete data.state_version;
577
- delete data.duplicate_of;
578
- }
579
- else if (currentCommand === "rows") {
580
- delete data.offset;
581
- delete data.limit;
582
- delete data.returned;
583
- delete data.truncated;
584
- }
585
- else if (currentCommand === "count" && typeof data.rows === "number") {
586
- data.total = data.rows;
587
- delete data.rows;
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);
632
- for (const key of ["ok", "error", "handle", "warnings"]) {
633
- if (!(key in data))
634
- continue;
635
- data[`data_${key}`] = data[key];
636
- delete data[key];
637
- }
638
- return {
639
- ok: true,
640
- ...(handle && !HANDLE_ECHO_COMMANDS.has(currentCommand) ? { handle } : {}),
641
- ...withoutNulls(data),
642
- ...(warnings.length ? { warnings } : {}),
643
- };
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
- }
711
- function primaryHandleKey(currentCommand) {
712
- const keys = {
713
- query: "result_id",
714
- "mongo.query": "result_id",
715
- filter: "result_id",
716
- show: "result_id",
717
- rows: "result_id",
718
- count: "result_id",
719
- columns: "result_id",
720
- export: "result_id",
721
- alias: "result_id",
722
- "alias.set": "result_id",
723
- exec: "operation_id",
724
- "mongo.exec": "operation_id",
725
- receipt: "operation_id",
726
- apply: "operation_id",
727
- plan: "plan_id",
728
- "mongo.plan": "plan_id",
729
- connect: "connection_id",
730
- transaction: "transaction_id",
731
- "transaction.begin": "transaction_id",
732
- "transaction.status": "transaction_id",
733
- "transaction.commit": "transaction_id",
734
- "transaction.rollback": "transaction_id",
735
- session: "session_id",
736
- "session.start": "session_id",
737
- "session.show": "session_id",
738
- "session.close": "session_id",
739
- };
740
- return keys[currentCommand];
741
- }
742
543
  function cliFailure(error) {
743
544
  return {
744
545
  ok: false,
@@ -801,7 +602,7 @@ Credential refs require a trusted host CredentialResolver; the standalone CLI ca
801
602
  State: --max-state-bytes N, --cache-ttl-seconds N, --result-ttl-seconds N.
802
603
  Output: --output agent|json|jsonl|text|silent (default: agent).
803
604
  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.
605
+ Agent output omits null fields and false cached/duplicate flags. Agent skill: skills/stateql/SKILL.md.
805
606
  Batch/pipe accept JSON array files or JSONL streams. Stop on first error.`;
806
607
  }
807
608
  function packageVersion() {
@@ -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
@@ -1,2 +1,3 @@
1
1
  export { StateQL } from "./stateql.js";
2
+ export { agentResponse } from "./agent-response.js";
2
3
  export { CredentialResolutionError, StateQLError, exitCodeFor, } from "./errors.js";
package/docs/batch.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Batch and pipes
2
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)
3
+ [StateQL](../README.md) · [Agent skill](../skills/stateql/SKILL.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
4
4
 
5
5
  `batch` reads a JSON array from a `.json` file or JSONL from a `.jsonl` file.
6
6
  `pipe` reads JSONL from standard input. Commands run sequentially and stop on
package/docs/cli.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # CLI reference
2
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)
3
+ [StateQL](../README.md) · [Agent skill](../skills/stateql/SKILL.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
4
4
 
5
5
  ```bash
6
6
  stql connect <target> [--name NAME] [--read-only|--read-write]
@@ -1,6 +1,6 @@
1
1
  # Connections and profiles
2
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)
3
+ [StateQL](../README.md) · [Agent skill](../skills/stateql/SKILL.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
4
4
 
5
5
  A connection accepts exactly one source: a direct target, `--env`,
6
6
  `--credential-ref`, or `--profile`. Library and batch callers may additionally
package/docs/databases.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Database support
2
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)
3
+ [StateQL](../README.md) · [Agent skill](../skills/stateql/SKILL.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
4
4
 
5
5
  - [Driver notes](#driver-notes)
6
6
  - [SQL statement support](#sql-statement-support)
package/docs/library.md CHANGED
@@ -1,9 +1,10 @@
1
1
  # TypeScript library
2
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)
3
+ [StateQL](../README.md) · [Agent skill](../skills/stateql/SKILL.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
4
4
 
5
5
  - [Getting started](#getting-started)
6
6
  - [Responses and command context](#responses-and-command-context)
7
+ - [Compact responses for model context](#compact-responses-for-model-context)
7
8
  - [Actor workspaces](#actor-workspaces)
8
9
  - [Credential resolution](#credential-resolution)
9
10
  - [Safe profile updates](#safe-profile-updates)
@@ -94,6 +95,23 @@ direct calls and `executeCommand(command)` calls are recorded as `legacy`.
94
95
  `BatchCommand` cannot attribute the command. `batch` accepts the same trusted
95
96
  context as `options.executionContext` for all commands in that batch.
96
97
 
98
+ ### Compact responses for model context
99
+
100
+ When a response goes into a model's context, pass it through `agentResponse`
101
+ with the batch command name. It returns the same compact shape as the CLI
102
+ `agent` output mode (see [output modes](cli.md#output-modes)). Keep the full
103
+ response for application logic.
104
+
105
+ ```ts
106
+ import { agentResponse } from "@fadhilp/stateql";
107
+
108
+ const response = await stateql.executeCommand(command, { origin: "model" });
109
+ const forModel = JSON.stringify(agentResponse(response, command.command));
110
+ ```
111
+
112
+ `objects.list` and `object.describe` are accepted as names for catalog
113
+ responses from `listObjects` and `describeObject`.
114
+
97
115
  ## Actor workspaces
98
116
 
99
117
  `StateQL.forWorkspace(...)` is a trusted-host primitive that atomically creates
package/docs/results.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Durable state and result reuse
2
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)
3
+ [StateQL](../README.md) · [Agent skill](../skills/stateql/SKILL.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
4
4
 
5
5
  State metadata lives under `STQL_HOME`, or the platform data directory when
6
6
  unset. StateQL keeps connections, sessions, handles, aliases, cache entries,
package/docs/writes.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Write safety
2
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)
3
+ [StateQL](../README.md) · [Agent skill](../skills/stateql/SKILL.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
4
4
 
5
5
  Writes require a read-write connection. Destructive and unbounded SQL/MongoDB
6
6
  operations require `--allow-destructive` and `--allow-unbounded`, respectively.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fadhilp/stateql",
3
- "version": "0.14.0",
3
+ "version": "0.15.1",
4
4
  "description": "Stateful, agent-oriented database CLI for safe result reuse",
5
5
  "repository": {
6
6
  "type": "git",
@@ -22,6 +22,7 @@
22
22
  "dist/src",
23
23
  "README.md",
24
24
  "docs",
25
+ "skills",
25
26
  "LICENSE"
26
27
  ],
27
28
  "scripts": {
@@ -0,0 +1,166 @@
1
+ ---
2
+ name: stateql
3
+ description: Query, inspect, and safely change SQLite, PostgreSQL, MySQL, MongoDB, and Redis databases with the `stql` CLI, which stores each result behind a short handle and returns compact JSON. Use when the user asks to look at a database schema, run SQL, read or page through rows, count or filter query results, export data, or make a guarded write.
4
+ ---
5
+
6
+ # StateQL (`stql`)
7
+
8
+ `stql` runs a query once, stores the full result locally, and returns a short
9
+ preview plus a handle. Page, filter, count, and export from the handle without
10
+ running the query again. Output is one line of JSON per command.
11
+
12
+ If `stql --version` fails, ask the user before installing
13
+ `npm install -g @fadhilp/stateql` (Node.js 22.16+).
14
+
15
+ ## Rules
16
+
17
+ 1. Set a session once per task: `export STQL_SESSION=<short-task-name>`
18
+ (PowerShell: `$env:STQL_SESSION = "<name>"`). Without it, every task shares
19
+ the `default` session.
20
+ 2. Connect read-only (the default). Use `--read-write` only when the user asked
21
+ for a change.
22
+ 3. Never add `--allow-destructive`, `--allow-unbounded`, or `--replay` unless the
23
+ user explicitly approved that operation. They are approvals, not fixes.
24
+ 4. Never put a password in a command. Remote URLs go in an environment variable
25
+ that you pass with `--env`.
26
+ 5. Pass values as parameters (`--param`), never by building SQL strings.
27
+ 6. Do not rerun a query to see more rows. Use its handle.
28
+
29
+ ## Connect
30
+
31
+ ```bash
32
+ stql status # already connected in this session?
33
+ stql connect ./app.sqlite # SQLite path, read-only
34
+ stql connect --env DATABASE_URL # postgres://, mysql://, mongodb://, redis:// URL in the variable
35
+ stql connect --env DATABASE_URL --read-write # only for requested changes
36
+ ```
37
+
38
+ `status` without a `connection` field means no connection is open.
39
+
40
+ ## Read workflow
41
+
42
+ 1. Find objects: `stql objects table --search order`
43
+ 2. Read the shape: `stql object table orders` (returns the DDL or column list)
44
+ 3. Query only the columns you need, with `ORDER BY`:
45
+ `stql query 'SELECT id, total FROM orders WHERE status = $1 ORDER BY id' --param paid`
46
+ 4. Read the response (see below). `total` is the full row count, so you do not
47
+ need a separate `COUNT(*)`.
48
+ 5. More rows: `stql rows <handle> --offset <next_offset> --limit 50`
49
+ (default 20, maximum 1000).
50
+ 6. Narrow down: `stql filter <handle> 'CAST(total AS REAL) > ?' --param 100`.
51
+ This runs locally on the stored rows in SQLite syntax, always with `?`, and
52
+ returns a new handle. PostgreSQL `numeric`/`bigint` and MySQL `DECIMAL` values
53
+ are stored as strings (`"7.50"`), and SQLite treats every string as greater
54
+ than every number, so `total > ?` silently matches all rows. Wrap such
55
+ 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`).
57
+
58
+ Use `--preview-rows N` (0 to 200) on `query` to change the preview size. Use
59
+ `--cache bypass` when data may have changed outside this session; writes made
60
+ through `stql` invalidate the cache automatically.
61
+
62
+ ## Response format
63
+
64
+ ```json
65
+ {"ok":true,"handle":"katcitg6un","total":331,"next_offset":5,"columns":["id","name"],"rows":[[2,"Ada"],[3,"Grace"],[5,"Linus"],[6,"Alan"],[8,"Edsger"]]}
66
+ ```
67
+
68
+ | Field | Meaning |
69
+ | --- | --- |
70
+ | `handle` | Stable result handle. Pass it to `rows`, `filter`, `count`, `columns`, `show`, `export`. |
71
+ | `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
+ | `total` | Rows in the stored result. |
73
+ | `next_offset` | Present only when more rows exist. Absent means you have every row. |
74
+ | `alias` | Present only when you named the result (batch `as`). |
75
+ | `warnings` | For example `NON_DETERMINISTIC_PAGINATION`: add `ORDER BY` before paging. |
76
+
77
+ - Exact numbers keep their precision as strings: PostgreSQL `numeric` and
78
+ `bigint`, MySQL `DECIMAL`.
79
+ - A long cell comes back as `{"type":"text","length":20000,"preview":"..."}`.
80
+ Use `--max-cell-characters N` or `export` for the full value.
81
+ - Null fields and false `cached`/`duplicate` flags are omitted.
82
+ - `rows`, `count`, and `columns` do not repeat the handle you passed.
83
+
84
+ ## Placeholders and shell quoting
85
+
86
+ | Database | Placeholders |
87
+ | --- | --- |
88
+ | SQLite, MySQL | `?` |
89
+ | PostgreSQL | `$1`, `$2`, ... |
90
+ | `filter` predicates (all databases) | `?` |
91
+
92
+ - Put SQL in single quotes. In bash and PowerShell, `"$1"` expands to an empty
93
+ string and breaks the query.
94
+ - Use parameters instead of string literals, so you do not need quotes inside
95
+ quotes: `--param 'Ada Lovelace'`.
96
+ - **Windows PowerShell 5.1** removes the double quotes inside JSON arguments, so
97
+ `--params '[1]'` is fine but `stql redis query '{"command":"GET"}'` breaks.
98
+ Send JSON on standard input instead: `'<one JSON command>' | stql pipe` (see
99
+ below), or escape every inner quote as `\"`.
100
+
101
+ ## Several steps in one call
102
+
103
+ `stql pipe` reads one JSON command per line and prints one response per line.
104
+ It stops at the first error unless you pass `--continue-on-error`. Fields use
105
+ snake_case; `as` gives a result a name that later lines can use.
106
+
107
+ ```bash
108
+ printf '%s\n' \
109
+ '{"command":"query","sql":"SELECT id, email FROM users WHERE status = $1 ORDER BY id","params":["active"],"as":"active"}' \
110
+ '{"command":"filter","handle":"active","where":"email LIKE ?","params":["%@example.com"],"as":"example"}' \
111
+ '{"command":"rows","handle":"example","offset":5,"limit":20}' | stql pipe
112
+ ```
113
+
114
+ Command names match the CLI: `query`, `filter`, `rows`, `count`, `columns`,
115
+ `show`, `export`, `exec`, `plan`, `apply`, `objects.list`, `object.describe`,
116
+ `inspect`, `mongo.query`, `redis.query`, `transaction.begin`, and so on.
117
+ `stql batch commands.json` runs a JSON array from a file.
118
+
119
+ ## Errors
120
+
121
+ Errors look like `{"ok":false,"error":{"code":"...","message":"...","retryable":false,"executed":false}}`.
122
+ Retry only when `retryable` is `true`. `executed:false` means nothing ran.
123
+
124
+ | Code | What to do |
125
+ | --- | --- |
126
+ | `INVALID_SQL` | Fix the SQL at the reported line and column. Check the placeholder style. |
127
+ | `QUERY_FAILED` | Read the database message (missing table or column, type error). Retry only if `retryable`. |
128
+ | `READ_ONLY_CONNECTION` | Ask the user before you reconnect with `--read-write`. |
129
+ | `UNBOUNDED_MUTATION` | Add a `WHERE` clause. Use `--allow-unbounded` only with user approval. |
130
+ | `DESTRUCTIVE_OPERATION_BLOCKED` | `DELETE`, `DROP`, `ALTER`, `TRUNCATE`, and `REPLACE` need user approval, then `--allow-destructive`. |
131
+ | `POTENTIAL_DUPLICATE_WRITE` | The same write already ran (`previous_operation_id`). Do not use `--replay` unless the user wants it to run again. |
132
+ | `OUTCOME_UNKNOWN` | The write may or may not have committed. Check the data with a query before anything else. |
133
+ | `OUTPUT_LIMIT_EXCEEDED` | Results are capped at 10,000 rows and 16 MiB. Add `WHERE`/`LIMIT` or select fewer columns; page `rows` in steps of at most 1000. |
134
+ | `RESULT_NOT_FOUND`, `RESULT_EXPIRED` | Wrong session or the result expired (24 h). Run the query again. |
135
+ | `STALE_PLAN` | Data changed after `plan`. Create a new plan. |
136
+ | `TRANSACTION_FAILED` | A staged transaction is open. Reads wait until you commit or roll back. |
137
+ | `DEADLINE_EXCEEDED` | The default timeout is 30 s. Narrow the query or pass `--timeout-ms`. |
138
+ | `CONNECTION_FAILED`, `CONNECTION_NOT_FOUND` | Check `stql status`, the URL variable, and the network. |
139
+
140
+ ## Writes
141
+
142
+ Writes need a read-write connection and the user's request. Read
143
+ [reference/writes.md](reference/writes.md) before `exec`, `plan`/`apply`, or a
144
+ transaction. In short:
145
+
146
+ ```bash
147
+ stql exec 'UPDATE jobs SET claimed = 1 WHERE id = $1' --param 42 --idempotency-key claim-job-42
148
+ ```
149
+
150
+ A successful write returns `affected_rows` and `status` (`committed`, or
151
+ `pending` inside a transaction).
152
+
153
+ ## MongoDB and Redis
154
+
155
+ These use native commands, not SQL. Read [reference/native.md](reference/native.md)
156
+ before you use `stql mongo` or `stql redis`.
157
+
158
+ ## Other commands
159
+
160
+ | Command | Use |
161
+ | --- | --- |
162
+ | `stql inspect columns\|indexes\|constraints <table>` | Column, index, and constraint details |
163
+ | `stql history --limit 10` | Recent commands in this session |
164
+ | `stql receipt <operation-handle>` | Full record of a write |
165
+ | `stql session summary` | Open results and recent writes |
166
+ | `stql help` | Command syntax |
@@ -0,0 +1,61 @@
1
+ # MongoDB and Redis
2
+
3
+ SQL commands (`query`, `exec`, `plan`) are rejected on these connections. Pass
4
+ the native command as one JSON argument. In Windows PowerShell 5.1, send it
5
+ through `stql pipe` instead (field `mongo` or `redis`):
6
+
7
+ ```powershell
8
+ '{"command":"mongo.query","mongo":{"operation":"find","collection":"users","filter":{"active":true},"options":{"limit":20}}}' | stql pipe
9
+ ```
10
+
11
+ ## MongoDB
12
+
13
+ Commands use Extended JSON (EJSON): ObjectIds are `{"$oid":"..."}`, dates are
14
+ `{"$date":"2026-01-01T00:00:00Z"}`.
15
+
16
+ ```bash
17
+ stql objects collection # list collections
18
+ stql inspect columns users # fields seen in sampled documents
19
+ stql mongo query '{"operation":"find","collection":"users","filter":{"active":true},"options":{"projection":{"email":1},"sort":{"_id":1},"limit":50}}'
20
+ stql mongo query '{"operation":"aggregate","collection":"orders","pipeline":[{"$match":{"status":"paid"}},{"$group":{"_id":"$user_id","n":{"$sum":1}}}]}'
21
+ ```
22
+
23
+ | Operation | Keys |
24
+ | --- | --- |
25
+ | `find` | `collection`, `filter`, `options`: `projection`, `sort`, `skip`, `limit`, `hint`, `collation` |
26
+ | `aggregate` | `collection`, `pipeline`, `options`: `allowDiskUse`, `hint`, `collation` |
27
+ | `insertOne` / `insertMany` | `document` / `documents` |
28
+ | `updateOne` / `updateMany` | `filter`, `update`, `options`: `upsert`, `collation`, `hint` |
29
+ | `replaceOne` | `filter`, `replacement` |
30
+ | `deleteOne` / `deleteMany` | `filter` |
31
+
32
+ - Writes: `stql mongo exec '<command>'`; review first with `stql mongo plan`.
33
+ Empty filters need `--allow-unbounded`; deletes and replacements need
34
+ `--allow-destructive`. Both need user approval.
35
+ - `$out`, `$merge`, `$where`, `$function`, `$accumulator`, and server-side
36
+ JavaScript are rejected.
37
+ - Documents with different fields come back as objects, not row arrays.
38
+ - The cache cannot see changes made outside this session. Use
39
+ `--cache bypass` for a fresh read.
40
+
41
+ ## Redis
42
+
43
+ Commands are `{"command":"NAME","args":["..."]}`. All arguments are strings.
44
+
45
+ ```bash
46
+ stql objects key --search session: --limit 50 # SCAN-based; continue with --cursor <next_offset>
47
+ stql object key session:42 # type, TTL, and a bounded value
48
+ stql redis query '{"command":"HGET","args":["user:42","email"]}'
49
+ stql redis exec '{"command":"SET","args":["app:status","ready"]}' --idempotency-key status-ready
50
+ ```
51
+
52
+ | Kind | Allowed commands |
53
+ | --- | --- |
54
+ | Read (`redis query`) | `GET`, `MGET`, `TYPE`, `EXISTS`, `TTL`, `PTTL`, `HGET`, `HMGET`, bounded `LRANGE`, bounded `SCAN`/`HSCAN`/`SSCAN`/`ZSCAN` |
55
+ | Write (`redis exec`, `redis plan`) | one key: `SET`, `DEL`, `HSET`, `HDEL`, `LPUSH`, `RPUSH`, `SADD`, `SREM`, `ZADD`, `ZREM` |
56
+
57
+ - `KEYS`, scripts, pub/sub, blocking commands, and admin commands are rejected.
58
+ - Key pages can be empty or repeat keys while data changes. Keep following
59
+ `next_offset` until it is absent.
60
+ - `redis plan` then `stql apply` fails with `ROW_CONFLICT` if the key changed
61
+ in between. There are no staged transactions.
@@ -0,0 +1,70 @@
1
+ # Writes, plans, and transactions
2
+
3
+ All writes need a read-write connection (`stql connect ... --read-write`) and a
4
+ change the user asked for.
5
+
6
+ ## Safety gates
7
+
8
+ | Statement | Needs |
9
+ | --- | --- |
10
+ | `UPDATE`/`DELETE` without `WHERE`, `TRUNCATE` | `--allow-unbounded` |
11
+ | `DELETE`, `DROP`, `ALTER`, `TRUNCATE`, `REPLACE`, SQLite `INSERT/UPDATE OR REPLACE` | `--allow-destructive` |
12
+ | MongoDB empty update/replace/delete filter | `--allow-unbounded` |
13
+ | MongoDB `deleteOne`, `deleteMany`, `replaceOne` | `--allow-destructive` |
14
+
15
+ The two flags are independent: a `DELETE` without `WHERE` needs both. Add a
16
+ flag only after the user approved that exact operation. When a gate blocks a
17
+ command, the error has `override_flag`; show the user the statement and ask.
18
+
19
+ ## Direct write
20
+
21
+ ```bash
22
+ stql exec 'UPDATE jobs SET claimed = 1 WHERE id = $1' --param 42 --idempotency-key claim-job-42
23
+ ```
24
+
25
+ ```json
26
+ {"ok":true,"handle":"op_...","statement_type":"update","affected_rows":1,"status":"committed","state_version_after":"sv_1"}
27
+ ```
28
+
29
+ - Check `affected_rows` against what you expected.
30
+ - Use `--idempotency-key` for any write you might retry. The same key never
31
+ runs twice.
32
+ - Running the same statement with the same parameters again returns
33
+ `POTENTIAL_DUPLICATE_WRITE` with `previous_operation_id`. Add `--replay` only
34
+ if the user wants it to run again.
35
+ - `OUTCOME_UNKNOWN` (timeout or lost connection during the write) blocks
36
+ automatic replay. Query the data to find out whether the write happened, tell
37
+ the user, and only then decide about `--replay`.
38
+ - `stql receipt <op-handle>` shows the full record of a write.
39
+
40
+ ## Plan, then apply
41
+
42
+ Use a plan when the user should review a write before it runs.
43
+
44
+ ```bash
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
47
+ stql apply <plan-handle>
48
+ ```
49
+
50
+ - A plan keeps only the approval flags given to `plan`; `apply` never adds any.
51
+ - If data changed after `plan`, `apply` returns `STALE_PLAN`. Create a new plan.
52
+ - Plans expire after 10 minutes.
53
+
54
+ ## Staged transactions
55
+
56
+ ```bash
57
+ stql transaction begin # optional: --isolation 'repeatable read'
58
+ stql exec 'UPDATE accounts SET balance = balance - $1 WHERE id = $2' --params '[50, 1]'
59
+ stql exec 'UPDATE accounts SET balance = balance + $1 WHERE id = $2' --params '[50, 2]'
60
+ stql transaction status
61
+ stql transaction commit # or: stql transaction rollback
62
+ ```
63
+
64
+ - Writes are stored locally (`status: "pending"`) and run atomically at commit.
65
+ - While a transaction is open, reads, plans, and connection changes return
66
+ `TRANSACTION_FAILED`. Query what you need before `begin`.
67
+ - Isolation: SQLite `serializable`; PostgreSQL and MySQL also `repeatable read`,
68
+ `read committed`, `read uncommitted`.
69
+ - MySQL transactions reject DDL. MongoDB transactions need a replica set and use
70
+ `snapshot` isolation. Redis has no staged transactions.
package/docs/agents.md DELETED
@@ -1,72 +0,0 @@
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).