@fadhilp/stateql 0.13.3 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/usage.md DELETED
@@ -1,372 +0,0 @@
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 actor show
104
- stql actor set-name <display-name>
105
- stql profile add|update NAME [TARGET | --env ENV | --credential-ref REF]
106
- [--read-only|--read-write]
107
- stql profile list|show|remove
108
- stql session start|list|show|summary|close
109
- stql query <sql> [--params JSON | --param VALUE...] [--cache auto|bypass|require]
110
- [--preview-rows 0..200]
111
- stql filter <result-handle> <predicate> [--params JSON | --param VALUE...]
112
- stql exec <sql> [--params JSON | --param VALUE...] [--idempotency-key KEY] [--replay]
113
- [--allow-unbounded] [--allow-destructive]
114
- stql mongo query|exec|plan '<EJSON command>' [--cache MODE] [--idempotency-key KEY]
115
- [--replay] [--allow-unbounded] [--allow-destructive]
116
- stql redis query '<JSON command>' [--cache auto|bypass|require]
117
- stql redis exec '<JSON command>' [--idempotency-key KEY] [--replay]
118
- stql redis plan '<JSON command>'
119
- stql show|count|columns <result-handle>
120
- stql rows <result-handle> [--offset N] [--limit N]
121
- stql alias set <name> <result-handle>
122
- stql export <result-handle> --output FILE [--format json|jsonl|csv]
123
- stql inspect schema|table|collection|collections|columns|indexes|constraints [name]
124
- stql objects [KIND] [--schema NAME] [--search TEXT] [--offset N|--cursor CURSOR] [--limit N]
125
- stql object KIND NAME [IDENTITY] [--schema NAME]
126
- stql transaction begin|status|commit|rollback [--isolation LEVEL]
127
- stql plan <sql> [--params JSON | --param VALUE...] [--allow-unbounded] [--allow-destructive]
128
- stql apply <plan-handle>
129
- stql history [--limit N] [--offset N] [--category statement|introspection|management]
130
- [--internal|--external]
131
- stql receipt <operation-handle>
132
- stql doctor
133
- stql purge [expired|results|history|all]
134
- stql capabilities
135
- stql batch [commands.json|commands.jsonl|-] [--continue-on-error]
136
- stql pipe [--continue-on-error]
137
- ```
138
-
139
- ### SQL parameters
140
-
141
- For shell-safe positional parameters, repeat `--param`. JSON scalars become
142
- their native types; other values remain strings.
143
-
144
- ```bash
145
- stql exec "INSERT INTO users (name, status) VALUES (?, ?)" `
146
- --param Ada --param trial
147
- ```
148
-
149
- Use `--params JSON` for a JSON array or named parameters. Use
150
- `--params-file FILE` when JSON is awkward to quote; `--params-file -` reads
151
- JSON from standard input.
152
-
153
- ### Catalog inspection
154
-
155
- Use `objects` to list a bounded page and `object` to describe an entry:
156
-
157
- ```bash
158
- stql objects table --search users --limit 50
159
- stql object table users
160
- ```
161
-
162
- SQL/MongoDB offsets are non-negative numbers; limits default to 50 and are at
163
- most 200. Redis uses `--cursor` with the opaque numeric SCAN cursor string
164
- returned as `next_offset`. Its limit is a SCAN `COUNT` hint with a hard 200-item
165
- response bound. Redis pages are not snapshots and can be empty or contain
166
- duplicates while keys change.
167
-
168
- Search is a case-insensitive name substring for SQL/MongoDB and escaped glob
169
- substring matching for Redis. No exact counts are forced. Supported kinds are
170
- returned on every page: SQLite `table,view,trigger`; PostgreSQL
171
- `table,view,function,trigger,enum`; MySQL `table,view,function,trigger`; MongoDB
172
- `collection,view`; Redis `key`. PostgreSQL function identities include identity
173
- arguments; pass the returned identity to `object` to distinguish overloads.
174
-
175
- Library equivalents are `listObjects(filter, options?)` and
176
- `describeObject(object, options?)`, where `object` is a returned structured
177
- catalog entry. The older `inspect` commands remain available for SQL and
178
- MongoDB, but not Redis. See [database support](databases.md) for native commands.
179
-
180
- ### Output modes
181
-
182
- CLI output defaults to compact, one-line `agent` JSON. Successful responses
183
- flatten useful data and expose the primary durable ID as `handle`. Errors retain
184
- their complete error object. Empty warnings and tracing metadata are omitted.
185
-
186
- ```json
187
- {"ok":false,"error":{"code":"UNBOUNDED_MUTATION","message":"Mutation has no WHERE clause.","retryable":false,"executed":false,"override_flag":"--allow-unbounded"}}
188
- ```
189
-
190
- Other modes are:
191
-
192
- - `--output json`: original pretty, verbose envelope.
193
- - `--output jsonl`: verbose envelope on one line.
194
- - `--output text`: short human-readable status.
195
- - `--output silent`: only a successful handle.
196
-
197
- Set `STQL_OUTPUT` to choose a mode globally. For `export`, `--output` names the
198
- file, so use `STQL_OUTPUT` to choose the command's response mode. Library
199
- responses always keep the full envelope.
200
-
201
- ### Deadlines and cancellation
202
-
203
- Database commands accept `--timeout-ms N`; the default is 30,000 ms. `Ctrl+C`
204
- cancels active work.
205
-
206
- - SQLite runs in a killable child process so long synchronous statements cannot
207
- block StateQL's event loop.
208
- - PostgreSQL combines server-side `statement_timeout` with client deadlines.
209
- - MySQL deadlines destroy the active connection.
210
- - MongoDB uses driver deadlines and closes stopped operations.
211
-
212
- A timed-out or cancelled write may return `OUTCOME_UNKNOWN` when its commit
213
- status cannot be proven. Cancellation stops that command's driver work; it does
214
- not close the `StateQL` actor, and later commands remain usable.
215
-
216
- ## Durable state and result reuse
217
-
218
- State metadata lives under `STQL_HOME`, or the platform data directory when
219
- unset. StateQL keeps connections, sessions, handles, aliases, cache entries,
220
- plans, transactions, history, and receipts available across CLI invocations.
221
-
222
- ### Sessions and actors
223
-
224
- Set `STQL_SESSION` to select a named session and `STQL_ACTOR` to select an
225
- attached actor. A session is a shared workspace: attached actors reuse its
226
- connection, handles, aliases, cache, and state version. Plans and staged
227
- transactions remain owned by the actor that created them.
228
-
229
- Callers that omit `actor` keep the legacy behavior where the actor ID is the
230
- session name.
231
-
232
- Actor IDs are immutable authorization and ownership identities. Each actor also
233
- has a mutable display name, initially equal to its ID. The selected actor may
234
- change only its own display name with `stql actor set-name <display-name>`;
235
- names are trimmed, limited to 80 characters, and cannot contain control
236
- characters. Display names are contextual metadata and must not be used for
237
- authorization.
238
-
239
- History records both the stable `actor_id` and the `actor_name` in effect when
240
- the command began. Renaming therefore does not rewrite earlier attribution; the
241
- rename is itself recorded as an `actor.set-name` management command.
242
-
243
- ### Result lifetime and limits
244
-
245
- Result rows are materialized locally for durable access. By default, read cache
246
- entries expire after five minutes, and materialized handles expire after 24
247
- hours. Expired results and plans are deleted the next time StateQL opens.
248
-
249
- By default, queries exceeding 10,000 rows or 16 MiB of serialized row data fail
250
- before persistence. Narrow the `WHERE` clause, add `LIMIT`, or select fewer
251
- columns. These caps bound persisted materialization; the independent deadline
252
- bounds execution time. Native commands may impose stricter
253
- [database-specific limits](databases.md).
254
-
255
- Query responses preview five rows by default. Use `--preview-rows N` to return
256
- between 0 and 200 preview rows without rerunning or changing the stored result.
257
- Additional rows remain available through `stql rows <result-handle>`.
258
-
259
- Command history keeps the latest 10,000 entries per session. SQLite cache reuse
260
- also checks the database file signature. PostgreSQL, MySQL, and MongoDB cache
261
- reuse is labeled `ttl_based` and is never authoritative.
262
-
263
- StateQL limits persisted result payloads to 256 MiB by default. When that quota
264
- is reached it removes the oldest unaliased results; aliases remain protected. A
265
- single result that cannot fit fails with `STATE_QUOTA_EXCEEDED`. Configure the
266
- limit with `maxStateBytes` in the library or `--max-state-bytes` in the CLI.
267
- Cache and result retention can be configured with `cacheTtlSeconds` and
268
- `resultTtlSeconds`, or their `--cache-ttl-seconds` and
269
- `--result-ttl-seconds` CLI equivalents.
270
-
271
- `stql doctor` checks SQLite integrity and stored payload shapes without printing
272
- SQL, parameters, or result values. `stql purge` removes expired data by default;
273
- use `results`, `history`, or `all` for explicit session cleanup. On POSIX
274
- systems, StateQL removes group and world access from its state directory,
275
- database, and SQLite sidecar files.
276
-
277
- ### Local filtering
278
-
279
- `filter` evaluates one scalar SQLite predicate against a stored result. It
280
- preserves source order, state metadata, and expiry, and never accesses the
281
- original database.
282
-
283
- Use parameters for values. Subqueries, query-shaping clauses, and
284
- non-allowlisted functions are rejected. Common deterministic functions such as
285
- `lower`, `upper`, `length`, and `coalesce` are supported.
286
-
287
- ## Write safety
288
-
289
- Writes require a read-write connection. Destructive and unbounded SQL/MongoDB
290
- operations require `--allow-destructive` and `--allow-unbounded`, respectively.
291
- The flags are independent.
292
-
293
- `plan` validates and stores a write for later application. A plan persists only
294
- the flags explicitly supplied when it is created; `apply` never adds
295
- authorization.
296
-
297
- Use an idempotency key to protect retryable writes from duplicate execution:
298
-
299
- ```bash
300
- stql exec "UPDATE jobs SET claimed = 1 WHERE id = ?" \
301
- --param 42 \
302
- --idempotency-key claim-job-42
303
- ```
304
-
305
- If a write starts but StateQL cannot safely record its final outcome, it returns
306
- `OUTCOME_UNKNOWN` and blocks automatic replay. Inspect database state before
307
- using `--replay`. Interrupted commits remain fail-closed; stale `committing`
308
- records become `outcome_unknown` after five minutes.
309
-
310
- ### Transactions
311
-
312
- Transactions are staged in local state so they survive CLI invocations, then
313
- executed atomically on commit. While a transaction is active, StateQL rejects
314
- database reads, plans, connection changes, and disconnects. Commit or roll back
315
- first.
316
-
317
- SQLite supports `serializable`. PostgreSQL and MySQL also support
318
- `repeatable read`, `read committed`, and `read uncommitted`. Server reads run
319
- inside database-enforced read-only transactions. MySQL staged transactions
320
- reject DDL because MySQL implicitly commits those statements.
321
- MongoDB transactions use `snapshot` isolation and require a replica set or
322
- sharded deployment; standalone servers do not support them.
323
- Redis does not support StateQL staged transactions; see its
324
- [native write guarantees](databases.md#native-redis).
325
-
326
- ## Batch and pipes
327
-
328
- `batch` reads a JSON array from a `.json` file or JSONL from a `.jsonl` file.
329
- `pipe` reads JSONL from standard input. Commands run sequentially and stop on
330
- the first error unless `--continue-on-error` is set. Output defaults to one
331
- compact `agent` JSON object per line.
332
-
333
- Pipe commands directly:
334
-
335
- ```bash
336
- printf '%s\n' \
337
- '{"command":"query","sql":"SELECT id, email FROM users ORDER BY id","as":"users"}' \
338
- '{"command":"filter","handle":"users","where":"email LIKE ?","params":["%@example.com"],"as":"example_users"}' \
339
- '{"command":"rows","handle":"example_users","limit":10}' |
340
- stql pipe
341
- ```
342
-
343
- Or save a JSON array as `commands.json`:
344
-
345
- ```json
346
- [
347
- {
348
- "command": "exec",
349
- "sql": "UPDATE jobs SET claimed = 1 WHERE id = ?",
350
- "params": [42],
351
- "idempotency_key": "claim-job-42"
352
- },
353
- {
354
- "command": "query",
355
- "sql": "SELECT * FROM jobs WHERE id = ?",
356
- "params": [42]
357
- }
358
- ]
359
- ```
360
-
361
- ```bash
362
- stql batch commands.json
363
- ```
364
-
365
- Batch fields use snake case. Supported command names match CLI paths, such as
366
- `actor.show`, `actor.set-name`, `filter`, `transaction.begin`, `session.summary`,
367
- `alias.set`, `plan`, and `apply`. `actor.set-name` takes the display name in the
368
- `name` field. Query commands may set `preview_rows` from 0 to 200. Native MongoDB
369
- batches use `mongo.query`, `mongo.exec`, or `mongo.plan` with the command object
370
- in `mongo`; the same cache, replay, idempotency, safety, and timeout fields
371
- apply. Database commands may set `timeout_ms`; otherwise they use the 30-second
372
- default.