@solidactions/cli 3.38.0 → 3.40.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 +15 -5
- package/dist/command-manifest.json +29 -4
- package/dist/commands/database-export.js +4 -2
- package/dist/commands/database.js +615 -49
- package/dist/index.js +19 -6
- package/dist/utils/database-kind-refusal.js +27 -0
- package/dist/utils/database-pull-guidance.js +20 -0
- package/dist/utils/database-replica-cache.js +432 -0
- package/dist/utils/examples-ref.js +4 -4
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -100,6 +100,7 @@ active workspace. The complete command surface is:
|
|
|
100
100
|
|
|
101
101
|
```bash
|
|
102
102
|
solidactions database list --json
|
|
103
|
+
solidactions database list --include-deleted --json
|
|
103
104
|
solidactions database create analytics --from backup.sql --json
|
|
104
105
|
solidactions database delete analytics --yes --json
|
|
105
106
|
solidactions database undelete analytics --json
|
|
@@ -109,6 +110,7 @@ solidactions database exec analytics "DELETE FROM events WHERE expired = 1" --ye
|
|
|
109
110
|
solidactions database dump analytics backup.sql --yes
|
|
110
111
|
solidactions database pull analytics .solidactions/databases/analytics.db --yes
|
|
111
112
|
solidactions database pull analytics --writable
|
|
113
|
+
solidactions database pull analytics --no-cache
|
|
112
114
|
solidactions database import analytics backup.sql --yes
|
|
113
115
|
solidactions database import analytics backup.sql --resume <checkpoint> --yes
|
|
114
116
|
solidactions database push analytics complete.db --yes
|
|
@@ -132,11 +134,15 @@ solidactions database versions metrics --limit 20 --json
|
|
|
132
134
|
solidactions database rollback metrics 2 --yes --json
|
|
133
135
|
```
|
|
134
136
|
|
|
137
|
+
`database pull` fetches only what changed since your last pull of the same database and keeps a hidden cache per database in `~/.solidactions/cache/database-replicas`; use `--no-cache` to skip it. Inside a workflow or function, query the database directly instead of pulling (`ctx.vars` with `createDatabaseClient`). Pull only for local analysis, keep and reuse one copy, and never pull per test or per preview.
|
|
138
|
+
|
|
135
139
|
`--json` produces machine-readable output where supported. `delete`, `exec`,
|
|
136
140
|
`dump` overwrites, `pull` overwrites, `drop-table`, and `import` prompt before
|
|
137
141
|
changing data; use `--yes` only when that change is already approved. A
|
|
138
142
|
database `delete` is a soft-delete, and its output shows the purge clock
|
|
139
|
-
during which `undelete` can restore it (either kind).
|
|
143
|
+
during which `undelete` can restore it (either kind). A deleted database
|
|
144
|
+
stays visible to `database list --include-deleted` until it is purged;
|
|
145
|
+
the default `database list` shows live databases only.
|
|
140
146
|
|
|
141
147
|
`create --kind` defaults to the standard (SQLite) kind; pass `--kind duckdb`
|
|
142
148
|
for an analytical database (waits for provisioning unless `--no-wait`).
|
|
@@ -150,7 +156,12 @@ refuse an analytical name with a one-line hint.
|
|
|
150
156
|
|
|
151
157
|
`create --kind duckdb_file` makes a DuckDB database file that your workflows
|
|
152
158
|
open, change and publish as numbered versions; it has no `--from`, `ingest` or
|
|
153
|
-
`exec` (change it from a workflow).
|
|
159
|
+
`exec` (change it from a workflow). Open it from a workflow with `openAnalytics`
|
|
160
|
+
from `@solidactions/sdk` 0.11.0 or newer (add `@duckdb/node-api` as a normal
|
|
161
|
+
dependency). The analytical verbs — `ingest`, `export`, `drop-table`,
|
|
162
|
+
`optimize`, `connect` and `wake` — do not apply to it: they are refused with
|
|
163
|
+
`kind_mismatch`, naming the kind and pointing at `query`, `schema`, `pull`,
|
|
164
|
+
`versions` and `rollback`. `pull <name> [path]` downloads the latest
|
|
154
165
|
published version as a plain DuckDB file (default
|
|
155
166
|
`.solidactions/databases/<name>.duckdb`; `--version <n>` picks an older one;
|
|
156
167
|
needs Node 22.15 or newer), verifies its size and checksum, and refuses a
|
|
@@ -158,8 +169,7 @@ download that does not match. It also refuses to pull over a target that has a
|
|
|
158
169
|
`<path>.wal` write-ahead file beside it, even with `--yes`: close the program
|
|
159
170
|
that has the database open (or remove that file) and pull again. `versions <name>` lists the published versions,
|
|
160
171
|
newest first, and `rollback <name> <version>` makes an earlier one current
|
|
161
|
-
after a `--yes` confirmation. `query` and `schema`
|
|
162
|
-
DuckDB databases arrive with the next release.
|
|
172
|
+
after a `--yes` confirmation. `query` and `schema` read the latest published version (read-only SQL on that version; `--limit` asks for fewer rows, and the server caps the rows it returns, 1000 by default) and answer `no_published_version` until a workflow has published one.
|
|
163
173
|
|
|
164
174
|
`ingest --mode replace` overwrites a table's contents with no `--yes` prompt
|
|
165
175
|
(unlike `drop-table`, which is a separate, rarer, schema-shaped operation) —
|
|
@@ -371,7 +381,7 @@ env:
|
|
|
371
381
|
- A global key, an `oauth:` name, and a `database:` name are **mutually exclusive**: bind each variable to exactly one. The platform enforces that server-side (HTTP 422), but do not rely on seeing that error: through CLI v3.6.0 the YAML parser keeps only the first form it recognizes — `oauth:` beats `database:` — so a declaration carrying both deploys silently as the wrong binding instead of failing.
|
|
372
382
|
- `project deploy` (including `--config-only`) syncs the *complete* `env:` list to the server on every run. Any previously YAML-sourced mapping whose name no longer appears in the list is deleted — removing or emptying `env:` prunes those mappings on the next deploy. Only mappings that were never YAML-declared survive: overriding a YAML-declared variable with `env set`/`env map` doesn't change its provenance, so removing its declaration still deletes the mapping.
|
|
373
383
|
- Create the workspace database first with `solidactions database create <name>` or in the web UI. Workspace-database bindings require `@solidactions/sdk >=0.8.0`.
|
|
374
|
-
- For a
|
|
384
|
+
- For a standard (libSQL) database, the workflow receives a typed `DatabaseVar` at `ctx.vars.<NAME>` at runtime, typically wrapped with the SDK's `createDatabaseClient()`; a `duckdb_file` database instead gets a plain database id string for `openAnalytics` (see the DuckDB database file paragraph above; needs `@solidactions/sdk` 0.11.0 or newer). The private transport payload uses `read_only`; SDK 0.8.0+ normalizes it to the public `DatabaseVar.readOnly` property. Use the typed SDK object rather than parsing the transport payload. See the SDK reference's [Workspace Databases](https://github.com/SolidActions/solidactions-ts-sdk/blob/main/docs/sdk-reference.md#workspace-databases) section for details.
|
|
375
385
|
|
|
376
386
|
## Commands
|
|
377
387
|
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schema_version": 1,
|
|
3
3
|
"cli_name": "solidactions",
|
|
4
|
-
"cli_version": "3.
|
|
4
|
+
"cli_version": "3.40.0",
|
|
5
5
|
"global_options": [
|
|
6
6
|
{
|
|
7
7
|
"flags": "-V, --version",
|
|
@@ -411,6 +411,18 @@
|
|
|
411
411
|
"negated": false,
|
|
412
412
|
"hidden": false
|
|
413
413
|
},
|
|
414
|
+
{
|
|
415
|
+
"flags": "--include-deleted",
|
|
416
|
+
"long": "--include-deleted",
|
|
417
|
+
"short": null,
|
|
418
|
+
"description": "Include deleted databases (they can be restored with database undelete until they are purged)",
|
|
419
|
+
"required": false,
|
|
420
|
+
"value_required": false,
|
|
421
|
+
"value_optional": false,
|
|
422
|
+
"variadic": false,
|
|
423
|
+
"negated": false,
|
|
424
|
+
"hidden": false
|
|
425
|
+
},
|
|
414
426
|
{
|
|
415
427
|
"flags": "--json",
|
|
416
428
|
"long": "--json",
|
|
@@ -570,7 +582,7 @@
|
|
|
570
582
|
],
|
|
571
583
|
"name": "delete",
|
|
572
584
|
"aliases": [],
|
|
573
|
-
"description": "Delete a workspace database",
|
|
585
|
+
"description": "Delete a workspace database (soft-delete: database list --include-deleted still shows it until purged; restore with database undelete)",
|
|
574
586
|
"hidden": false,
|
|
575
587
|
"arguments": [
|
|
576
588
|
{
|
|
@@ -626,7 +638,7 @@
|
|
|
626
638
|
],
|
|
627
639
|
"name": "undelete",
|
|
628
640
|
"aliases": [],
|
|
629
|
-
"description": "Restore a deleted workspace database",
|
|
641
|
+
"description": "Restore a deleted workspace database (find it with database list --include-deleted)",
|
|
630
642
|
"hidden": false,
|
|
631
643
|
"arguments": [
|
|
632
644
|
{
|
|
@@ -735,7 +747,7 @@
|
|
|
735
747
|
"flags": "--limit <n>",
|
|
736
748
|
"long": "--limit",
|
|
737
749
|
"short": null,
|
|
738
|
-
"description": "
|
|
750
|
+
"description": "Maximum rows to return (analytical databases: up to 10000; DuckDB database files: the server caps it, 1000 by default)",
|
|
739
751
|
"required": false,
|
|
740
752
|
"value_required": true,
|
|
741
753
|
"value_optional": false,
|
|
@@ -941,6 +953,19 @@
|
|
|
941
953
|
"negated": false,
|
|
942
954
|
"hidden": false
|
|
943
955
|
},
|
|
956
|
+
{
|
|
957
|
+
"flags": "--no-cache",
|
|
958
|
+
"long": "--no-cache",
|
|
959
|
+
"short": null,
|
|
960
|
+
"description": "Do not read or write the local replica cache for this pull",
|
|
961
|
+
"required": false,
|
|
962
|
+
"value_required": false,
|
|
963
|
+
"value_optional": false,
|
|
964
|
+
"variadic": false,
|
|
965
|
+
"negated": true,
|
|
966
|
+
"hidden": false,
|
|
967
|
+
"default": true
|
|
968
|
+
},
|
|
944
969
|
{
|
|
945
970
|
"flags": "-h, --help",
|
|
946
971
|
"long": "--help",
|
|
@@ -47,6 +47,7 @@ const promises_1 = require("stream/promises");
|
|
|
47
47
|
const stream_1 = require("stream");
|
|
48
48
|
const api_1 = require("../utils/api");
|
|
49
49
|
const database_data_plane_1 = require("../utils/database-data-plane");
|
|
50
|
+
const database_kind_refusal_1 = require("../utils/database-kind-refusal");
|
|
50
51
|
const database_1 = require("./database");
|
|
51
52
|
function safeDownloadUrl(value) {
|
|
52
53
|
if (typeof value !== 'string')
|
|
@@ -358,8 +359,9 @@ async function databaseExportWithConfig(name, options, config, dependencies = {}
|
|
|
358
359
|
if (options.resume && options.wait === false)
|
|
359
360
|
throw new ExportCommandError('invalid_arguments', '--no-wait cannot be combined with --resume. Resume waits for and downloads the existing export.');
|
|
360
361
|
const database = await (0, database_1.requestDatabaseRecord)(name, config);
|
|
361
|
-
|
|
362
|
-
|
|
362
|
+
const exportRefusal = (0, database_kind_refusal_1.analyticalVerbKindMismatch)(name, database, 'export');
|
|
363
|
+
if (exportRefusal)
|
|
364
|
+
throw new ExportCommandError(exportRefusal.code, exportRefusal.message);
|
|
363
365
|
let metadata;
|
|
364
366
|
if (options.resume) {
|
|
365
367
|
try {
|