@fadhilp/stateql 0.13.0 → 0.13.2

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/docs/usage.md ADDED
@@ -0,0 +1,358 @@
1
+ # Usage
2
+
3
+ [Home](../README.md) · [Usage](usage.md) · [Database support](databases.md) · [TypeScript library](library.md)
4
+
5
+ - [Connections and profiles](#connections-and-profiles)
6
+ - [CLI reference](#cli-reference)
7
+ - [Durable state and result reuse](#durable-state-and-result-reuse)
8
+ - [Write safety](#write-safety)
9
+ - [Batch and pipes](#batch-and-pipes)
10
+
11
+ ## Connections and profiles
12
+
13
+ A connection accepts exactly one source: a direct target, `--env`,
14
+ `--credential-ref`, or `--profile`. Library and batch callers may additionally
15
+ attach a [password reference](library.md#password-references) to a literal
16
+ password-free remote target; it is not an additional connection source.
17
+
18
+ ```bash
19
+ stql connect <target> [--name NAME] [--read-only|--read-write]
20
+ stql connect --env ENV [--name NAME] [--read-only|--read-write]
21
+ stql connect --credential-ref REF [--name NAME] [--read-only|--read-write]
22
+ stql connect --profile NAME
23
+ stql disconnect
24
+ stql status
25
+ ```
26
+
27
+ Direct targets accept SQLite paths or password-free PostgreSQL, MySQL, MongoDB,
28
+ and Redis/Rediss URLs. Connections default to read-only unless a profile or an
29
+ explicit flag selects read-write access.
30
+
31
+ ### Environment-backed credentials
32
+
33
+ PostgreSQL, MySQL, MongoDB, and Redis credentials should come from environment
34
+ variables. The variable must contain the complete connection URL, not only its
35
+ password. Environment-backed SQLite paths require an explicit `sqlite:` prefix.
36
+ The URLs below are placeholders; supply real values through your secret-management
37
+ workflow rather than recording them in shell history.
38
+
39
+ ```bash
40
+ export APP_DATABASE_URL='postgres://user:password@host/app'
41
+ stql connect --env APP_DATABASE_URL --name app --read-only
42
+
43
+ export MYSQL_DATABASE_URL='mysql://user:password@host/app'
44
+ stql connect --env MYSQL_DATABASE_URL --name mysql-app --read-only
45
+
46
+ export MONGODB_URL='mongodb://user:password@host/app'
47
+ stql connect --env MONGODB_URL --name mongo-app --read-only
48
+
49
+ export REDIS_URL='rediss://user:password@host/0'
50
+ stql connect --env REDIS_URL --name redis-app --read-only
51
+
52
+ export SQLITE_DATABASE='sqlite:./app.sqlite'
53
+ stql connect --env SQLITE_DATABASE --name local --read-only
54
+ ```
55
+
56
+ StateQL stores no PostgreSQL, MySQL, MongoDB, or Redis password.
57
+ Credential-bearing URLs must be supplied through `--env` or an opaque full-URL
58
+ credential reference. SQLite paths remain persisted as connection metadata.
59
+
60
+ ### Local profiles
61
+
62
+ Profiles store exactly one connection target, environment-variable name, or
63
+ opaque credential reference together with read-only policy. A remote literal
64
+ target may additionally store a `password_ref`; SQLite, environment-backed, and
65
+ full-URL `credential_ref` profiles cannot. Credential values are never stored.
66
+ Profiles persist under `STQL_HOME` with other StateQL metadata, and list/show
67
+ responses include nullable `credential_ref` and `password_ref` fields.
68
+
69
+ ```bash
70
+ stql profile add local ./app.sqlite --read-only
71
+ stql profile add production --env PROD_DATABASE_URL --read-only
72
+ stql profile add hosted --credential-ref 'vault://team/app' --read-only
73
+ stql profile list
74
+ stql profile show production
75
+ stql profile update production --read-only
76
+ stql connect local
77
+ stql connect --profile production
78
+ ```
79
+
80
+ Credential references are bounded nonempty opaque strings; StateQL does not
81
+ apply environment-variable syntax or normalization to them. They can only be
82
+ resolved by a trusted host `CredentialResolver`, so the standalone CLI may
83
+ store them in profiles but cannot connect with them.
84
+
85
+ A bare connection target matching a profile name resolves to that profile;
86
+ otherwise it remains a path or database URL.
87
+
88
+ `profile update` changes subsequent connections, not an already-open connection.
89
+ Omitting the source keeps it; supplying a new source replaces the old one.
90
+ Password references are configured through the library or batch API, not a CLI
91
+ `--password-ref` flag. See [safe profile updates](library.md#safe-profile-updates)
92
+ for source-replacement and downgrade restrictions.
93
+
94
+ ## CLI reference
95
+
96
+ ```bash
97
+ stql connect <target> [--name NAME] [--read-only|--read-write]
98
+ stql connect --env ENV [--name NAME] [--read-only|--read-write]
99
+ stql connect --credential-ref REF [--name NAME] [--read-only|--read-write]
100
+ stql connect --profile NAME
101
+ stql disconnect
102
+ stql status
103
+ stql profile add|update NAME [TARGET | --env ENV | --credential-ref REF]
104
+ [--read-only|--read-write]
105
+ stql profile list|show|remove
106
+ stql session start|list|show|summary|close
107
+ stql query <sql> [--params JSON | --param VALUE...] [--cache auto|bypass|require]
108
+ [--preview-rows 0..200]
109
+ stql filter <result-handle> <predicate> [--params JSON | --param VALUE...]
110
+ stql exec <sql> [--params JSON | --param VALUE...] [--idempotency-key KEY] [--replay]
111
+ [--allow-unbounded] [--allow-destructive]
112
+ stql mongo query|exec|plan '<EJSON command>' [--cache MODE] [--idempotency-key KEY]
113
+ [--replay] [--allow-unbounded] [--allow-destructive]
114
+ stql redis query '<JSON command>' [--cache auto|bypass|require]
115
+ stql redis exec '<JSON command>' [--idempotency-key KEY] [--replay]
116
+ stql redis plan '<JSON command>'
117
+ stql show|count|columns <result-handle>
118
+ stql rows <result-handle> [--offset N] [--limit N]
119
+ stql alias set <name> <result-handle>
120
+ stql export <result-handle> --output FILE [--format json|jsonl|csv]
121
+ stql inspect schema|table|collection|collections|columns|indexes|constraints [name]
122
+ stql objects [KIND] [--schema NAME] [--search TEXT] [--offset N|--cursor CURSOR] [--limit N]
123
+ stql object KIND NAME [IDENTITY] [--schema NAME]
124
+ stql transaction begin|status|commit|rollback [--isolation LEVEL]
125
+ stql plan <sql> [--params JSON | --param VALUE...] [--allow-unbounded] [--allow-destructive]
126
+ stql apply <plan-handle>
127
+ stql history [--limit N] [--offset N] [--category statement|introspection|management]
128
+ [--internal|--external]
129
+ stql receipt <operation-handle>
130
+ stql doctor
131
+ stql purge [expired|results|history|all]
132
+ stql capabilities
133
+ stql batch [commands.json|commands.jsonl|-] [--continue-on-error]
134
+ stql pipe [--continue-on-error]
135
+ ```
136
+
137
+ ### SQL parameters
138
+
139
+ For shell-safe positional parameters, repeat `--param`. JSON scalars become
140
+ their native types; other values remain strings.
141
+
142
+ ```bash
143
+ stql exec "INSERT INTO users (name, status) VALUES (?, ?)" `
144
+ --param Ada --param trial
145
+ ```
146
+
147
+ Use `--params JSON` for a JSON array or named parameters. Use
148
+ `--params-file FILE` when JSON is awkward to quote; `--params-file -` reads
149
+ JSON from standard input.
150
+
151
+ ### Catalog inspection
152
+
153
+ Use `objects` to list a bounded page and `object` to describe an entry:
154
+
155
+ ```bash
156
+ stql objects table --search users --limit 50
157
+ stql object table users
158
+ ```
159
+
160
+ SQL/MongoDB offsets are non-negative numbers; limits default to 50 and are at
161
+ most 200. Redis uses `--cursor` with the opaque numeric SCAN cursor string
162
+ returned as `next_offset`. Its limit is a SCAN `COUNT` hint with a hard 200-item
163
+ response bound. Redis pages are not snapshots and can be empty or contain
164
+ duplicates while keys change.
165
+
166
+ Search is a case-insensitive name substring for SQL/MongoDB and escaped glob
167
+ substring matching for Redis. No exact counts are forced. Supported kinds are
168
+ returned on every page: SQLite `table,view,trigger`; PostgreSQL
169
+ `table,view,function,trigger,enum`; MySQL `table,view,function,trigger`; MongoDB
170
+ `collection,view`; Redis `key`. PostgreSQL function identities include identity
171
+ arguments; pass the returned identity to `object` to distinguish overloads.
172
+
173
+ Library equivalents are `listObjects(filter, options?)` and
174
+ `describeObject(object, options?)`, where `object` is a returned structured
175
+ catalog entry. The older `inspect` commands remain available for SQL and
176
+ MongoDB, but not Redis. See [database support](databases.md) for native commands.
177
+
178
+ ### Output modes
179
+
180
+ CLI output defaults to compact, one-line `agent` JSON. Successful responses
181
+ flatten useful data and expose the primary durable ID as `handle`. Errors retain
182
+ their complete error object. Empty warnings and tracing metadata are omitted.
183
+
184
+ ```json
185
+ {"ok":false,"error":{"code":"UNBOUNDED_MUTATION","message":"Mutation has no WHERE clause.","retryable":false,"executed":false,"override_flag":"--allow-unbounded"}}
186
+ ```
187
+
188
+ Other modes are:
189
+
190
+ - `--output json`: original pretty, verbose envelope.
191
+ - `--output jsonl`: verbose envelope on one line.
192
+ - `--output text`: short human-readable status.
193
+ - `--output silent`: only a successful handle.
194
+
195
+ Set `STQL_OUTPUT` to choose a mode globally. For `export`, `--output` names the
196
+ file, so use `STQL_OUTPUT` to choose the command's response mode. Library
197
+ responses always keep the full envelope.
198
+
199
+ ### Deadlines and cancellation
200
+
201
+ Database commands accept `--timeout-ms N`; the default is 30,000 ms. `Ctrl+C`
202
+ cancels active work.
203
+
204
+ - SQLite runs in a killable child process so long synchronous statements cannot
205
+ block StateQL's event loop.
206
+ - PostgreSQL combines server-side `statement_timeout` with client deadlines.
207
+ - MySQL deadlines destroy the active connection.
208
+ - MongoDB uses driver deadlines and closes stopped operations.
209
+
210
+ A timed-out or cancelled write may return `OUTCOME_UNKNOWN` when its commit
211
+ status cannot be proven. Cancellation stops that command's driver work; it does
212
+ not close the `StateQL` actor, and later commands remain usable.
213
+
214
+ ## Durable state and result reuse
215
+
216
+ State metadata lives under `STQL_HOME`, or the platform data directory when
217
+ unset. StateQL keeps connections, sessions, handles, aliases, cache entries,
218
+ plans, transactions, history, and receipts available across CLI invocations.
219
+
220
+ ### Sessions and actors
221
+
222
+ Set `STQL_SESSION` to select a named session and `STQL_ACTOR` to select an
223
+ attached actor. A session is a shared workspace: attached actors reuse its
224
+ connection, handles, aliases, cache, and state version. Plans and staged
225
+ transactions remain owned by the actor that created them.
226
+
227
+ Callers that omit `actor` keep the legacy behavior where the actor ID is the
228
+ session name.
229
+
230
+ ### Result lifetime and limits
231
+
232
+ Result rows are materialized locally for durable access. By default, read cache
233
+ entries expire after five minutes, and materialized handles expire after 24
234
+ hours. Expired results and plans are deleted the next time StateQL opens.
235
+
236
+ By default, queries exceeding 10,000 rows or 16 MiB of serialized row data fail
237
+ before persistence. Narrow the `WHERE` clause, add `LIMIT`, or select fewer
238
+ columns. These caps bound persisted materialization; the independent deadline
239
+ bounds execution time. Native commands may impose stricter
240
+ [database-specific limits](databases.md).
241
+
242
+ Query responses preview five rows by default. Use `--preview-rows N` to return
243
+ between 0 and 200 preview rows without rerunning or changing the stored result.
244
+ Additional rows remain available through `stql rows <result-handle>`.
245
+
246
+ Command history keeps the latest 10,000 entries per session. SQLite cache reuse
247
+ also checks the database file signature. PostgreSQL, MySQL, and MongoDB cache
248
+ reuse is labeled `ttl_based` and is never authoritative.
249
+
250
+ StateQL limits persisted result payloads to 256 MiB by default. When that quota
251
+ is reached it removes the oldest unaliased results; aliases remain protected. A
252
+ single result that cannot fit fails with `STATE_QUOTA_EXCEEDED`. Configure the
253
+ limit with `maxStateBytes` in the library or `--max-state-bytes` in the CLI.
254
+ Cache and result retention can be configured with `cacheTtlSeconds` and
255
+ `resultTtlSeconds`, or their `--cache-ttl-seconds` and
256
+ `--result-ttl-seconds` CLI equivalents.
257
+
258
+ `stql doctor` checks SQLite integrity and stored payload shapes without printing
259
+ SQL, parameters, or result values. `stql purge` removes expired data by default;
260
+ use `results`, `history`, or `all` for explicit session cleanup. On POSIX
261
+ systems, StateQL removes group and world access from its state directory,
262
+ database, and SQLite sidecar files.
263
+
264
+ ### Local filtering
265
+
266
+ `filter` evaluates one scalar SQLite predicate against a stored result. It
267
+ preserves source order, state metadata, and expiry, and never accesses the
268
+ original database.
269
+
270
+ Use parameters for values. Subqueries, query-shaping clauses, and
271
+ non-allowlisted functions are rejected. Common deterministic functions such as
272
+ `lower`, `upper`, `length`, and `coalesce` are supported.
273
+
274
+ ## Write safety
275
+
276
+ Writes require a read-write connection. Destructive and unbounded SQL/MongoDB
277
+ operations require `--allow-destructive` and `--allow-unbounded`, respectively.
278
+ The flags are independent.
279
+
280
+ `plan` validates and stores a write for later application. A plan persists only
281
+ the flags explicitly supplied when it is created; `apply` never adds
282
+ authorization.
283
+
284
+ Use an idempotency key to protect retryable writes from duplicate execution:
285
+
286
+ ```bash
287
+ stql exec "UPDATE jobs SET claimed = 1 WHERE id = ?" \
288
+ --param 42 \
289
+ --idempotency-key claim-job-42
290
+ ```
291
+
292
+ If a write starts but StateQL cannot safely record its final outcome, it returns
293
+ `OUTCOME_UNKNOWN` and blocks automatic replay. Inspect database state before
294
+ using `--replay`. Interrupted commits remain fail-closed; stale `committing`
295
+ records become `outcome_unknown` after five minutes.
296
+
297
+ ### Transactions
298
+
299
+ Transactions are staged in local state so they survive CLI invocations, then
300
+ executed atomically on commit. While a transaction is active, StateQL rejects
301
+ database reads, plans, connection changes, and disconnects. Commit or roll back
302
+ first.
303
+
304
+ SQLite supports `serializable`. PostgreSQL and MySQL also support
305
+ `repeatable read`, `read committed`, and `read uncommitted`. Server reads run
306
+ inside database-enforced read-only transactions. MySQL staged transactions
307
+ reject DDL because MySQL implicitly commits those statements.
308
+ MongoDB transactions use `snapshot` isolation and require a replica set or
309
+ sharded deployment; standalone servers do not support them.
310
+ Redis does not support StateQL staged transactions; see its
311
+ [native write guarantees](databases.md#native-redis).
312
+
313
+ ## Batch and pipes
314
+
315
+ `batch` reads a JSON array from a `.json` file or JSONL from a `.jsonl` file.
316
+ `pipe` reads JSONL from standard input. Commands run sequentially and stop on
317
+ the first error unless `--continue-on-error` is set. Output defaults to one
318
+ compact `agent` JSON object per line.
319
+
320
+ Pipe commands directly:
321
+
322
+ ```bash
323
+ printf '%s\n' \
324
+ '{"command":"query","sql":"SELECT id, email FROM users ORDER BY id","as":"users"}' \
325
+ '{"command":"filter","handle":"users","where":"email LIKE ?","params":["%@example.com"],"as":"example_users"}' \
326
+ '{"command":"rows","handle":"example_users","limit":10}' |
327
+ stql pipe
328
+ ```
329
+
330
+ Or save a JSON array as `commands.json`:
331
+
332
+ ```json
333
+ [
334
+ {
335
+ "command": "exec",
336
+ "sql": "UPDATE jobs SET claimed = 1 WHERE id = ?",
337
+ "params": [42],
338
+ "idempotency_key": "claim-job-42"
339
+ },
340
+ {
341
+ "command": "query",
342
+ "sql": "SELECT * FROM jobs WHERE id = ?",
343
+ "params": [42]
344
+ }
345
+ ]
346
+ ```
347
+
348
+ ```bash
349
+ stql batch commands.json
350
+ ```
351
+
352
+ Batch fields use snake case. Supported command names match CLI paths, such as
353
+ `filter`, `transaction.begin`, `session.summary`, `alias.set`, `plan`, and
354
+ `apply`. Query commands may set `preview_rows` from 0 to 200. Native MongoDB
355
+ batches use `mongo.query`, `mongo.exec`, or `mongo.plan` with the command object
356
+ in `mongo`; the same cache, replay, idempotency, safety, and timeout fields
357
+ apply. Database commands may set `timeout_ms`; otherwise they use the 30-second
358
+ default.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fadhilp/stateql",
3
- "version": "0.13.0",
3
+ "version": "0.13.2",
4
4
  "description": "Stateful, agent-oriented database CLI for safe result reuse",
5
5
  "repository": {
6
6
  "type": "git",
@@ -21,6 +21,7 @@
21
21
  "files": [
22
22
  "dist/src",
23
23
  "README.md",
24
+ "docs",
24
25
  "SQL_COMMAND_ROADMAP.md",
25
26
  "LICENSE"
26
27
  ],