solera 0.0.1__tar.gz
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.
- solera-0.0.1/.gitignore +11 -0
- solera-0.0.1/LICENSE +15 -0
- solera-0.0.1/PKG-INFO +366 -0
- solera-0.0.1/README.md +347 -0
- solera-0.0.1/apps/server/src/solera_server/api.py +485 -0
- solera-0.0.1/apps/server/src/solera_server/cli.py +402 -0
- solera-0.0.1/apps/server/src/solera_server/demo.py +391 -0
- solera-0.0.1/apps/server/src/solera_server/engine.py +1835 -0
- solera-0.0.1/apps/server/src/solera_server/journal.py +363 -0
- solera-0.0.1/apps/server/src/solera_server/model.py +632 -0
- solera-0.0.1/apps/server/src/solera_server/placements/__init__.py +122 -0
- solera-0.0.1/apps/server/src/solera_server/placements/inline.py +49 -0
- solera-0.0.1/apps/server/src/solera_server/placements/local.py +176 -0
- solera-0.0.1/apps/server/src/solera_server/placements/pool.py +43 -0
- solera-0.0.1/apps/server/src/solera_server/placements/remote.py +220 -0
- solera-0.0.1/apps/server/src/solera_server/selftest.py +104 -0
- solera-0.0.1/apps/server/src/solera_server/state.py +274 -0
- solera-0.0.1/apps/server/src/solera_server/web/assets/assets-BSap0vq5.js +1 -0
- solera-0.0.1/apps/server/src/solera_server/web/assets/automations-DdLiPOz0.js +1 -0
- solera-0.0.1/apps/server/src/solera_server/web/assets/button-Dq2m6pM8.js +1 -0
- solera-0.0.1/apps/server/src/solera_server/web/assets/common-B-CWyYtx.js +1 -0
- solera-0.0.1/apps/server/src/solera_server/web/assets/executors-DQQbyBAS.js +1 -0
- solera-0.0.1/apps/server/src/solera_server/web/assets/geist-cyrillic-ext-wght-normal-DjL33-gN.woff2 +0 -0
- solera-0.0.1/apps/server/src/solera_server/web/assets/geist-cyrillic-wght-normal-BEAKL7Jp.woff2 +0 -0
- solera-0.0.1/apps/server/src/solera_server/web/assets/geist-latin-ext-wght-normal-DC-KSUi6.woff2 +0 -0
- solera-0.0.1/apps/server/src/solera_server/web/assets/geist-latin-wght-normal-BgDaEnEv.woff2 +0 -0
- solera-0.0.1/apps/server/src/solera_server/web/assets/geist-vietnamese-wght-normal-6IgcOCM7.woff2 +0 -0
- solera-0.0.1/apps/server/src/solera_server/web/assets/index-JGfsGvyn.js +17 -0
- solera-0.0.1/apps/server/src/solera_server/web/assets/refresh-cw-L1RN7bT3.js +1 -0
- solera-0.0.1/apps/server/src/solera_server/web/assets/runs-CKQ9Hxux.js +1 -0
- solera-0.0.1/apps/server/src/solera_server/web/assets/sources-CFtEjXLV.js +1 -0
- solera-0.0.1/apps/server/src/solera_server/web/assets/storage-ws5IRrKT.js +1 -0
- solera-0.0.1/apps/server/src/solera_server/web/assets/styles-COw0wuCY.css +2 -0
- solera-0.0.1/apps/server/src/solera_server/web/assets/table-DwKiY1Zz.js +1 -0
- solera-0.0.1/apps/server/src/solera_server/web/assets/useSelector-o7Ls85E6.js +1 -0
- solera-0.0.1/apps/server/src/solera_server/web/assets/with-selector-CxLBpKjg.js +1 -0
- solera-0.0.1/apps/server/src/solera_server/web/favicon.svg +1 -0
- solera-0.0.1/apps/server/src/solera_server/web/index.html +0 -0
- solera-0.0.1/apps/worker/src/solera_worker/__init__.py +1 -0
- solera-0.0.1/apps/worker/src/solera_worker/__main__.py +5 -0
- solera-0.0.1/apps/worker/src/solera_worker/worker.py +600 -0
- solera-0.0.1/packages/sdk/src/solera/__init__.py +106 -0
- solera-0.0.1/packages/sdk/src/solera/executors.py +138 -0
- solera-0.0.1/packages/sdk/src/solera/ids.py +28 -0
- solera-0.0.1/packages/sdk/src/solera/keys/__init__.py +75 -0
- solera-0.0.1/packages/sdk/src/solera/keys/_python.py +532 -0
- solera-0.0.1/packages/sdk/src/solera/keys/index.py +790 -0
- solera-0.0.1/packages/sdk/src/solera/keys/io.py +230 -0
- solera-0.0.1/packages/sdk/src/solera/sdk.py +1247 -0
- solera-0.0.1/packages/sdk/src/solera/stores.py +788 -0
- solera-0.0.1/packages/sdk/src/solera_postgres/__init__.py +581 -0
- solera-0.0.1/pyproject.toml +73 -0
solera-0.0.1/.gitignore
ADDED
solera-0.0.1/LICENSE
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
|
|
3
|
+
Copyright 2026 Solera contributors
|
|
4
|
+
|
|
5
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
6
|
+
you may not use this file except in compliance with the License.
|
|
7
|
+
You may obtain a copy of the License at
|
|
8
|
+
|
|
9
|
+
https://www.apache.org/licenses/LICENSE-2.0
|
|
10
|
+
|
|
11
|
+
Unless required by applicable law or agreed to in writing, software
|
|
12
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
13
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
14
|
+
See the License for the specific language governing permissions and
|
|
15
|
+
limitations under the License.
|
solera-0.0.1/PKG-INFO
ADDED
|
@@ -0,0 +1,366 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: solera
|
|
3
|
+
Version: 0.0.1
|
|
4
|
+
Summary: Asset-first orchestration on object storage: SDK, worker, and control plane
|
|
5
|
+
Project-URL: Repository, https://github.com/erwinkn/solera
|
|
6
|
+
License-Expression: Apache-2.0
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
Requires-Python: >=3.12
|
|
9
|
+
Requires-Dist: croniter<7,>=6
|
|
10
|
+
Requires-Dist: fastapi<1,>=0.115
|
|
11
|
+
Requires-Dist: httpx<1,>=0.28
|
|
12
|
+
Requires-Dist: obstore==0.11.1
|
|
13
|
+
Requires-Dist: uvicorn<1,>=0.34
|
|
14
|
+
Requires-Dist: xxhash<4,>=3
|
|
15
|
+
Provides-Extra: postgres
|
|
16
|
+
Requires-Dist: pandas<3,>=2.2; extra == 'postgres'
|
|
17
|
+
Requires-Dist: psycopg[binary]<4,>=3.2; extra == 'postgres'
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
|
|
20
|
+
# solera — asset-first data orchestration
|
|
21
|
+
|
|
22
|
+
A Python data orchestrator: assets declare outputs, partitions, inputs, and
|
|
23
|
+
placement; a durable control plane plans and executes runs; every committed
|
|
24
|
+
output is an immutable ref. The control plane keeps all state in SlateDB on
|
|
25
|
+
object storage (files, S3, or compatible services) — **no external service is
|
|
26
|
+
required for local operation**. Relational outputs can optionally live in
|
|
27
|
+
shared Postgres tables when `DATABASE_URL` is set.
|
|
28
|
+
|
|
29
|
+
**Experimental alpha — not production-ready.**
|
|
30
|
+
|
|
31
|
+
## Layout
|
|
32
|
+
|
|
33
|
+
- `packages/sdk` — `solera`, the asset SDK project files import
|
|
34
|
+
(`@asset`, `Output`, `Patch`, `Sql`, `PartitionSet`, `Incremental`,
|
|
35
|
+
`AllPartitions`, `TimePartitions`, triggers, placements). `solera_postgres`
|
|
36
|
+
ships `PostgresStore`.
|
|
37
|
+
- `apps/server` — `solera_server`: the control plane (state layer, engine,
|
|
38
|
+
FastAPI, CLI) and the built console under `solera_server/web`.
|
|
39
|
+
- `apps/worker` — `solera_worker`: the task harness that executes attempts in
|
|
40
|
+
subprocesses and pool workers.
|
|
41
|
+
- `apps/console` — the pnpm/Vite/TanStack console source. The built bundle is
|
|
42
|
+
committed, so running the server needs no Node.
|
|
43
|
+
- `apps/server/src/solera_server/demo.py` — the self-contained demo project
|
|
44
|
+
(`uv run solera serve --insecure` loads it by default).
|
|
45
|
+
- `example/brimstone.py` — a second reference project.
|
|
46
|
+
|
|
47
|
+
## Quick start
|
|
48
|
+
|
|
49
|
+
Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
uv sync --locked
|
|
53
|
+
uv run solera serve --insecure
|
|
54
|
+
# console + API at http://127.0.0.1:8000
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
State lands in `./.solera` — a `file://` object store using the same client
|
|
58
|
+
interfaces as S3. `--insecure` disables token auth and is restricted to
|
|
59
|
+
loopback; set `SOLERA_API_TOKEN` for anything else.
|
|
60
|
+
|
|
61
|
+
## The demo project
|
|
62
|
+
|
|
63
|
+
The default project is designed to make every architecture feature visible:
|
|
64
|
+
|
|
65
|
+
| asset | shows |
|
|
66
|
+
| --- | --- |
|
|
67
|
+
| `sites` | a `PartitionSet` on a `Cron` — the site list grows one site per run (cursor-driven) and caps at four |
|
|
68
|
+
| `uploads` | an external `PartitionSet` source fed by `solera commit` |
|
|
69
|
+
| `site_feed` | per-site cursor asset on `Every(10)`: `site_events` (unkeyed incremental) + `site_files` (keyed inventory), `Patch` both ways |
|
|
70
|
+
| `file_index` | `Incremental(batch_size=2)` consumer — watch `more` continuation; declared `version="2"` |
|
|
71
|
+
| `site_digest` | `site × day` two-dimensional asset (`TimePartitions`), `deps=` on the `roadmap` source, `BlobStore` output |
|
|
72
|
+
| `fleet_index` | `AllPartitions` fan-in: `dict[str, list[dict]]` on JsonStore, `dict[str, TableRef]` on Postgres |
|
|
73
|
+
| `site_status` | `Sql` asset over a `TableRef` (Postgres); on JsonStore it logs that it skipped |
|
|
74
|
+
| `fleet_status` | Postgres-only `AllPartitions` consumer over `TableRef`s — the SELECT runs in-database |
|
|
75
|
+
| `manual_ingest` | the one non-`Local` asset: `Pool("ingest")`, on an `Every(30)` schedule with `partitions="missing"` |
|
|
76
|
+
| `weekly_digest` | a `@job` on a weekly `Cron` — inputs and placement, no outputs |
|
|
77
|
+
| `refresh-index` | a standalone `Automation` targeting `site_feed` + `file_index` |
|
|
78
|
+
|
|
79
|
+
The feed fake emits a new batch per site every few seconds, and repeated polls
|
|
80
|
+
inside the same tick return identical content — an unchanged commit wakes
|
|
81
|
+
nothing downstream. Run config `feed_tick_seconds` stretches the tick:
|
|
82
|
+
`--config '{"feed_tick_seconds": 300}'`.
|
|
83
|
+
|
|
84
|
+
## Walkthrough
|
|
85
|
+
|
|
86
|
+
Everything below works against the running server. Set
|
|
87
|
+
`SOLERA_SERVER_URL=http://127.0.0.1:8000` so the CLI talks to it; unset, the
|
|
88
|
+
same commands drive an in-process engine against `SOLERA_STATE_URL`.
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
export SOLERA_SERVER_URL=http://127.0.0.1:8000
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### 1. The growing partition set
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
uv run solera run sites # run it a few times — one site appears per run
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Console: **Assets → sites** shows the partition-set head; the keys endpoint
|
|
101
|
+
(`GET /api/projects/demo/outputs/sites/keys`) grows `alpha → delta`.
|
|
102
|
+
The `sites.cron.0` automation keeps it fresh on its own once the server is up.
|
|
103
|
+
|
|
104
|
+
### 2. Commit external partition keys
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
uv run solera commit uploads --upsert '["u-1", "u-2"]'
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
**Sources** in the console lists `uploads` with its committed keys. These keys
|
|
111
|
+
are work for `manual_ingest` (below) — the `Every(30)` schedule with
|
|
112
|
+
`partitions="missing"` plans every key that lacks a complete head, so just
|
|
113
|
+
committing is enough once a pool worker is running.
|
|
114
|
+
|
|
115
|
+
### 3. The per-site cursor asset
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
uv run solera run site_feed --partitions all --upstream
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Each site scope writes a `site_events` incremental batch and a `site_files` keyed
|
|
122
|
+
patch, and stores the feed token as its cursor. **Runs** shows the run; click a
|
|
123
|
+
task to see its attempt spec — `inputs.site_files` carries the pinned ref, the
|
|
124
|
+
pinned key index and the window to read (a delta-log range, or the whole index
|
|
125
|
+
for a first delivery); the attempt's result records the keys it delivered.
|
|
126
|
+
|
|
127
|
+
Run it again inside the same feed tick: the feed returns identical events,
|
|
128
|
+
the committed versions are unchanged, and `file_index` is not woken — that is
|
|
129
|
+
the "no change wakes nothing" corollary. To see a changed pass, wait one tick
|
|
130
|
+
(or shrink it) and let `site_feed.every.0` fire, or `run-now` it.
|
|
131
|
+
|
|
132
|
+
### 4. Incremental with `more` continuation
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
uv run solera run file_index --partitions all --upstream
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
`site_files` holds four files per site; `Incremental(batch_size=2)` delivers them in
|
|
139
|
+
two batches — the run detail shows the first attempt completing with
|
|
140
|
+
`more: true` and a follow-up attempt finishing the remaining keys.
|
|
141
|
+
|
|
142
|
+
`file_index` declares `version="2"`. To demonstrate a version bump, edit it to
|
|
143
|
+
`"3"` in `apps/server/src/solera_server/demo.py` and re-run — the interpretation
|
|
144
|
+
fingerprint changes and every key reprocesses. To process selected keys only:
|
|
145
|
+
`uv run solera run file_index --keys 'site_files=alpha-file-0,alpha-file-1'`.
|
|
146
|
+
|
|
147
|
+
### 5. Two dimensions: site × day
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
uv run solera run site_digest --partitions all --upstream
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
`site_digest` is partitioned by `site` and a daily `TimePartitions` dim, so
|
|
154
|
+
its scopes look like `day=2026-09-01,site=alpha` (explicit multi-dim keys use
|
|
155
|
+
that canonical comma form with `--partition`). Its `deps=["roadmap"]` pins the
|
|
156
|
+
plain source in lineage without loading it. The output is bytes in the
|
|
157
|
+
`BlobStore` — check the head's ref on the asset page.
|
|
158
|
+
|
|
159
|
+
### 6. AllPartitions fan-in
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
uv run solera run fleet_index --upstream
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
`fleet_index` receives `file_index` as `dict[str, ...]` keyed by site —
|
|
166
|
+
committed heads at pin time, never a barrier on missing keys. With JsonStore
|
|
167
|
+
the values are `list[dict]`; with Postgres they are `TableRef`s.
|
|
168
|
+
|
|
169
|
+
### 7. SQL inside Postgres
|
|
170
|
+
|
|
171
|
+
With `DATABASE_URL` set (next section), `site_status` materializes
|
|
172
|
+
`SELECT status, count(*) ... GROUP BY status` into `ops.site_status` and
|
|
173
|
+
`fleet_status` unions a per-site count across `site_events` slices — neither
|
|
174
|
+
row set enters the harness. Without Postgres, `site_status` still runs and
|
|
175
|
+
logs `DATABASE_URL unset — site_status skipped (needs Postgres)` — visible in
|
|
176
|
+
the attempt log.
|
|
177
|
+
|
|
178
|
+
### 8. The job and the standalone automation
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
uv run solera automations # list all nine
|
|
182
|
+
uv run solera automations run-now refresh-index # fires site_feed + file_index
|
|
183
|
+
uv run solera run weekly_digest # sends the fake mail
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
**Automations** in the console shows trigger, last fire, and an enable/disable
|
|
187
|
+
toggle per automation; `weekly_digest.cron.0` runs Mondays at 07:00.
|
|
188
|
+
|
|
189
|
+
### 9. The pool worker
|
|
190
|
+
|
|
191
|
+
`manual_ingest` is placed on `Pool("ingest")` — submitted work waits queued
|
|
192
|
+
until an external worker claims it. In a second terminal:
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
export SOLERA_SERVER_URL=http://127.0.0.1:8000
|
|
196
|
+
export SOLERA_PROJECT=solera_server.demo:project # the entrypoint the worker executes
|
|
197
|
+
uv run solera worker pool ingest
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
Commit a couple of uploads (step 2), then `uv run solera run manual_ingest
|
|
201
|
+
--partitions all`. Watch the worker log `[pool] claimed …` / `[pool] completed
|
|
202
|
+
…`, and the **Executors** page shows the registered worker and its claimed
|
|
203
|
+
task. Pool tasks carry `cpu`/`memory`/`gpu` needs and are only offered to
|
|
204
|
+
workers whose capacity fits.
|
|
205
|
+
|
|
206
|
+
## Postgres
|
|
207
|
+
|
|
208
|
+
The demo runs entirely on JsonStore by default. To move the relational
|
|
209
|
+
outputs (`site_events`, `site_files`, `file_index`, `site_status`,
|
|
210
|
+
`fleet_status`) into shared Postgres tables:
|
|
211
|
+
|
|
212
|
+
```bash
|
|
213
|
+
docker compose up postgres
|
|
214
|
+
export DATABASE_URL=postgresql://solera:solera@127.0.0.1:5432/solera
|
|
215
|
+
uv run solera serve --insecure
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
Partitioned outputs share one physical table per output, sliced by their
|
|
219
|
+
`partition_column`; unkeyed incremental outputs get a `_batch`/`_seq` snapshot pair so a
|
|
220
|
+
pinned `TableRef` keeps reading the version it was committed at. Writes are
|
|
221
|
+
fenced by a per-partition version marker — a stale attempt's rows can never
|
|
222
|
+
become visible. `Sql` assets materialize straight into `{schema}.{table}`.
|
|
223
|
+
|
|
224
|
+
The Compose file also has a full `solera` service:
|
|
225
|
+
|
|
226
|
+
```bash
|
|
227
|
+
SOLERA_API_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')" \
|
|
228
|
+
docker compose up --build
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
It wires `DATABASE_URL` to the compose Postgres and keeps object state on a
|
|
232
|
+
named volume — swap `SOLERA_STATE_URL` for `s3://…` in `compose.yml` to run the
|
|
233
|
+
same stack on S3.
|
|
234
|
+
|
|
235
|
+
## Migrations
|
|
236
|
+
|
|
237
|
+
Schema changes are declared on the output, not implied by the store. An
|
|
238
|
+
`Output` carries `migrations=(Migration(name, payload), …)` in order; the
|
|
239
|
+
payload is a SQL string or a callable taking a cursor. Registration rejects
|
|
240
|
+
migrations on a store without `migrate` (JsonStore has none), duplicate
|
|
241
|
+
names, and payloads that fail `can_store`.
|
|
242
|
+
|
|
243
|
+
PostgresStore keeps a `solera_migrations(output, name, at)` ledger and runs
|
|
244
|
+
each pending migration plus its ledger row in one transaction under an
|
|
245
|
+
advisory lock keyed on the output, so concurrent workers apply each exactly
|
|
246
|
+
once. BlobStore records applied names in `_migrations.json` under the
|
|
247
|
+
output's prefix. A table that already exists must match the declaration —
|
|
248
|
+
drift fails non-retryably instead of triggering a silent `ALTER`. The
|
|
249
|
+
harness migrates before the first write in an attempt, and the output's
|
|
250
|
+
head carries the last applied name as `schema`.
|
|
251
|
+
|
|
252
|
+
Apply pending migrations without running the pipeline:
|
|
253
|
+
|
|
254
|
+
```bash
|
|
255
|
+
uv run solera migrate # every output that declares migrations
|
|
256
|
+
uv run solera migrate site_events # named outputs only
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
## S3 and compatible services
|
|
260
|
+
|
|
261
|
+
Point the control plane at a private bucket:
|
|
262
|
+
|
|
263
|
+
```bash
|
|
264
|
+
export SOLERA_STATE_URL=s3://your-private-bucket/orchestrator
|
|
265
|
+
export SOLERA_NAMESPACE=development
|
|
266
|
+
export AWS_ACCESS_KEY_ID=...
|
|
267
|
+
export AWS_SECRET_ACCESS_KEY=...
|
|
268
|
+
export AWS_REGION=us-east-1
|
|
269
|
+
export AWS_CONDITIONAL_PUT=etag
|
|
270
|
+
export SOLERA_API_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
|
|
271
|
+
uv run solera serve
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
For a custom S3 endpoint, `AWS_ENDPOINT` (the Rust object-store client's
|
|
275
|
+
setting) plus `AWS_VIRTUAL_HOSTED_STYLE_REQUEST=false`; `AWS_ALLOW_HTTP=true`
|
|
276
|
+
only for a local HTTP emulator. Before trusting a new S3-compatible service,
|
|
277
|
+
run the conformance probe, which writes into a fresh isolated namespace:
|
|
278
|
+
|
|
279
|
+
```bash
|
|
280
|
+
uv run solera selftest --state-url "$SOLERA_STATE_URL"
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
**One coordinator per namespace.** A second writer on the same namespace
|
|
284
|
+
fences the first. Give ad-hoc CLI runs a distinct `--namespace`, or submit
|
|
285
|
+
through the server instead.
|
|
286
|
+
|
|
287
|
+
## CLI
|
|
288
|
+
|
|
289
|
+
```text
|
|
290
|
+
solera serve [--project SPEC] [--insecure] API + console (default project: the demo)
|
|
291
|
+
solera manifest --project SPEC print the project manifest
|
|
292
|
+
solera run TARGET... [--partitions latest|all|missing] [--partition KEY]
|
|
293
|
+
[--upstream] [--full] [--keys EDGE=k1,k2] [--config JSON]
|
|
294
|
+
solera runs / run-show RUN_ID / logs RUN_ID ATTEMPT_ID [--tail N]
|
|
295
|
+
solera runs delete RUN_ID delete a finished run
|
|
296
|
+
solera runs prune [--before DATE] [--asset A] [--keep N] [--dry-run]
|
|
297
|
+
solera automations [enable|disable|run-now NAME]
|
|
298
|
+
solera migrate [OUTPUT...] apply pending output migrations locally
|
|
299
|
+
solera commit SOURCE [--version V] [--keys JSON] [--upsert JSON] [--remove K]
|
|
300
|
+
solera worker pool NAME [--server URL] claim and run pool tasks
|
|
301
|
+
solera selftest storage conformance probe
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
`--project` accepts `module:attribute`, a `file.py` path, or `file.py:attr`;
|
|
305
|
+
it also reads `SOLERA_PROJECT`. With `SOLERA_SERVER_URL` set every command talks
|
|
306
|
+
to the server (token from `SOLERA_API_TOKEN`); without it they drive a local
|
|
307
|
+
engine against `SOLERA_STATE_URL`/`--state-url` (`--namespace` selects the
|
|
308
|
+
namespace). `solera worker pool` additionally needs `SOLERA_PROJECT` so claimed
|
|
309
|
+
attempts can load the project.
|
|
310
|
+
|
|
311
|
+
## Authoring
|
|
312
|
+
|
|
313
|
+
```python
|
|
314
|
+
from solera.sdk import Output, PartitionSet, Project, TimePartitions, asset
|
|
315
|
+
from solera.stores import Patch
|
|
316
|
+
|
|
317
|
+
sites = PartitionSet("sites")
|
|
318
|
+
|
|
319
|
+
|
|
320
|
+
@asset(outputs=Output("files", key="file_id", revision="version"), partitions={"site": sites})
|
|
321
|
+
def site_files(ctx):
|
|
322
|
+
# Patch both ways: rows upsert by key, remove deletes keys.
|
|
323
|
+
return Patch(rows, remove=gone)
|
|
324
|
+
|
|
325
|
+
|
|
326
|
+
@asset(
|
|
327
|
+
outputs=Output("digests", key="file_id"),
|
|
328
|
+
partitions={"site": sites, "day": TimePartitions(start="2026-01-01", every="1d")},
|
|
329
|
+
)
|
|
330
|
+
def daily_digests(ctx, site_files): ...
|
|
331
|
+
|
|
332
|
+
|
|
333
|
+
project = Project(assets=[site_files, daily_digests], sources=[sites], name="mine")
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
Save as `my_project.py` and `uv run solera serve --insecure --project
|
|
337
|
+
my_project.py` (the attribute defaults to `project`). Cursors, resources,
|
|
338
|
+
`Incremental`/`AllPartitions` inputs, placements, triggers, and the Postgres stores
|
|
339
|
+
are documented in [docs/architecture.md](docs/architecture.md);
|
|
340
|
+
`apps/server/src/solera_server/demo.py` exercises all of them.
|
|
341
|
+
|
|
342
|
+
## Tests
|
|
343
|
+
|
|
344
|
+
```bash
|
|
345
|
+
uv run pytest -q # includes tests/test_demo_e2e.py (server + pool worker, temp file:// store)
|
|
346
|
+
SOLERA_TEST_DATABASE_URL=postgresql://solera:solera@127.0.0.1:5432/solera uv run pytest -q -m postgres
|
|
347
|
+
pnpm install --frozen-lockfile && pnpm -C apps/console exec playwright install chromium && pnpm -C apps/console test
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
CI runs the Python suite, the Playwright suite on desktop and mobile, and a
|
|
351
|
+
wheel-contents check. `uv.lock` and `pnpm-lock.yaml` are committed; installs
|
|
352
|
+
are locked.
|
|
353
|
+
|
|
354
|
+
## Boundaries
|
|
355
|
+
|
|
356
|
+
This is a feasibility implementation, not a claim of production readiness.
|
|
357
|
+
Metadata transitions serialize through conditional object-store writes;
|
|
358
|
+
catalog/history scans are unpaginated. Remote placements (AWS ECS, Kubernetes
|
|
359
|
+
jobs, Modal) exist behind `SOLERA_*` configuration but see far less exercise
|
|
360
|
+
than `Local`/`Pool`. There is no artifact garbage collector, retained
|
|
361
|
+
historical code image, or multi-replica writer election. Read
|
|
362
|
+
[docs/architecture.md](docs/architecture.md) before extending the backend.
|
|
363
|
+
|
|
364
|
+
## License
|
|
365
|
+
|
|
366
|
+
Apache-2.0.
|