@fadhilp/stateql 0.16.0 → 0.18.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/dist/src/adapters.d.ts +17 -25
- package/dist/src/adapters.js +15 -95
- package/dist/src/agent-response.js +6 -1
- package/dist/src/catalog.d.ts +6 -0
- package/dist/src/catalog.js +52 -0
- package/dist/src/cli.js +76 -25
- package/dist/src/connect.d.ts +16 -0
- package/dist/src/connect.js +205 -0
- package/dist/src/core.d.ts +78 -0
- package/dist/src/core.js +477 -0
- package/dist/src/execution.d.ts +27 -0
- package/dist/src/execution.js +87 -0
- package/dist/src/filter.js +3 -1
- package/dist/src/index.d.ts +1 -1
- package/dist/src/migrations.d.ts +1 -1
- package/dist/src/mongodb.d.ts +4 -2
- package/dist/src/mongodb.js +5 -56
- package/dist/src/panel.d.ts +64 -0
- package/dist/src/panel.js +316 -0
- package/dist/src/plans.d.ts +31 -0
- package/dist/src/plans.js +275 -0
- package/dist/src/reads.d.ts +35 -0
- package/dist/src/reads.js +184 -0
- package/dist/src/redis.d.ts +4 -2
- package/dist/src/redis.js +7 -33
- package/dist/src/response-data.d.ts +1 -0
- package/dist/src/response-data.js +13 -10
- package/dist/src/results.d.ts +10 -0
- package/dist/src/results.js +153 -0
- package/dist/src/sql.d.ts +7 -1
- package/dist/src/sql.js +88 -8
- package/dist/src/sqlite-process.js +16 -9
- package/dist/src/stateql.d.ts +9 -59
- package/dist/src/stateql.js +170 -2597
- package/dist/src/table-editor.js +2 -2
- package/dist/src/transactions.d.ts +8 -0
- package/dist/src/transactions.js +186 -0
- package/dist/src/types.d.ts +20 -18
- package/dist/src/util.d.ts +1 -0
- package/dist/src/util.js +1 -1
- package/dist/src/writes.d.ts +48 -0
- package/dist/src/writes.js +320 -0
- package/docs/batch.md +2 -1
- package/docs/cli.md +15 -9
- package/docs/databases.md +4 -3
- package/docs/library.md +3 -1
- package/docs/results.md +17 -0
- package/docs/writes.md +6 -0
- package/package.json +5 -3
- package/skills/stateql/SKILL.md +14 -6
- package/skills/stateql/reference/writes.md +4 -1
|
@@ -0,0 +1,320 @@
|
|
|
1
|
+
import { databaseIdentity, version } from "./connection.js";
|
|
2
|
+
import { adapterOfKind, closeAdapterQuietly, errorMessage, safeCredentialErrorMessage, } from "./core.js";
|
|
3
|
+
import { StateQLError } from "./errors.js";
|
|
4
|
+
import { AdapterExecutionError, AdapterWriteError, BatchWriteError, stoppedStateQLError, } from "./execution.js";
|
|
5
|
+
import { analyzeMongoWriteSafety, deserializeMongoWriteCommand, serializeMongoCommand, validateMongoWriteCommand, } from "./mongodb.js";
|
|
6
|
+
import { invalidCommand, mongoDescriptor, redisDescriptor, sqlParametersLength, } from "./reads.js";
|
|
7
|
+
import { serializeRedisCommand, validateRedisWriteCommand, } from "./redis.js";
|
|
8
|
+
import { operationData } from "./response-data.js";
|
|
9
|
+
import { analyzeSql } from "./sql.js";
|
|
10
|
+
import { hash } from "./util.js";
|
|
11
|
+
const REPLAY_ACTION = "Inspect database state, then use --replay only if another execution is safe.";
|
|
12
|
+
const FINALIZE_ACTION = "Inspect database state before issuing any replacement write.";
|
|
13
|
+
export function prepareSqlWrite(connection, sql, parameters, safety) {
|
|
14
|
+
const analysis = analyzeSql(sql, connection.driver);
|
|
15
|
+
if (analysis.read) {
|
|
16
|
+
throw new StateQLError("INVALID_SQL", "exec accepts write statements only; use query for reads.");
|
|
17
|
+
}
|
|
18
|
+
rejectUnsafeWrite(analysis.unboundedMutation, analysis.destructive, safety, "Mutation has no WHERE clause.", "Destructive operation requires an explicit override.");
|
|
19
|
+
const autocommitHasInputs = safety.expectedRows !== undefined || sqlParametersLength(parameters) > 0;
|
|
20
|
+
if (analysis.requiresAutocommit && autocommitHasInputs) {
|
|
21
|
+
throw new StateQLError("INVALID_SQL", "Autocommit maintenance statements do not accept StateQL parameters or row-count preconditions.");
|
|
22
|
+
}
|
|
23
|
+
const statementName = analysis.statementType.toUpperCase();
|
|
24
|
+
return {
|
|
25
|
+
descriptor: sql,
|
|
26
|
+
parameters,
|
|
27
|
+
statementType: analysis.statementType,
|
|
28
|
+
fingerprint: hash({
|
|
29
|
+
sql: analysis.normalized,
|
|
30
|
+
parameters,
|
|
31
|
+
database: databaseIdentity(connection),
|
|
32
|
+
}),
|
|
33
|
+
...(analysis.requiresAutocommit
|
|
34
|
+
? { stagingError: `${statementName} cannot be staged in a transaction.` }
|
|
35
|
+
: {}),
|
|
36
|
+
conflictMessage: "The row changed or no longer matches. Reload before editing.",
|
|
37
|
+
unknownAction: REPLAY_ACTION,
|
|
38
|
+
async execute(adapter) {
|
|
39
|
+
const sqlAdapter = adapterOfKind(adapter, "sql");
|
|
40
|
+
if (!analysis.requiresAutocommit)
|
|
41
|
+
return sqlAdapter.write(sql, parameters, safety.expectedRows);
|
|
42
|
+
if (!sqlAdapter.writeAutocommit) {
|
|
43
|
+
throw new AdapterWriteError(`${statementName} requires adapter autocommit execution.`, false);
|
|
44
|
+
}
|
|
45
|
+
return sqlAdapter.writeAutocommit(sql, parameters);
|
|
46
|
+
},
|
|
47
|
+
};
|
|
48
|
+
}
|
|
49
|
+
export function prepareMongoWrite(connection, command, safety) {
|
|
50
|
+
const value = invalidCommand(() => validateMongoWriteCommand(command));
|
|
51
|
+
const unsafe = analyzeMongoWriteSafety(value);
|
|
52
|
+
rejectUnsafeWrite(unsafe.unbounded, unsafe.destructive, safety, "MongoDB mutation has an empty filter.", "Destructive MongoDB operation requires an explicit override.");
|
|
53
|
+
const serialized = serializeMongoCommand(value);
|
|
54
|
+
return {
|
|
55
|
+
descriptor: mongoDescriptor(value.operation),
|
|
56
|
+
parameters: [serialized],
|
|
57
|
+
statementType: `mongo.${value.operation}`,
|
|
58
|
+
fingerprint: hash({ command: serialized, database: databaseIdentity(connection) }),
|
|
59
|
+
conflictMessage: "The document changed or was removed. Reload before editing.",
|
|
60
|
+
unknownAction: REPLAY_ACTION,
|
|
61
|
+
execute: (adapter) => adapterOfKind(adapter, "mongodb").write(value, safety.expectedRows),
|
|
62
|
+
};
|
|
63
|
+
}
|
|
64
|
+
export function prepareRedisWrite(connection, command, precondition) {
|
|
65
|
+
const value = invalidCommand(() => validateRedisWriteCommand(command));
|
|
66
|
+
const serialized = serializeRedisCommand(value);
|
|
67
|
+
return {
|
|
68
|
+
descriptor: redisDescriptor(value.command),
|
|
69
|
+
parameters: [serialized],
|
|
70
|
+
statementType: `redis.${value.command.toLowerCase()}`,
|
|
71
|
+
fingerprint: hash({ command: serialized, database: databaseIdentity(connection) }),
|
|
72
|
+
stagingError: "Redis writes cannot be staged in a transaction.",
|
|
73
|
+
conflictMessage: "The Redis key changed. Reload and plan again.",
|
|
74
|
+
unknownAction: "Inspect Redis state before issuing a replacement write.",
|
|
75
|
+
execute: (adapter) => adapterOfKind(adapter, "redis").write(value, precondition),
|
|
76
|
+
};
|
|
77
|
+
}
|
|
78
|
+
export function prepareTableBatch(connection, planId, updates, compiled) {
|
|
79
|
+
if (connection.driver === "redis") {
|
|
80
|
+
throw new StateQLError("UNSUPPORTED_DRIVER", "Redis does not support table edit batches.");
|
|
81
|
+
}
|
|
82
|
+
const mongoCommands = connection.driver === "mongodb"
|
|
83
|
+
? compiled.map((item) => {
|
|
84
|
+
if (!item.mongo)
|
|
85
|
+
throw new StateQLError("STALE_PLAN", "Table edit batch contains mixed drivers.");
|
|
86
|
+
return item.mongo;
|
|
87
|
+
})
|
|
88
|
+
: undefined;
|
|
89
|
+
return {
|
|
90
|
+
descriptor: `Conditional table update batch (${updates.length} rows)`,
|
|
91
|
+
parameters: [JSON.stringify({ version: 1, updates })],
|
|
92
|
+
statementType: "table.updates",
|
|
93
|
+
fingerprint: hash({ plan: planId, updates }),
|
|
94
|
+
stagingError: "Table edit batches cannot be staged in a transaction.",
|
|
95
|
+
conflictMessage: "At least one row changed; the entire edit batch was rolled back.",
|
|
96
|
+
unknownAction: "Inspect every edited row before retrying.",
|
|
97
|
+
async execute(adapter, operation) {
|
|
98
|
+
const results = mongoCommands
|
|
99
|
+
? await adapterOfKind(adapter, "mongodb").writeBatch(mongoCommands, "snapshot", true)
|
|
100
|
+
: await adapterOfKind(adapter, "sql").writeBatch(compiled.map((item, index) => ({
|
|
101
|
+
...operation,
|
|
102
|
+
id: `${operation.id}:${index}`,
|
|
103
|
+
sql: item.sql,
|
|
104
|
+
parameters: JSON.stringify(item.params),
|
|
105
|
+
statement_type: "update",
|
|
106
|
+
expectedRows: 1,
|
|
107
|
+
})), "serializable");
|
|
108
|
+
return { affectedRows: results.reduce((sum, item) => sum + item.affectedRows, 0) };
|
|
109
|
+
},
|
|
110
|
+
};
|
|
111
|
+
}
|
|
112
|
+
/** Reserves the write, stages it or runs it once, and records a definite or unknown outcome. */
|
|
113
|
+
export async function runWrite(core, session, connection, statement, options, context, claim) {
|
|
114
|
+
if (options.idempotencyKey !== undefined && !options.idempotencyKey.trim()) {
|
|
115
|
+
throw new StateQLError("INVALID_COMMAND", "Idempotency key cannot be empty.");
|
|
116
|
+
}
|
|
117
|
+
const transactionId = session.active_transaction_id ?? undefined;
|
|
118
|
+
if (transactionId)
|
|
119
|
+
requireStagingTransaction(core, session, connection, statement, transactionId);
|
|
120
|
+
const reservation = core.store.reserveOperation({
|
|
121
|
+
sessionId: session.id,
|
|
122
|
+
actorId: core.actorId,
|
|
123
|
+
connectionId: connection.id,
|
|
124
|
+
fingerprint: statement.fingerprint,
|
|
125
|
+
sql: statement.descriptor,
|
|
126
|
+
parameters: statement.parameters,
|
|
127
|
+
statementType: statement.statementType,
|
|
128
|
+
status: transactionId ? "pending" : "executing",
|
|
129
|
+
transactionId,
|
|
130
|
+
replay: options.replay ?? false,
|
|
131
|
+
idempotencyKey: options.idempotencyKey,
|
|
132
|
+
stateVersionBefore: version(connection),
|
|
133
|
+
});
|
|
134
|
+
if (reservation.denied)
|
|
135
|
+
throw reservationDenied(core, session, reservation.denied);
|
|
136
|
+
const previous = reservation.previous;
|
|
137
|
+
const keyReused = previous !== undefined &&
|
|
138
|
+
options.idempotencyKey !== undefined &&
|
|
139
|
+
!options.replay &&
|
|
140
|
+
previous.fingerprint !== statement.fingerprint;
|
|
141
|
+
if (keyReused) {
|
|
142
|
+
throw new StateQLError("IDEMPOTENCY_CONFLICT", "Idempotency key was already used for a different write.", { extra: { previous_operation_id: previous.id } });
|
|
143
|
+
}
|
|
144
|
+
if (!reservation.operation)
|
|
145
|
+
return duplicateWrite(previous, options.idempotencyKey);
|
|
146
|
+
const operation = reservation.operation;
|
|
147
|
+
if (transactionId) {
|
|
148
|
+
return {
|
|
149
|
+
data: operationData(operation),
|
|
150
|
+
handle: operation.id,
|
|
151
|
+
executed: false,
|
|
152
|
+
stateVersion: version(connection),
|
|
153
|
+
};
|
|
154
|
+
}
|
|
155
|
+
let adapter;
|
|
156
|
+
let source;
|
|
157
|
+
try {
|
|
158
|
+
source = claim?.source ??
|
|
159
|
+
await core.resolveConnectionSource(connection, session, "exec", "write", context);
|
|
160
|
+
adapter = await core.openAdapter(connection, context, source);
|
|
161
|
+
}
|
|
162
|
+
catch (error) {
|
|
163
|
+
core.store.failOperation(operation.id);
|
|
164
|
+
if (error instanceof StateQLError)
|
|
165
|
+
throw error;
|
|
166
|
+
throw new StateQLError("CONNECTION_FAILED", "Database connection failed.", { retryable: true });
|
|
167
|
+
}
|
|
168
|
+
try {
|
|
169
|
+
const write = await statement.execute(adapter, operation);
|
|
170
|
+
const finalized = finishWrite(core, connection, operation, write, claim);
|
|
171
|
+
return {
|
|
172
|
+
data: {
|
|
173
|
+
...operationData(finalized.operation),
|
|
174
|
+
duplicate: Boolean(previous),
|
|
175
|
+
duplicate_override: Boolean(previous),
|
|
176
|
+
},
|
|
177
|
+
handle: finalized.operation.id,
|
|
178
|
+
executed: true,
|
|
179
|
+
stateVersion: finalized.stateVersion,
|
|
180
|
+
confidence: adapter.confidence,
|
|
181
|
+
};
|
|
182
|
+
}
|
|
183
|
+
catch (error) {
|
|
184
|
+
throw writeFailure(core, operation, statement, error, source);
|
|
185
|
+
}
|
|
186
|
+
finally {
|
|
187
|
+
await closeAdapterQuietly(adapter);
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
function rejectUnsafeWrite(unbounded, destructive, safety, unboundedMessage, destructiveMessage) {
|
|
191
|
+
if (unbounded && !safety.allowUnbounded) {
|
|
192
|
+
throw new StateQLError("UNBOUNDED_MUTATION", unboundedMessage, {
|
|
193
|
+
extra: { override_flag: "--allow-unbounded" },
|
|
194
|
+
});
|
|
195
|
+
}
|
|
196
|
+
if (destructive && !safety.allowDestructive) {
|
|
197
|
+
throw new StateQLError("DESTRUCTIVE_OPERATION_BLOCKED", destructiveMessage, {
|
|
198
|
+
extra: { override_flag: "--allow-destructive" },
|
|
199
|
+
});
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
function requireStagingTransaction(core, session, connection, statement, transactionId) {
|
|
203
|
+
if (statement.stagingError) {
|
|
204
|
+
throw new StateQLError("TRANSACTION_FAILED", statement.stagingError, {
|
|
205
|
+
suggestedAction: "Roll back or commit the staged transaction, then run this statement separately.",
|
|
206
|
+
});
|
|
207
|
+
}
|
|
208
|
+
const transaction = core.store.getTransaction(transactionId);
|
|
209
|
+
const matches = transaction !== undefined &&
|
|
210
|
+
transaction.session_id === session.id &&
|
|
211
|
+
transaction.state === "active" &&
|
|
212
|
+
transaction.connection_id === connection.id;
|
|
213
|
+
if (!matches) {
|
|
214
|
+
throw new StateQLError("TRANSACTION_FAILED", "Active transaction does not match the active connection.");
|
|
215
|
+
}
|
|
216
|
+
if (transaction.owner_actor_id !== core.actorId) {
|
|
217
|
+
throw new StateQLError("PERMISSION_DENIED", "Only the transaction owner may stage writes.");
|
|
218
|
+
}
|
|
219
|
+
}
|
|
220
|
+
function reservationDenied(core, session, denied) {
|
|
221
|
+
if (denied === "membership") {
|
|
222
|
+
return new StateQLError("PERMISSION_DENIED", "Actor membership changed before the write was reserved.");
|
|
223
|
+
}
|
|
224
|
+
const active = core.store.getSession(session.id)?.active_transaction_id;
|
|
225
|
+
const transaction = active ? core.store.getTransaction(active) : undefined;
|
|
226
|
+
if (transaction && transaction.owner_actor_id !== core.actorId) {
|
|
227
|
+
return new StateQLError("PERMISSION_DENIED", "Only the transaction owner may stage writes.");
|
|
228
|
+
}
|
|
229
|
+
return new StateQLError("TRANSACTION_FAILED", "The active transaction changed before the write was reserved.");
|
|
230
|
+
}
|
|
231
|
+
function duplicateWrite(previous, idempotencyKey) {
|
|
232
|
+
if (previous.status === "executing" || previous.status === "outcome_unknown") {
|
|
233
|
+
throw new StateQLError("OUTCOME_UNKNOWN", "A matching write has an unknown outcome.", {
|
|
234
|
+
executed: true,
|
|
235
|
+
suggestedAction: REPLAY_ACTION,
|
|
236
|
+
extra: { previous_operation_id: previous.id },
|
|
237
|
+
});
|
|
238
|
+
}
|
|
239
|
+
if (!idempotencyKey) {
|
|
240
|
+
throw new StateQLError("POTENTIAL_DUPLICATE_WRITE", "An equivalent operation was previously applied.", { extra: { previous_operation_id: previous.id, replay_required: true } });
|
|
241
|
+
}
|
|
242
|
+
return {
|
|
243
|
+
data: {
|
|
244
|
+
...operationData(previous),
|
|
245
|
+
duplicate: true,
|
|
246
|
+
duplicate_of: previous.id,
|
|
247
|
+
idempotency_key: idempotencyKey,
|
|
248
|
+
},
|
|
249
|
+
handle: previous.id,
|
|
250
|
+
cached: true,
|
|
251
|
+
stateVersion: previous.state_version_after ?? previous.state_version_before,
|
|
252
|
+
};
|
|
253
|
+
}
|
|
254
|
+
function finishWrite(core, connection, operation, write, claim) {
|
|
255
|
+
try {
|
|
256
|
+
if (claim) {
|
|
257
|
+
return core.store.finishPlannedOperation({
|
|
258
|
+
planId: claim.planId,
|
|
259
|
+
claimToken: claim.claimToken,
|
|
260
|
+
operationId: operation.id,
|
|
261
|
+
connectionId: connection.id,
|
|
262
|
+
affectedRows: write.affectedRows,
|
|
263
|
+
outcome: write.outcome,
|
|
264
|
+
});
|
|
265
|
+
}
|
|
266
|
+
const stateVersion = core.store.bumpVersion(connection.id);
|
|
267
|
+
return {
|
|
268
|
+
operation: core.store.finishOperation(operation.id, write.affectedRows, stateVersion, write.outcome),
|
|
269
|
+
stateVersion,
|
|
270
|
+
};
|
|
271
|
+
}
|
|
272
|
+
catch (error) {
|
|
273
|
+
core.store.markOperationOutcomeUnknown(operation.id);
|
|
274
|
+
throw new StateQLError("OUTCOME_UNKNOWN", errorMessage(error), {
|
|
275
|
+
executed: true,
|
|
276
|
+
suggestedAction: FINALIZE_ACTION,
|
|
277
|
+
});
|
|
278
|
+
}
|
|
279
|
+
}
|
|
280
|
+
function writeFailure(core, operation, statement, error, source) {
|
|
281
|
+
if (error instanceof StateQLError)
|
|
282
|
+
return error;
|
|
283
|
+
const definite = (error instanceof AdapterExecutionError ||
|
|
284
|
+
error instanceof AdapterWriteError ||
|
|
285
|
+
error instanceof BatchWriteError) &&
|
|
286
|
+
!error.outcomeUnknown;
|
|
287
|
+
if (!definite) {
|
|
288
|
+
core.store.markOperationOutcomeUnknown(operation.id);
|
|
289
|
+
return new StateQLError("OUTCOME_UNKNOWN", safeCredentialErrorMessage(error, source), { executed: true, suggestedAction: statement.unknownAction });
|
|
290
|
+
}
|
|
291
|
+
core.store.failOperation(operation.id);
|
|
292
|
+
if (error.message.startsWith("ROW_CONFLICT:")) {
|
|
293
|
+
return new StateQLError("ROW_CONFLICT", statement.conflictMessage);
|
|
294
|
+
}
|
|
295
|
+
if (error instanceof AdapterExecutionError)
|
|
296
|
+
return stoppedStateQLError(error, false);
|
|
297
|
+
return new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, source), { executed: true });
|
|
298
|
+
}
|
|
299
|
+
export function storedMongoOperation(operation) {
|
|
300
|
+
if (!operation.statement_type.startsWith("mongo.")) {
|
|
301
|
+
throw new StateQLError("TRANSACTION_FAILED", "MongoDB transaction contains a mixed or corrupt native payload.");
|
|
302
|
+
}
|
|
303
|
+
return storedMongoWrite(operation.parameters, operation.statement_type, `operation "${operation.id}"`, "TRANSACTION_FAILED");
|
|
304
|
+
}
|
|
305
|
+
export function storedMongoWrite(parameters, statementType, label, errorCode) {
|
|
306
|
+
try {
|
|
307
|
+
const payload = JSON.parse(parameters);
|
|
308
|
+
if (!Array.isArray(payload) || payload.length !== 1 || typeof payload[0] !== "string") {
|
|
309
|
+
throw new Error("payload must contain one EJSON command string");
|
|
310
|
+
}
|
|
311
|
+
const command = deserializeMongoWriteCommand(payload[0]);
|
|
312
|
+
if (statementType !== `mongo.${command.operation}`) {
|
|
313
|
+
throw new Error("operation does not match its statement type");
|
|
314
|
+
}
|
|
315
|
+
return command;
|
|
316
|
+
}
|
|
317
|
+
catch {
|
|
318
|
+
throw new StateQLError(errorCode, `Stored MongoDB ${label} payload is invalid.`);
|
|
319
|
+
}
|
|
320
|
+
}
|
package/docs/batch.md
CHANGED
|
@@ -42,7 +42,8 @@ stql batch commands.json
|
|
|
42
42
|
Batch fields use snake case. Supported command names match CLI paths, such as
|
|
43
43
|
`actor.show`, `actor.set-name`, `filter`, `transaction.begin`, `session.summary`,
|
|
44
44
|
`alias.set`, `plan`, and `apply`. `actor.set-name` takes the display name in the
|
|
45
|
-
`name` field. Query commands may set `preview_rows` from 0 to 200.
|
|
45
|
+
`name` field. Query commands may set `preview_rows` from 0 to 200. `rows` may
|
|
46
|
+
set `columns` to an array of column names; `summarize` takes `handle`. Native MongoDB
|
|
46
47
|
batches use `mongo.query`, `mongo.exec`, or `mongo.plan` with the command object
|
|
47
48
|
in `mongo`; the same cache, replay, idempotency, safety, and timeout fields
|
|
48
49
|
apply. Database commands may set `timeout_ms`; otherwise they use the 30-second
|
package/docs/cli.md
CHANGED
|
@@ -15,25 +15,25 @@ stql profile add|update NAME [TARGET [--ask-password] | --env ENV | --credential
|
|
|
15
15
|
[--read-only|--read-write]
|
|
16
16
|
stql profile list|show|remove
|
|
17
17
|
stql session start|list|show|summary|close
|
|
18
|
-
stql query <sql> [--params JSON | --param VALUE...] [--cache auto|bypass|require]
|
|
18
|
+
stql query <sql> | --file FILE [--params JSON | --param VALUE...] [--cache auto|bypass|require]
|
|
19
19
|
[--preview-rows 0..200]
|
|
20
20
|
stql filter <result-handle> <predicate> [--params JSON | --param VALUE...]
|
|
21
|
-
stql exec <sql> [--params JSON | --param VALUE...] [--idempotency-key KEY] [--replay]
|
|
21
|
+
stql exec <sql> | --file FILE [--params JSON | --param VALUE...] [--idempotency-key KEY] [--replay]
|
|
22
22
|
[--allow-unbounded] [--allow-destructive]
|
|
23
|
-
stql mongo query|exec|plan '<EJSON command>' [--cache MODE] [--idempotency-key KEY]
|
|
23
|
+
stql mongo query|exec|plan '<EJSON command>' | --file FILE [--cache MODE] [--idempotency-key KEY]
|
|
24
24
|
[--replay] [--allow-unbounded] [--allow-destructive]
|
|
25
25
|
stql redis query '<JSON command>' [--cache auto|bypass|require]
|
|
26
26
|
stql redis exec '<JSON command>' [--idempotency-key KEY] [--replay]
|
|
27
27
|
stql redis plan '<JSON command>'
|
|
28
|
-
stql show|count|columns <result-handle>
|
|
29
|
-
stql rows <result-handle> [--offset N] [--limit N]
|
|
28
|
+
stql show|count|columns|summarize <result-handle>
|
|
29
|
+
stql rows <result-handle> [--offset N] [--limit N] [--columns a,b]
|
|
30
30
|
stql alias set <name> <result-handle>
|
|
31
|
-
stql export <result-handle> --output FILE [--format json|jsonl|csv]
|
|
31
|
+
stql export <result-handle> --output FILE [--format json|jsonl|csv] [--columns a,b]
|
|
32
32
|
stql inspect schema|table|collection|collections|columns|indexes|constraints [name]
|
|
33
33
|
stql objects [KIND] [--schema NAME] [--search TEXT] [--offset N|--cursor CURSOR] [--limit N]
|
|
34
34
|
stql object KIND NAME [IDENTITY] [--schema NAME]
|
|
35
35
|
stql transaction begin|status|commit|rollback [--isolation LEVEL]
|
|
36
|
-
stql plan <sql> [--params JSON | --param VALUE...] [--allow-unbounded] [--allow-destructive]
|
|
36
|
+
stql plan <sql> | --file FILE [--params JSON | --param VALUE...] [--allow-unbounded] [--allow-destructive]
|
|
37
37
|
stql apply <plan-handle>
|
|
38
38
|
stql history [--limit N] [--offset N] [--category statement|introspection|management]
|
|
39
39
|
[--internal|--external]
|
|
@@ -43,7 +43,7 @@ stql purge [expired|results|history|all]
|
|
|
43
43
|
stql capabilities
|
|
44
44
|
stql batch [commands.json|commands.jsonl|-] [--continue-on-error]
|
|
45
45
|
stql pipe [--continue-on-error]
|
|
46
|
-
stql help
|
|
46
|
+
stql help [command]
|
|
47
47
|
```
|
|
48
48
|
|
|
49
49
|
Global options: `--output MODE`, `--timeout-ms N`, `--max-cell-characters N`,
|
|
@@ -63,6 +63,10 @@ Use `--params JSON` for a JSON array or named parameters. Use
|
|
|
63
63
|
`--params-file FILE` when JSON is awkward to quote; `--params-file -` reads
|
|
64
64
|
JSON from standard input.
|
|
65
65
|
|
|
66
|
+
Use `--file FILE` instead of inline text to read the SQL, or the MongoDB or
|
|
67
|
+
Redis command, from a file. `--file -` reads standard input, so it cannot be
|
|
68
|
+
combined with `--params-file -`. A leading UTF-8 BOM is ignored.
|
|
69
|
+
|
|
66
70
|
## Catalog inspection
|
|
67
71
|
|
|
68
72
|
Use `objects` to list a bounded page and `object` to describe an entry:
|
|
@@ -98,6 +102,8 @@ their complete error object. Empty warnings and tracing metadata are omitted.
|
|
|
98
102
|
|
|
99
103
|
Agent mode also removes data that costs tokens but adds no information:
|
|
100
104
|
|
|
105
|
+
- `summarize` returns `columns` (`name`, `nulls`, `distinct`, `min`, `max`) and
|
|
106
|
+
one row per result column.
|
|
101
107
|
- `query`, `filter`, `show`, `mongo.query`, and `rows` return `columns` once and
|
|
102
108
|
each row as an array in that order. When rows have different keys (for
|
|
103
109
|
example, MongoDB documents), rows stay objects and `columns` is omitted.
|
|
@@ -110,7 +116,7 @@ Agent mode also removes data that costs tokens but adds no information:
|
|
|
110
116
|
- `capabilities` lists enabled `features` as names.
|
|
111
117
|
- `objects` returns `columns` once and each entry as an array. `identity` is
|
|
112
118
|
omitted when it equals `schema.name` (or `name`) for every entry.
|
|
113
|
-
- `rows`, `count`, and `
|
|
119
|
+
- `rows`, `count`, `columns`, and `summarize` do not repeat the handle you passed.
|
|
114
120
|
- Result `handle` is the generated alias, which cannot be reassigned. Full
|
|
115
121
|
`q_...` IDs work too and appear in `--output json`, `silent`, and history.
|
|
116
122
|
`alias` is present only when you chose a different name (batch `as`).
|
package/docs/databases.md
CHANGED
|
@@ -17,7 +17,8 @@ covered under [write safety](writes.md).
|
|
|
17
17
|
## Driver notes
|
|
18
18
|
|
|
19
19
|
- **SQLite:** use a filesystem path for direct connections or `sqlite:` for an
|
|
20
|
-
environment-backed path.
|
|
20
|
+
environment-backed path. Reads run with `PRAGMA query_only`, also on
|
|
21
|
+
read-write connections, so a read cannot change the database.
|
|
21
22
|
- **PostgreSQL:** StateQL preserves strict TLS verification by normalizing
|
|
22
23
|
`sslmode=prefer`, `require`, and `verify-ca` to `verify-full` before opening
|
|
23
24
|
the adapter. Use `sslmode=verify-full` explicitly for clarity. Setting
|
|
@@ -95,8 +96,8 @@ stql plan "REINDEX TABLE public.jobs" --allow-destructive
|
|
|
95
96
|
|
|
96
97
|
The PostgreSQL 14–18 grammar includes parenthesized `REINDEX CONCURRENTLY`,
|
|
97
98
|
PostgreSQL 16 `BUFFER_USAGE_LIMIT` for `VACUUM`/`ANALYZE`, optional
|
|
98
|
-
`DATABASE`/`SYSTEM` reindex names, and PostgreSQL 18 `ONLY table *`
|
|
99
|
-
targets. Memory sizes accept an integer number of kilobytes or a quoted
|
|
99
|
+
`DATABASE`/`SYSTEM` reindex names, and PostgreSQL 18 `ONLY table` and `table *`
|
|
100
|
+
maintenance targets (not both on one table). Memory sizes accept an integer number of kilobytes or a quoted
|
|
100
101
|
`B|kB|MB|GB|TB` value. Older servers may reject newer forms after dispatch, so
|
|
101
102
|
StateQL retains conservative unknown-outcome handling.
|
|
102
103
|
|
package/docs/library.md
CHANGED
|
@@ -63,7 +63,9 @@ Library responses retain the full response envelope regardless of the CLI
|
|
|
63
63
|
output mode. Check `response.ok` before reading `response.data`; failures expose
|
|
64
64
|
`response.error`. Queries return typed `ResultData` with `result_id`, `preview`,
|
|
65
65
|
and result metadata. Reuse `result_id` with methods such as `filter`, `rows`,
|
|
66
|
-
`count`, and `exportResult`; the CLI instead presents its primary ID as `handle`.
|
|
66
|
+
`count`, `summarize`, and `exportResult`; the CLI instead presents its primary ID as `handle`.
|
|
67
|
+
`rows(id, { columns })` and `exportResult(id, output, format, columns)` return
|
|
68
|
+
only the named columns.
|
|
67
69
|
Queries preview five rows by default. Set `previewRows` from 0 to 200 on an
|
|
68
70
|
individual query to control its response without changing or rerunning the
|
|
69
71
|
materialized result. The constructor-level `previewRows` option changes the
|
package/docs/results.md
CHANGED
|
@@ -67,6 +67,23 @@ use `results`, `history`, or `all` for explicit session cleanup. On POSIX
|
|
|
67
67
|
systems, StateQL removes group and world access from its state directory,
|
|
68
68
|
database, and SQLite sidecar files.
|
|
69
69
|
|
|
70
|
+
## Column projection and summaries
|
|
71
|
+
|
|
72
|
+
`rows` and `export` accept `--columns a,b` (library: `columns: ["a", "b"]`) to
|
|
73
|
+
return only those columns, in that order. Unknown column names fail with
|
|
74
|
+
`INVALID_COMMAND` and a list of the available columns.
|
|
75
|
+
|
|
76
|
+
CSV exports put a `'` before text cells that start with `=`, `+`, `-`, or `@`
|
|
77
|
+
(after optional spaces or control characters), or with a tab or line break.
|
|
78
|
+
Spreadsheets then show these cells as text and do not run them as formulas.
|
|
79
|
+
Number values are not changed.
|
|
80
|
+
|
|
81
|
+
`summarize` returns, for each column of a stored result, the null count, the
|
|
82
|
+
distinct count, and the min and max. Min and max are computed only when all
|
|
83
|
+
non-null values are numbers or all are strings. Numeric strings, such as
|
|
84
|
+
PostgreSQL `numeric` values, compare as numbers. Neither command accesses the
|
|
85
|
+
original database.
|
|
86
|
+
|
|
70
87
|
## Local filtering
|
|
71
88
|
|
|
72
89
|
`filter` evaluates one scalar SQLite predicate against a stored result. It
|
package/docs/writes.md
CHANGED
|
@@ -10,6 +10,12 @@ The flags are independent.
|
|
|
10
10
|
the flags explicitly supplied when it is created; `apply` never adds
|
|
11
11
|
authorization.
|
|
12
12
|
|
|
13
|
+
For a single-table SQL `UPDATE` or `DELETE` without `ORDER BY` or `LIMIT`,
|
|
14
|
+
`plan` also returns `estimated_rows`: a `COUNT(*)` of the rows that the `WHERE`
|
|
15
|
+
clause matches at plan time. The field is absent for other statements, or when
|
|
16
|
+
the count cannot be derived. Data can change before `apply`, so treat it as an
|
|
17
|
+
estimate; `affected_rows` on `apply` is the real value.
|
|
18
|
+
|
|
13
19
|
Use an idempotency key to protect retryable writes from duplicate execution:
|
|
14
20
|
|
|
15
21
|
```bash
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fadhilp/stateql",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.18.0",
|
|
4
4
|
"description": "Stateful, agent-oriented database CLI for safe result reuse",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -26,8 +26,9 @@
|
|
|
26
26
|
"LICENSE"
|
|
27
27
|
],
|
|
28
28
|
"scripts": {
|
|
29
|
-
"build": "tsc -p tsconfig.json",
|
|
30
|
-
"test": "npm run build && node --test dist/test
|
|
29
|
+
"build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json",
|
|
30
|
+
"test": "npm run build && node --test \"dist/test/*.test.js\"",
|
|
31
|
+
"lint": "biome lint",
|
|
31
32
|
"release": "npm version",
|
|
32
33
|
"version": "npm install",
|
|
33
34
|
"prepack": "npm test"
|
|
@@ -56,6 +57,7 @@
|
|
|
56
57
|
"pg": "^8.16.3"
|
|
57
58
|
},
|
|
58
59
|
"devDependencies": {
|
|
60
|
+
"@biomejs/biome": "2.5.15",
|
|
59
61
|
"@types/node": "^24.0.0",
|
|
60
62
|
"@types/pg": "^8.15.5",
|
|
61
63
|
"node-pty": "^1.1.0",
|
package/skills/stateql/SKILL.md
CHANGED
|
@@ -51,14 +51,18 @@ shows saved profiles.
|
|
|
51
51
|
4. Read the response (see below). `total` is the full row count, so you do not
|
|
52
52
|
need a separate `COUNT(*)`.
|
|
53
53
|
5. More rows: `stql rows <handle> --offset <next_offset> --limit 50`
|
|
54
|
-
(default 20, maximum 1000).
|
|
54
|
+
(default 20, maximum 1000). Add `--columns id,email` to return only some
|
|
55
|
+
columns of a wide result.
|
|
56
|
+
To understand the data, run `stql summarize <handle>`: for each column it
|
|
57
|
+
returns the null count, distinct count, min, and max.
|
|
55
58
|
6. Narrow down: `stql filter <handle> 'CAST(total AS REAL) > ?' --param 100`.
|
|
56
59
|
This runs locally on the stored rows in SQLite syntax, always with `?`, and
|
|
57
60
|
returns a new handle. PostgreSQL `numeric`/`bigint` and MySQL `DECIMAL` values
|
|
58
61
|
are stored as strings (`"7.50"`), and SQLite treats every string as greater
|
|
59
62
|
than every number, so `total > ?` silently matches all rows. Wrap such
|
|
60
63
|
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
|
|
64
|
+
7. Save all rows: `stql export <handle> --output rows.csv` (`--format json|jsonl|csv`,
|
|
65
|
+
optional `--columns`).
|
|
62
66
|
|
|
63
67
|
Use `--preview-rows N` (0 to 200) on `query` to change the preview size. Use
|
|
64
68
|
`--cache bypass` when data may have changed outside this session; writes made
|
|
@@ -72,7 +76,7 @@ through `stql` invalidate the cache automatically.
|
|
|
72
76
|
|
|
73
77
|
| Field | Meaning |
|
|
74
78
|
| --- | --- |
|
|
75
|
-
| `handle` | Stable result handle. Pass it to `rows`, `filter`, `count`, `columns`, `show`, `export`. |
|
|
79
|
+
| `handle` | Stable result handle. Pass it to `rows`, `filter`, `count`, `columns`, `summarize`, `show`, `export`. |
|
|
76
80
|
| `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
81
|
| `total` | Rows in the stored result. |
|
|
78
82
|
| `next_offset` | Present only when more rows exist. Absent means you have every row. |
|
|
@@ -96,12 +100,16 @@ through `stql` invalidate the cache automatically.
|
|
|
96
100
|
|
|
97
101
|
- Put SQL in single quotes. In bash and PowerShell, `"$1"` expands to an empty
|
|
98
102
|
string and breaks the query.
|
|
103
|
+
- For long SQL, or SQL with quotes, write it to a file and pass
|
|
104
|
+
`--file query.sql` instead of the inline SQL. `--file -` reads standard input.
|
|
105
|
+
This works for `query`, `exec`, `plan`, `stql mongo`, and `stql redis`.
|
|
99
106
|
- Use parameters instead of string literals, so you do not need quotes inside
|
|
100
107
|
quotes: `--param 'Ada Lovelace'`.
|
|
101
108
|
- **Windows PowerShell 5.1** removes the double quotes inside JSON arguments, so
|
|
102
109
|
`--params '[1]'` is fine but `stql redis query '{"command":"GET"}'` breaks.
|
|
103
|
-
Send JSON on standard input instead:
|
|
104
|
-
|
|
110
|
+
Send the JSON on standard input instead:
|
|
111
|
+
`'{"command":"GET","args":["a"]}' | stql redis query --file -`, or
|
|
112
|
+
`'<one JSON command>' | stql pipe` (see below).
|
|
105
113
|
|
|
106
114
|
## Several steps in one call
|
|
107
115
|
|
|
@@ -168,4 +176,4 @@ before you use `stql mongo` or `stql redis`.
|
|
|
168
176
|
| `stql history --limit 10` | Recent commands in this session |
|
|
169
177
|
| `stql receipt <operation-handle>` | Full record of a write |
|
|
170
178
|
| `stql session summary` | Open results and recent writes |
|
|
171
|
-
| `stql help
|
|
179
|
+
| `stql help <command>` | Syntax of one command (`stql help` lists all) |
|
|
@@ -43,10 +43,13 @@ Use a plan when the user should review a write before it runs.
|
|
|
43
43
|
|
|
44
44
|
```bash
|
|
45
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
|
|
46
|
+
# show the user statement_type, estimated_rows, required_overrides, and expires_at
|
|
47
47
|
stql apply <plan-handle>
|
|
48
48
|
```
|
|
49
49
|
|
|
50
|
+
- `estimated_rows` is the number of rows the `WHERE` clause matched when the
|
|
51
|
+
plan was made. It is present only for single-table `UPDATE` and `DELETE`
|
|
52
|
+
without `ORDER BY`/`LIMIT`. If it is absent, count the rows with a query.
|
|
50
53
|
- A plan keeps only the approval flags given to `plan`; `apply` never adds any.
|
|
51
54
|
- If data changed after `plan`, `apply` returns `STALE_PLAN`. Create a new plan.
|
|
52
55
|
- Plans expire after 10 minutes.
|