@fadhilp/stateql 0.15.0 → 0.16.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 +13 -1
- package/dist/src/cli.js +51 -11
- package/dist/src/os-credentials.d.ts +6 -0
- package/dist/src/os-credentials.js +96 -0
- package/docs/batch.md +1 -1
- package/docs/cli.md +2 -2
- package/docs/connections.md +30 -8
- package/docs/databases.md +1 -1
- package/docs/library.md +1 -1
- package/docs/results.md +1 -1
- package/docs/writes.md +1 -1
- package/package.json +3 -1
- package/skills/stateql/SKILL.md +171 -0
- package/skills/stateql/reference/native.md +61 -0
- package/skills/stateql/reference/writes.md +70 -0
- package/docs/agents.md +0 -72
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
|
|
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 |
|
package/dist/src/cli.js
CHANGED
|
@@ -7,6 +7,7 @@ import { BSON } from "mongodb";
|
|
|
7
7
|
import { exitCodeFor } from "./errors.js";
|
|
8
8
|
import { StateQL } from "./stateql.js";
|
|
9
9
|
import { agentResponse } from "./agent-response.js";
|
|
10
|
+
import { askPassword, cliCredentialResolver, deleteOsPassword, saveOsPassword } from "./os-credentials.js";
|
|
10
11
|
const parsed = parseArgs({
|
|
11
12
|
allowPositionals: true,
|
|
12
13
|
strict: true,
|
|
@@ -15,6 +16,7 @@ const parsed = parseArgs({
|
|
|
15
16
|
profile: { type: "string" },
|
|
16
17
|
env: { type: "string" },
|
|
17
18
|
"credential-ref": { type: "string" },
|
|
19
|
+
"ask-password": { type: "boolean" },
|
|
18
20
|
"read-only": { type: "boolean" },
|
|
19
21
|
"read-write": { type: "boolean" },
|
|
20
22
|
params: { type: "string" },
|
|
@@ -76,6 +78,7 @@ const stateql = new StateQL({
|
|
|
76
78
|
...(values["max-cell-characters"] === undefined
|
|
77
79
|
? {}
|
|
78
80
|
: { maxCellCharacters: Number(values["max-cell-characters"]) }),
|
|
81
|
+
credentialResolver: cliCredentialResolver,
|
|
79
82
|
signal: abortController.signal,
|
|
80
83
|
});
|
|
81
84
|
try {
|
|
@@ -350,30 +353,62 @@ async function dispatchSession(action, args) {
|
|
|
350
353
|
}
|
|
351
354
|
async function dispatchProfile(action, args) {
|
|
352
355
|
switch (action) {
|
|
353
|
-
case "add":
|
|
356
|
+
case "add": {
|
|
354
357
|
if (values["read-only"] && values["read-write"]) {
|
|
355
358
|
throw new Error("--read-only and --read-write are mutually exclusive.");
|
|
356
359
|
}
|
|
357
|
-
|
|
360
|
+
const name = requireValue(args[0], "profile name");
|
|
361
|
+
const passwordRef = values["ask-password"]
|
|
362
|
+
? await saveOsPassword(await askPassword(name, requireValue(args[1], "TARGET for --ask-password")))
|
|
363
|
+
: undefined;
|
|
364
|
+
const added = await stateql.addProfile(name, args[1], {
|
|
358
365
|
...(values.env ? { secretEnv: values.env } : {}),
|
|
359
366
|
...(values["credential-ref"] ? { credentialRef: values["credential-ref"] } : {}),
|
|
367
|
+
...(passwordRef ? { passwordRef } : {}),
|
|
360
368
|
readOnly: !values["read-write"],
|
|
361
369
|
});
|
|
362
|
-
|
|
370
|
+
if (!added.ok)
|
|
371
|
+
await deleteOsPassword(passwordRef);
|
|
372
|
+
return added;
|
|
373
|
+
}
|
|
374
|
+
case "update": {
|
|
363
375
|
if (values["read-only"] && values["read-write"])
|
|
364
376
|
throw new Error("--read-only and --read-write are mutually exclusive.");
|
|
365
|
-
|
|
377
|
+
const name = requireValue(args[0], "profile name");
|
|
378
|
+
const before = await stateql.showProfile(name);
|
|
379
|
+
if (!before.ok)
|
|
380
|
+
return before;
|
|
381
|
+
const target = args[1] ?? before.data.target;
|
|
382
|
+
const passwordRef = values["ask-password"]
|
|
383
|
+
? await saveOsPassword(await askPassword(name, requireValue(target ?? undefined, "TARGET for --ask-password")))
|
|
384
|
+
: undefined;
|
|
385
|
+
const updated = await stateql.updateProfile(name, {
|
|
366
386
|
...(args[1] !== undefined ? { target: args[1] } : {}),
|
|
367
387
|
...(values.env ? { secretEnv: values.env } : {}),
|
|
368
388
|
...(values["credential-ref"] ? { credentialRef: values["credential-ref"] } : {}),
|
|
389
|
+
...(passwordRef ? { passwordRef } : {}),
|
|
369
390
|
...(values["read-only"] ? { readOnly: true } : values["read-write"] ? { readOnly: false } : {}),
|
|
370
391
|
});
|
|
392
|
+
if (!updated.ok) {
|
|
393
|
+
await deleteOsPassword(passwordRef);
|
|
394
|
+
return updated;
|
|
395
|
+
}
|
|
396
|
+
if (updated.data.password_ref !== before.data.password_ref)
|
|
397
|
+
await deleteOsPassword(before.data.password_ref);
|
|
398
|
+
return updated;
|
|
399
|
+
}
|
|
371
400
|
case "list":
|
|
372
401
|
return stateql.listProfiles();
|
|
373
402
|
case "show":
|
|
374
403
|
return stateql.showProfile(requireValue(args[0], "profile name"));
|
|
375
|
-
case "remove":
|
|
376
|
-
|
|
404
|
+
case "remove": {
|
|
405
|
+
const name = requireValue(args[0], "profile name");
|
|
406
|
+
const before = await stateql.showProfile(name);
|
|
407
|
+
const removed = await stateql.removeProfile(name);
|
|
408
|
+
if (removed.ok && before.ok)
|
|
409
|
+
await deleteOsPassword(before.data.password_ref);
|
|
410
|
+
return removed;
|
|
411
|
+
}
|
|
377
412
|
default:
|
|
378
413
|
throw new Error(`Unknown profile command "${action ?? ""}".`);
|
|
379
414
|
}
|
|
@@ -406,7 +441,7 @@ function parseParameters(value, values, file) {
|
|
|
406
441
|
: value;
|
|
407
442
|
let parsedValue;
|
|
408
443
|
try {
|
|
409
|
-
parsedValue = JSON.parse(json);
|
|
444
|
+
parsedValue = JSON.parse(withoutBom(json));
|
|
410
445
|
}
|
|
411
446
|
catch {
|
|
412
447
|
throw new Error(`Invalid JSON from ${file ? "--params-file" : "--params"}. ` +
|
|
@@ -447,6 +482,10 @@ async function* readBatchCommands(source) {
|
|
|
447
482
|
yield parseBatchCommand(parseBatchJson(line, `line ${lineNumber}`), `line ${lineNumber}`);
|
|
448
483
|
}
|
|
449
484
|
}
|
|
485
|
+
// PowerShell pipes and Out-File/Notepad files can start with a UTF-8 BOM, which JSON.parse rejects.
|
|
486
|
+
function withoutBom(value) {
|
|
487
|
+
return value.startsWith("") ? value.slice(1) : value;
|
|
488
|
+
}
|
|
450
489
|
function parseBatchCommand(value, location) {
|
|
451
490
|
if (!value ||
|
|
452
491
|
typeof value !== "object" ||
|
|
@@ -457,7 +496,7 @@ function parseBatchCommand(value, location) {
|
|
|
457
496
|
}
|
|
458
497
|
function parseBatchJson(value, location) {
|
|
459
498
|
try {
|
|
460
|
-
return JSON.parse(value);
|
|
499
|
+
return JSON.parse(withoutBom(value));
|
|
461
500
|
}
|
|
462
501
|
catch {
|
|
463
502
|
throw new Error(`Invalid JSON at ${location}.`);
|
|
@@ -576,7 +615,7 @@ Commands:
|
|
|
576
615
|
connect TARGET | --env ENV | --credential-ref REF | --profile NAME
|
|
577
616
|
disconnect, status
|
|
578
617
|
actor show | set-name NAME
|
|
579
|
-
profile add|update NAME [TARGET | --env ENV | --credential-ref REF]
|
|
618
|
+
profile add|update NAME [TARGET [--ask-password] | --env ENV | --credential-ref REF]
|
|
580
619
|
profile list|show|remove
|
|
581
620
|
query, filter, exec, show, rows, count, columns, export
|
|
582
621
|
mongo query|exec|plan '<EJSON command>'
|
|
@@ -594,11 +633,12 @@ SQL parameters: --params JSON, repeated --param VALUE, or --params-file FILE.
|
|
|
594
633
|
Query preview: --preview-rows N (default: 5, maximum: 200).
|
|
595
634
|
Long cells: --max-cell-characters N (default: 200); use export for full values.
|
|
596
635
|
Deadline: --timeout-ms N (default: 30000). Ctrl+C cancels database work.
|
|
597
|
-
|
|
636
|
+
Saved passwords: --ask-password opens a dialog and keeps the password in the OS credential store.
|
|
637
|
+
Other credential refs require a trusted host CredentialResolver; the standalone CLI cannot resolve them.
|
|
598
638
|
State: --max-state-bytes N, --cache-ttl-seconds N, --result-ttl-seconds N.
|
|
599
639
|
Output: --output agent|json|jsonl|text|silent (default: agent).
|
|
600
640
|
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.
|
|
641
|
+
Agent output omits null fields and false cached/duplicate flags. Agent skill: skills/stateql/SKILL.md.
|
|
602
642
|
Batch/pipe accept JSON array files or JSONL streams. Stop on first error.`;
|
|
603
643
|
}
|
|
604
644
|
function packageVersion() {
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import type { CredentialRequest } from "./types.js";
|
|
2
|
+
export declare function isOsPasswordRef(reference: string | null | undefined): reference is string;
|
|
3
|
+
export declare function cliCredentialResolver(request: CredentialRequest): Promise<string | undefined>;
|
|
4
|
+
export declare function saveOsPassword(password: string): Promise<string>;
|
|
5
|
+
export declare function deleteOsPassword(reference: string | null | undefined): Promise<void>;
|
|
6
|
+
export declare function askPassword(profile: string, target: string): Promise<string>;
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
import { execFile } from "node:child_process";
|
|
2
|
+
import { randomUUID } from "node:crypto";
|
|
3
|
+
import { env, platform } from "node:process";
|
|
4
|
+
import { promisify } from "node:util";
|
|
5
|
+
const SERVICE = "stql";
|
|
6
|
+
const PREFIX = "os:";
|
|
7
|
+
const run = promisify(execFile);
|
|
8
|
+
export function isOsPasswordRef(reference) {
|
|
9
|
+
return reference?.startsWith(PREFIX) ?? false;
|
|
10
|
+
}
|
|
11
|
+
export async function cliCredentialResolver(request) {
|
|
12
|
+
if (request.source === "credential_ref")
|
|
13
|
+
return undefined;
|
|
14
|
+
if (request.source !== "password_ref")
|
|
15
|
+
return env[request.reference];
|
|
16
|
+
if (!isOsPasswordRef(request.reference))
|
|
17
|
+
return undefined;
|
|
18
|
+
return (await osEntry(request.reference)).getPassword() ?? undefined;
|
|
19
|
+
}
|
|
20
|
+
export async function saveOsPassword(password) {
|
|
21
|
+
const reference = `${PREFIX}${randomUUID()}`;
|
|
22
|
+
(await osEntry(reference)).setPassword(password);
|
|
23
|
+
return reference;
|
|
24
|
+
}
|
|
25
|
+
export async function deleteOsPassword(reference) {
|
|
26
|
+
if (!isOsPasswordRef(reference))
|
|
27
|
+
return;
|
|
28
|
+
(await osEntry(reference)).deletePassword();
|
|
29
|
+
}
|
|
30
|
+
async function osEntry(reference) {
|
|
31
|
+
const { Entry } = await import("@napi-rs/keyring");
|
|
32
|
+
return new Entry(SERVICE, reference.slice(PREFIX.length));
|
|
33
|
+
}
|
|
34
|
+
export async function askPassword(profile, target) {
|
|
35
|
+
const url = new URL(target);
|
|
36
|
+
const user = decodeURIComponent(url.username);
|
|
37
|
+
const message = `Password for ${user ? `${user}@` : ""}${url.host} (StateQL profile "${profile}")`;
|
|
38
|
+
let output;
|
|
39
|
+
try {
|
|
40
|
+
output = await passwordDialog(message);
|
|
41
|
+
}
|
|
42
|
+
catch (error) {
|
|
43
|
+
if (isMissingCommand(error)) {
|
|
44
|
+
throw new Error("--ask-password needs a password dialog: zenity on Linux, osascript on macOS.");
|
|
45
|
+
}
|
|
46
|
+
throw new Error("Password entry was cancelled.");
|
|
47
|
+
}
|
|
48
|
+
const password = platform === "win32" ? output : output.replace(/\r?\n$/, "");
|
|
49
|
+
if (password === "")
|
|
50
|
+
throw new Error("No password was entered.");
|
|
51
|
+
return password;
|
|
52
|
+
}
|
|
53
|
+
async function passwordDialog(message) {
|
|
54
|
+
if (platform === "win32") {
|
|
55
|
+
// Get-Credential opens behind the active window; a TopMost form stays visible.
|
|
56
|
+
// windowsHide makes the first ShowWindow hide the form, so show it again explicitly.
|
|
57
|
+
const script = [
|
|
58
|
+
"$ErrorActionPreference = 'Stop'",
|
|
59
|
+
"[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding $false",
|
|
60
|
+
"Add-Type -AssemblyName System.Windows.Forms",
|
|
61
|
+
"Add-Type -Namespace StateQL -Name Win32 -MemberDefinition '[DllImport(\"user32.dll\")] public static extern bool ShowWindow(IntPtr window, int command);'",
|
|
62
|
+
"[Windows.Forms.Application]::EnableVisualStyles()",
|
|
63
|
+
"$form = New-Object Windows.Forms.Form -Property @{ Text = 'StateQL'; TopMost = $true; StartPosition = 'CenterScreen'; FormBorderStyle = 'FixedDialog'; MaximizeBox = $false; MinimizeBox = $false; AutoSize = $true; AutoSizeMode = 'GrowAndShrink'; Padding = 12 }",
|
|
64
|
+
"$layout = New-Object Windows.Forms.FlowLayoutPanel -Property @{ FlowDirection = 'TopDown'; AutoSize = $true }",
|
|
65
|
+
"$label = New-Object Windows.Forms.Label -Property @{ Text = $env:STQL_PROMPT_MESSAGE; AutoSize = $true; MaximumSize = '360,0' }",
|
|
66
|
+
"$box = New-Object Windows.Forms.TextBox -Property @{ UseSystemPasswordChar = $true; Width = 360 }",
|
|
67
|
+
"$buttons = New-Object Windows.Forms.FlowLayoutPanel -Property @{ FlowDirection = 'RightToLeft'; Width = 366; Height = 34 }",
|
|
68
|
+
"$cancel = New-Object Windows.Forms.Button -Property @{ Text = 'Cancel'; DialogResult = 'Cancel' }",
|
|
69
|
+
"$ok = New-Object Windows.Forms.Button -Property @{ Text = 'OK'; DialogResult = 'OK' }",
|
|
70
|
+
"$buttons.Controls.AddRange(@($cancel, $ok))",
|
|
71
|
+
"$layout.Controls.AddRange(@($label, $box, $buttons))",
|
|
72
|
+
"$form.Controls.Add($layout)",
|
|
73
|
+
"$form.AcceptButton = $ok",
|
|
74
|
+
"$form.CancelButton = $cancel",
|
|
75
|
+
"$form.Add_Shown({ [void][StateQL.Win32]::ShowWindow($form.Handle, 5); $form.Activate(); [void]$box.Focus() })",
|
|
76
|
+
"if ($form.ShowDialog() -ne 'OK') { exit 1 }",
|
|
77
|
+
"[Console]::Out.Write($box.Text)",
|
|
78
|
+
].join("\n");
|
|
79
|
+
const { stdout } = await run("powershell.exe", ["-NoProfile", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], { env: { ...env, STQL_PROMPT_MESSAGE: message }, windowsHide: true });
|
|
80
|
+
return stdout;
|
|
81
|
+
}
|
|
82
|
+
if (platform === "darwin") {
|
|
83
|
+
const { stdout } = await run("osascript", [
|
|
84
|
+
"-e", "on run argv",
|
|
85
|
+
"-e", 'text returned of (display dialog (item 1 of argv) default answer "" with hidden answer with title "StateQL")',
|
|
86
|
+
"-e", "end run",
|
|
87
|
+
message,
|
|
88
|
+
]);
|
|
89
|
+
return stdout;
|
|
90
|
+
}
|
|
91
|
+
const { stdout } = await run("zenity", ["--password", "--title", message]);
|
|
92
|
+
return stdout;
|
|
93
|
+
}
|
|
94
|
+
function isMissingCommand(error) {
|
|
95
|
+
return error.code === "ENOENT";
|
|
96
|
+
}
|
package/docs/batch.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Batch and pipes
|
|
2
2
|
|
|
3
|
-
[StateQL](../README.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) · [
|
|
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]
|
|
@@ -11,7 +11,7 @@ stql disconnect
|
|
|
11
11
|
stql status
|
|
12
12
|
stql actor show
|
|
13
13
|
stql actor set-name <display-name>
|
|
14
|
-
stql profile add|update NAME [TARGET | --env ENV | --credential-ref REF]
|
|
14
|
+
stql profile add|update NAME [TARGET [--ask-password] | --env ENV | --credential-ref REF]
|
|
15
15
|
[--read-only|--read-write]
|
|
16
16
|
stql profile list|show|remove
|
|
17
17
|
stql session start|list|show|summary|close
|
package/docs/connections.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Connections and profiles
|
|
2
2
|
|
|
3
|
-
[StateQL](../README.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
|
|
@@ -45,9 +45,10 @@ export SQLITE_DATABASE='sqlite:./app.sqlite'
|
|
|
45
45
|
stql connect --env SQLITE_DATABASE --name local --read-only
|
|
46
46
|
```
|
|
47
47
|
|
|
48
|
-
StateQL stores no PostgreSQL, MySQL, MongoDB, or Redis password.
|
|
48
|
+
StateQL stores no PostgreSQL, MySQL, MongoDB, or Redis password in its state.
|
|
49
49
|
Credential-bearing URLs must be supplied through `--env` or an opaque full-URL
|
|
50
|
-
credential reference
|
|
50
|
+
credential reference, or the password can be [saved in the OS credential
|
|
51
|
+
store](#saved-passwords). SQLite paths remain persisted as connection metadata.
|
|
51
52
|
|
|
52
53
|
## Local profiles
|
|
53
54
|
|
|
@@ -70,15 +71,36 @@ stql connect --profile production
|
|
|
70
71
|
```
|
|
71
72
|
|
|
72
73
|
Credential references are bounded nonempty opaque strings; StateQL does not
|
|
73
|
-
apply environment-variable syntax or normalization to them.
|
|
74
|
-
|
|
75
|
-
store them in profiles but
|
|
74
|
+
apply environment-variable syntax or normalization to them. Apart from the
|
|
75
|
+
`os:` password references below, they can only be resolved by a trusted host
|
|
76
|
+
`CredentialResolver`, so the standalone CLI may store them in profiles but
|
|
77
|
+
cannot connect with them.
|
|
78
|
+
|
|
79
|
+
## Saved passwords
|
|
80
|
+
|
|
81
|
+
`--ask-password` opens a password dialog and saves the password in the OS
|
|
82
|
+
credential store: Windows Credential Manager, macOS Keychain, or Linux Secret
|
|
83
|
+
Service. The profile keeps the password-free target and an `os:` password
|
|
84
|
+
reference.
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
stql profile add charlie 'postgres://reader@db.example.com:5432/app?sslmode=verify-full' --ask-password --read-only
|
|
88
|
+
stql profile update charlie --ask-password # replace the saved password
|
|
89
|
+
stql profile remove charlie # also deletes the saved password
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
The dialog uses Windows PowerShell on Windows, `osascript` on macOS, and `zenity`
|
|
93
|
+
on Linux, so it also works when an agent runs the command. Replacing the
|
|
94
|
+
password, changing the target or source, or removing the profile deletes the
|
|
95
|
+
old saved password; reconnect sessions that used it. Any program running as
|
|
96
|
+
your OS user can read the store, so give agent profiles a read-only database
|
|
97
|
+
user.
|
|
76
98
|
|
|
77
99
|
A bare connection target matching a profile name resolves to that profile;
|
|
78
100
|
otherwise it remains a path or database URL.
|
|
79
101
|
|
|
80
102
|
`profile update` changes subsequent connections, not an already-open connection.
|
|
81
103
|
Omitting the source keeps it; supplying a new source replaces the old one.
|
|
82
|
-
|
|
83
|
-
`--password-ref` flag. See [safe profile updates](library.md#safe-profile-updates)
|
|
104
|
+
Other password references are configured through the library or batch API, not
|
|
105
|
+
a CLI `--password-ref` flag. See [safe profile updates](library.md#safe-profile-updates)
|
|
84
106
|
for source-replacement and downgrade restrictions.
|
package/docs/databases.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Database support
|
|
2
2
|
|
|
3
|
-
[StateQL](../README.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,6 +1,6 @@
|
|
|
1
1
|
# TypeScript library
|
|
2
2
|
|
|
3
|
-
[StateQL](../README.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)
|
package/docs/results.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Durable state and result reuse
|
|
2
2
|
|
|
3
|
-
[StateQL](../README.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) · [
|
|
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.
|
|
3
|
+
"version": "0.16.0",
|
|
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": {
|
|
@@ -46,6 +47,7 @@
|
|
|
46
47
|
"node": ">=22.16"
|
|
47
48
|
},
|
|
48
49
|
"dependencies": {
|
|
50
|
+
"@napi-rs/keyring": "^2.1.1",
|
|
49
51
|
"@redis/client": "^5.12.1",
|
|
50
52
|
"bson": "^6.10.4",
|
|
51
53
|
"mongodb": "^6.21.0",
|
|
@@ -0,0 +1,171 @@
|
|
|
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`, or in a profile with a saved password (below).
|
|
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
|
+
To save a remote database with its password, run
|
|
41
|
+
`stql profile add <name> '<password-free URL>' --ask-password`. The user types
|
|
42
|
+
the password in a dialog; then use `stql connect <name>`. `stql profile list`
|
|
43
|
+
shows saved profiles.
|
|
44
|
+
|
|
45
|
+
## Read workflow
|
|
46
|
+
|
|
47
|
+
1. Find objects: `stql objects table --search order`
|
|
48
|
+
2. Read the shape: `stql object table orders` (returns the DDL or column list)
|
|
49
|
+
3. Query only the columns you need, with `ORDER BY`:
|
|
50
|
+
`stql query 'SELECT id, total FROM orders WHERE status = $1 ORDER BY id' --param paid`
|
|
51
|
+
4. Read the response (see below). `total` is the full row count, so you do not
|
|
52
|
+
need a separate `COUNT(*)`.
|
|
53
|
+
5. More rows: `stql rows <handle> --offset <next_offset> --limit 50`
|
|
54
|
+
(default 20, maximum 1000).
|
|
55
|
+
6. Narrow down: `stql filter <handle> 'CAST(total AS REAL) > ?' --param 100`.
|
|
56
|
+
This runs locally on the stored rows in SQLite syntax, always with `?`, and
|
|
57
|
+
returns a new handle. PostgreSQL `numeric`/`bigint` and MySQL `DECIMAL` values
|
|
58
|
+
are stored as strings (`"7.50"`), and SQLite treats every string as greater
|
|
59
|
+
than every number, so `total > ?` silently matches all rows. Wrap such
|
|
60
|
+
columns in `CAST(... AS REAL)`, or filter in SQL with a new query.
|
|
61
|
+
7. Save all rows: `stql export <handle> --output rows.csv` (`--format json|jsonl|csv`).
|
|
62
|
+
|
|
63
|
+
Use `--preview-rows N` (0 to 200) on `query` to change the preview size. Use
|
|
64
|
+
`--cache bypass` when data may have changed outside this session; writes made
|
|
65
|
+
through `stql` invalidate the cache automatically.
|
|
66
|
+
|
|
67
|
+
## Response format
|
|
68
|
+
|
|
69
|
+
```json
|
|
70
|
+
{"ok":true,"handle":"katcitg6un","total":331,"next_offset":5,"columns":["id","name"],"rows":[[2,"Ada"],[3,"Grace"],[5,"Linus"],[6,"Alan"],[8,"Edsger"]]}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
| Field | Meaning |
|
|
74
|
+
| --- | --- |
|
|
75
|
+
| `handle` | Stable result handle. Pass it to `rows`, `filter`, `count`, `columns`, `show`, `export`. |
|
|
76
|
+
| `columns` + `rows` | Each row is an array in `columns` order. If rows have different keys (MongoDB documents), rows are objects and `columns` is absent. |
|
|
77
|
+
| `total` | Rows in the stored result. |
|
|
78
|
+
| `next_offset` | Present only when more rows exist. Absent means you have every row. |
|
|
79
|
+
| `alias` | Present only when you named the result (batch `as`). |
|
|
80
|
+
| `warnings` | For example `NON_DETERMINISTIC_PAGINATION`: add `ORDER BY` before paging. |
|
|
81
|
+
|
|
82
|
+
- Exact numbers keep their precision as strings: PostgreSQL `numeric` and
|
|
83
|
+
`bigint`, MySQL `DECIMAL`.
|
|
84
|
+
- A long cell comes back as `{"type":"text","length":20000,"preview":"..."}`.
|
|
85
|
+
Use `--max-cell-characters N` or `export` for the full value.
|
|
86
|
+
- Null fields and false `cached`/`duplicate` flags are omitted.
|
|
87
|
+
- `rows`, `count`, and `columns` do not repeat the handle you passed.
|
|
88
|
+
|
|
89
|
+
## Placeholders and shell quoting
|
|
90
|
+
|
|
91
|
+
| Database | Placeholders |
|
|
92
|
+
| --- | --- |
|
|
93
|
+
| SQLite, MySQL | `?` |
|
|
94
|
+
| PostgreSQL | `$1`, `$2`, ... |
|
|
95
|
+
| `filter` predicates (all databases) | `?` |
|
|
96
|
+
|
|
97
|
+
- Put SQL in single quotes. In bash and PowerShell, `"$1"` expands to an empty
|
|
98
|
+
string and breaks the query.
|
|
99
|
+
- Use parameters instead of string literals, so you do not need quotes inside
|
|
100
|
+
quotes: `--param 'Ada Lovelace'`.
|
|
101
|
+
- **Windows PowerShell 5.1** removes the double quotes inside JSON arguments, so
|
|
102
|
+
`--params '[1]'` is fine but `stql redis query '{"command":"GET"}'` breaks.
|
|
103
|
+
Send JSON on standard input instead: `'<one JSON command>' | stql pipe` (see
|
|
104
|
+
below), or escape every inner quote as `\"`.
|
|
105
|
+
|
|
106
|
+
## Several steps in one call
|
|
107
|
+
|
|
108
|
+
`stql pipe` reads one JSON command per line and prints one response per line.
|
|
109
|
+
It stops at the first error unless you pass `--continue-on-error`. Fields use
|
|
110
|
+
snake_case; `as` gives a result a name that later lines can use.
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
printf '%s\n' \
|
|
114
|
+
'{"command":"query","sql":"SELECT id, email FROM users WHERE status = $1 ORDER BY id","params":["active"],"as":"active"}' \
|
|
115
|
+
'{"command":"filter","handle":"active","where":"email LIKE ?","params":["%@example.com"],"as":"example"}' \
|
|
116
|
+
'{"command":"rows","handle":"example","offset":5,"limit":20}' | stql pipe
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Command names match the CLI: `query`, `filter`, `rows`, `count`, `columns`,
|
|
120
|
+
`show`, `export`, `exec`, `plan`, `apply`, `objects.list`, `object.describe`,
|
|
121
|
+
`inspect`, `mongo.query`, `redis.query`, `transaction.begin`, and so on.
|
|
122
|
+
`stql batch commands.json` runs a JSON array from a file.
|
|
123
|
+
|
|
124
|
+
## Errors
|
|
125
|
+
|
|
126
|
+
Errors look like `{"ok":false,"error":{"code":"...","message":"...","retryable":false,"executed":false}}`.
|
|
127
|
+
Retry only when `retryable` is `true`. `executed:false` means nothing ran.
|
|
128
|
+
|
|
129
|
+
| Code | What to do |
|
|
130
|
+
| --- | --- |
|
|
131
|
+
| `INVALID_SQL` | Fix the SQL at the reported line and column. Check the placeholder style. |
|
|
132
|
+
| `QUERY_FAILED` | Read the database message (missing table or column, type error). Retry only if `retryable`. |
|
|
133
|
+
| `READ_ONLY_CONNECTION` | Ask the user before you reconnect with `--read-write`. |
|
|
134
|
+
| `UNBOUNDED_MUTATION` | Add a `WHERE` clause. Use `--allow-unbounded` only with user approval. |
|
|
135
|
+
| `DESTRUCTIVE_OPERATION_BLOCKED` | `DELETE`, `DROP`, `ALTER`, `TRUNCATE`, and `REPLACE` need user approval, then `--allow-destructive`. |
|
|
136
|
+
| `POTENTIAL_DUPLICATE_WRITE` | The same write already ran (`previous_operation_id`). Do not use `--replay` unless the user wants it to run again. |
|
|
137
|
+
| `OUTCOME_UNKNOWN` | The write may or may not have committed. Check the data with a query before anything else. |
|
|
138
|
+
| `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. |
|
|
139
|
+
| `RESULT_NOT_FOUND`, `RESULT_EXPIRED` | Wrong session or the result expired (24 h). Run the query again. |
|
|
140
|
+
| `STALE_PLAN` | Data changed after `plan`. Create a new plan. |
|
|
141
|
+
| `TRANSACTION_FAILED` | A staged transaction is open. Reads wait until you commit or roll back. |
|
|
142
|
+
| `DEADLINE_EXCEEDED` | The default timeout is 30 s. Narrow the query or pass `--timeout-ms`. |
|
|
143
|
+
| `CONNECTION_FAILED`, `CONNECTION_NOT_FOUND` | Check `stql status`, the URL variable, and the network. |
|
|
144
|
+
|
|
145
|
+
## Writes
|
|
146
|
+
|
|
147
|
+
Writes need a read-write connection and the user's request. Read
|
|
148
|
+
[reference/writes.md](reference/writes.md) before `exec`, `plan`/`apply`, or a
|
|
149
|
+
transaction. In short:
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
stql exec 'UPDATE jobs SET claimed = 1 WHERE id = $1' --param 42 --idempotency-key claim-job-42
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
A successful write returns `affected_rows` and `status` (`committed`, or
|
|
156
|
+
`pending` inside a transaction).
|
|
157
|
+
|
|
158
|
+
## MongoDB and Redis
|
|
159
|
+
|
|
160
|
+
These use native commands, not SQL. Read [reference/native.md](reference/native.md)
|
|
161
|
+
before you use `stql mongo` or `stql redis`.
|
|
162
|
+
|
|
163
|
+
## Other commands
|
|
164
|
+
|
|
165
|
+
| Command | Use |
|
|
166
|
+
| --- | --- |
|
|
167
|
+
| `stql inspect columns\|indexes\|constraints <table>` | Column, index, and constraint details |
|
|
168
|
+
| `stql history --limit 10` | Recent commands in this session |
|
|
169
|
+
| `stql receipt <operation-handle>` | Full record of a write |
|
|
170
|
+
| `stql session summary` | Open results and recent writes |
|
|
171
|
+
| `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).
|