Persistence facade: the Store protocol, the connection lifecycle and the
guarantees every backend gets before it sees a call.
SQLite is the one backend Vis ships. Its namespace loads on the first store
operation, not with this facade (see sqlite), so commands that never touch
the store skip ~480 ms of JDBC/Hikari/Flyway class loading on a cold JVM.
Every Store op forwards to that backend, which hands the facade its
implementation through store-implementation: a backend missing an op fails
to compile.
Frontends still call db-error->user-message here; the backend owns the
actual translation. Same for the store-staleness check the process-wide
shared connection uses.
Persistence facade: the `Store` protocol, the connection lifecycle and the guarantees every backend gets before it sees a call. SQLite is the one backend Vis ships. Its namespace loads on the first store operation, not with this facade (see `sqlite`), so commands that never touch the store skip ~480 ms of JDBC/Hikari/Flyway class loading on a cold JVM. Every `Store` op forwards to that backend, which hands the facade its implementation through `store-implementation`: a backend missing an op fails to compile. Frontends still call `db-error->user-message` here; the backend owns the actual translation. Same for the store-staleness check the process-wide shared connection uses.
Automation operations of a persistence backend, with the Store dispatch. They
are a separate protocol because one protocol with every op exceeds the JVM limit
for the size of one method. Rows keep column names. A definition is canonical
JSON with string keys.
Automation operations of a persistence backend, with the `Store` dispatch. They are a separate protocol because one protocol with every op exceeds the JVM limit for the size of one method. Rows keep column names. A definition is canonical JSON with string keys.
(db-automation-get db-info id)(db-automation-last-runs db-info)The newest run of each automation that has runs, by automation id.
The newest run of each automation that has runs, by automation id.
(db-automation-update-run! db-info id statuses attrs)Change a run only while its status is in statuses. Answer the new row or nil.
Change a run only while its status is in `statuses`. Answer the new row or nil.
(db-automation-update-delivery! db-info id attrs)(db-automation-put! db-info row)(db-automation-prune-runs! db-info automation-id limit)(db-automation-run db-info id)One run, with the name of its automation as automation_name.
One run, with the name of its automation as `automation_name`.
(db-automation-list db-info)(db-automation-runs db-info opts)Runs newest first, each with automation_name.
Runs newest first, each with `automation_name`.
(db-automation-delete! db-info id)(db-automation-enqueue-delivery! db-info row)(db-automation-stamps db-info)The id, enabled and updated_at of each automation, without the definition.
The `id`, `enabled` and `updated_at` of each automation, without the definition.
(db-automation-claim-run! db-info row)Insert a run unless its trigger key exists. Answer the inserted row or nil.
Insert a run unless its trigger key exists. Answer the inserted row or nil.
(db-automation-due-deliveries db-info now limit)Due pending callbacks, with the current callback_url and callback_secret.
Due pending callbacks, with the current `callback_url` and `callback_secret`.
(bound-error-data error)Bound every string inside a structured terminal error, at any depth. Pure; nil in, nil out.
Bound every string inside a structured terminal error, at any depth. Pure; nil in, nil out.
(bounded-error-text s)(bounded-error-text s max-chars)Truncate ONE diagnostic string so the result NEVER exceeds max-chars,
naming what was cut. A string already within the cap comes back identical, so
a normal error is persisted byte for byte.
Truncate ONE diagnostic string so the result NEVER exceeds `max-chars`, naming what was cut. A string already within the cap comes back identical, so a normal error is persisted byte for byte.
(db-create-connection! db-spec)Open a persistence connection from db-spec.
Common spec forms: nil - no DB (returns nil) :memory - in-memory ephemeral store "path/to.db" - file-backed store {:backend :sqlite :path ...} - explicit backend selection {:backend :sqlite :datasource ds} - caller-owned DataSource
SQLite is the only backend; a spec naming another :backend is refused.
Open a persistence connection from `db-spec`.
Common spec forms:
nil - no DB (returns nil)
:memory - in-memory ephemeral store
"path/to.db" - file-backed store
{:backend :sqlite :path ...} - explicit backend selection
{:backend :sqlite :datasource ds} - caller-owned DataSource
SQLite is the only backend; a spec naming another `:backend` is refused.(db-dispose-shared-connection!)Close the shared connection if one is open. Idempotent.
Close the shared connection if one is open. Idempotent.
(db-error->user-message e)Translate a persistence exception into something a human can act on.
The backend owns backend-specific recognition; unknown errors fall
back to (ex-message e).
Translate a persistence exception into something a human can act on. The backend owns backend-specific recognition; unknown errors fall back to `(ex-message e)`.
(db-shared-connection! db-spec)Return the process-wide shared persistence connection for db-spec,
opening it on first call and caching the handle for the lifetime of
the JVM. Subsequent calls return the cached handle regardless of
the db-spec argument - the singleton intentionally pins to the
first spec it saw.
Pair with db-dispose-shared-connection! on process shutdown.
Return the process-wide shared persistence connection for `db-spec`, opening it on first call and caching the handle for the lifetime of the JVM. Subsequent calls return the cached handle regardless of the `db-spec` argument - the singleton intentionally pins to the first spec it saw. Pair with `db-dispose-shared-connection!` on process shutdown.
Hard cap on ONE persisted DIAGNOSTIC string (256K chars).
SQLite refuses any bound value over SQLITE_MAX_LENGTH (1e9 bytes) with
[SQLITE_TOOBIG], and the value carrying a turn's terminal error is the one
most likely to be unbounded: a runtime message can quote the entire document
that broke it. An error is a DIAGNOSTIC, so a truncated head is worth
strictly more than the lost turn an oversized one costs. An answer's own
content and the CTX snapshot are DATA and are never truncated here -- an
oversized one degrades through the caller's outcome guard instead.
Hard cap on ONE persisted DIAGNOSTIC string (256K chars). SQLite refuses any bound value over `SQLITE_MAX_LENGTH` (1e9 bytes) with `[SQLITE_TOOBIG]`, and the value carrying a turn's terminal error is the one most likely to be unbounded: a runtime message can quote the entire document that broke it. An error is a DIAGNOSTIC, so a truncated head is worth strictly more than the lost turn an oversized one costs. An answer's own content and the CTX snapshot are DATA and are never truncated here -- an oversized one degrades through the caller's outcome guard instead.
Queued-turn operations of a persistence backend, with the Store dispatch. They
are a separate protocol for the same JVM method-size limit as AutomationStore.
Queued-turn operations of a persistence backend, with the `Store` dispatch. They are a separate protocol for the same JVM method-size limit as `AutomationStore`.
(db-list-queued-turn-attachments db-info queued-turn-ids)(db-store-queued-turn-attachments! db-info
session-turn-soul-id
queued-turn-id
attachments)Every operation a persistence backend implements. The first argument is the
store db-create-connection! opened, or nil when there is none; every value
dispatches to the SQLite backend.
Every operation a persistence backend implements. The first argument is the store `db-create-connection!` opened, or nil when there is none; every value dispatches to the SQLite backend.
(db-list-session-turn-iterations db-info session-turn-ref)(db-get-session db-info ref)(db-workspace-touch-focus! db-info workspace-id)(db-archived-session-group-ids db-info)(db-latest-session-state-id db-info session-id)(db-list-session-groups db-info project-id opts)(db-seed-session-read-marks! db-info reader-id marks)(db-list-session-attachments db-info session-id)(db-append-iteration-attachment! db-info iteration-id att)(db-session-usage-stats db-info session-id)(db-search-session-matches db-info channel query)(db-search-session-matches db-info channel query session-ids)(db-checkpoint-session-turn-ctx! db-info session-turn-id state-id ctx)(db-activity-settle! db-info aid outcome summary)(db-adopt-and-reorder-project-sessions! db-info project-id session-ids)(db-list-sessions db-info channel)(db-list-session-turns-iterations-meta db-info session-turn-ids)(db-latest-turn-request-usage db-info session-turn-id)(db-agent-update! db-info session-id changes)(db-list-extension-aggregates db-info opts)(db-update-session-turn! db-info session-turn-id opts)Write a turn's terminal outcome. The facade bounds the DIAGNOSTIC text before
the backend sees it, so the write that records HOW a turn ended can never be
lost to an unbounded error message (see max-persisted-error-chars).
Write a turn's terminal outcome. The facade bounds the DIAGNOSTIC text before the backend sees it, so the write that records HOW a turn ended can never be lost to an unbounded error message (see [[max-persisted-error-chars]]).
(db-set-session-archived! db-info session-id archived?)(db-session-state-list-for-workspace db-info workspace-id)(db-fork-session-at-turn! db-info session-id opts)(db-reorder-project-sessions! db-info project-id session-ids)(db-create-extension-aggregate! db-info opts)(db-workspace-update-state! db-info workspace-id new-state)(db-council-unavailable! db-info sid id)(db-list-turn-all-attachments db-info session-turn-soul-id)(db-get-project-by-root db-info owner-id root)(db-routing-locked? db-info session-id)(db-list-turns-attachments db-info session-turn-soul-ids)(db-put-extension-aggregate! db-info opts)(db-list-iterations-attachments-meta db-info iteration-ids)(db-load-ctx-history db-info session-id)(db-get-session-group db-info group-id)(db-get-session-prompt-cache-state db-info session-state-id)(db-compare-session-goal! db-info session-id revision goal)(db-list-iteration-attachments-meta db-info iteration-id)(db-delete-session-group! db-info group-id)(db-store-iteration! db-info opts)Store one iteration row. The facade refuses opts that is not a map or lacks
:session-turn-id before the backend sees it.
Store one iteration row. The facade refuses `opts` that is not a map or lacks `:session-turn-id` before the backend sees it.
(db-session-state-set-workspace! db-info session-state-id workspace-id)(db-search db-info query opts)Backend-neutral full-text search. The backend RENDERS the neutral query DSL
into its native full-text query and runs it. No caller passes an engine
dialect — only the DSL in search-query-dsl-doc.
query is the DSL — a string (implicit-AND of its words) or a DSL map.
opts:
:owner-table restrict to one owner table (string)
:field restrict to one indexed field (string)
:limit max hits (backend default applies when nil)
Returns a vector of hits sorted by relevance (best first), each
{:owner-table :owner-id :field :snippet :rank}. Backends MUST honor the
DSL; an engine that cannot express a node should degrade it (e.g. :near ->
:all), never reject well-formed DSL. A MALFORMED query (e.g. a lone :not)
may throw — that is a DSL logic error, distinct from un-matchable content.
Backend-neutral full-text search. The backend RENDERS the neutral query DSL
into its native full-text query and runs it. No caller passes an engine
dialect — only the DSL in `search-query-dsl-doc`.
`query` is the DSL — a string (implicit-AND of its words) or a DSL map.
`opts`:
:owner-table restrict to one owner table (string)
:field restrict to one indexed field (string)
:limit max hits (backend default applies when nil)
Returns a vector of hits sorted by relevance (best first), each
`{:owner-table :owner-id :field :snippet :rank}`. Backends MUST honor the
DSL; an engine that cannot express a node should degrade it (e.g. :near ->
:all), never reject well-formed DSL. A MALFORMED query (e.g. a lone :not)
may throw — that is a DSL logic error, distinct from un-matchable content.(db-set-session-favorite! db-info session-id is-favorite)(db-list-session-turns-iterations db-info session-turn-ids)(db-store-session! db-info opts)(db-council-pending db-info sid activation gid after limit)(db-list-session-turns db-info session-ref)(db-agent-claim-iteration! db-info session-id)(db-improve-project-ids db-info)(db-find-session-by-external db-info channel ext-id)(db-list-session-states db-info session-id)(db-list-iterations db-info iteration-ids)(db-council-delivered! db-info sid ids)(db-workspace-list-drafts db-info)(db-list-projects db-info opts)(db-council-source db-info sid source)(db-mark-session-read! db-info reader-id session-id seen-answers)(db-get-extension-aggregate db-info opts)(db-council-machine-name db-info)(db-council-page db-info gid thread roots? after limit)(db-council-replay db-info sid key)(db-edit-scoped-settings! db-info scope target-id edit)(db-workspace-update-label! db-info workspace-id label)(db-lock-routing! db-info session-id locked?)(db-improve-list db-info opts)(db-council-set-machine-name! db-info name)(db-improve-update! db-info id attrs)(db-create-project! db-info opts)(db-improve-get db-info id)(db-improve-apply-review! db-info proposal still-current?)(db-resolve-session-id db-info sel)(db-update-project! db-info project-id opts)(db-set-scoped-setting! db-info scope target-id setting-id value)(db-workspace-insert! db-info opts)(db-agent-checkpoint db-info session-id)(db-create-session-group! db-info project-id opts)(db-council-unanswered db-info sid ids)(db-council-insert! db-info row recipients infer-reply?)(db-project-session-ids db-info project-id)(db-list-session-attachments-meta db-info session-id)(db-set-session-group! db-info session-id group-id)(db-agent-list db-info leader-id)(db-swap-extension-aggregate! db-info opts f args)(db-repo-focus-get db-info repo-id)(db-retry-session-turn! db-info session-turn-soul-id opts)(db-workspace-get db-info workspace-id)(db-update-session-group! db-info group-id opts)(db-get-session-goal db-info session-id)(db-fork-session! db-info session-id opts)(db-list-session-turns-by-status db-info status)(db-council-bind-wake! db-info entry-id sid activation)(db-scoped-settings db-info scope target-id)(db-claim-session! db-info ref)(db-read-attachment db-info attachment-id)(db-repo-focus-set! db-info repo-id workspace-id)(db-session-read-marks db-info reader-id)(db-improve-create! db-info attrs)(db-delete-session-tree! db-info id)(db-update-session-title! db-info ref title)(db-workspace-list-by-repo db-info repo-id)(db-workspace-list-by-repo db-info repo-id state-set)(db-workspace-for-session db-info session-state-id)(db-list-turn-attachments db-info session-turn-soul-id)(db-search-session-ids db-info channel query)(db-list-session-turn-states db-info session-turn-id)(db-list-session-turns-meta db-info session-ref)(db-get-project db-info project-id)(db-read-session-turn db-info session-ref turn-ref)(db-council-interrupt! db-info sid activation)(db-council-get db-info id)(db-session-turn-stats db-info)(db-session-turn-stats db-info session-id)Per-session turn aggregates. 1-arity: the whole store, {soul-id-str {:turn-count n :latest-turn-at Date}}. 2-arity: ONE session's stats
unwrapped (nil when unknown), so a single-session read never scans the
whole store.
Per-session turn aggregates. 1-arity: the whole store, `{soul-id-str
{:turn-count n :latest-turn-at Date}}`. 2-arity: ONE session's stats
unwrapped (nil when unknown), so a single-session read never scans the
whole store.(db-list-iteration-attachments db-info iteration-id)(db-agent-info db-info session-id)(db-activity-page db-info sid aid opts)(db-set-session-prompt-cache-state! db-info session-state-id state)(db-load-latest-ctx db-info session-id)(db-list-iterations-attachments db-info iteration-ids)(db-activity-apply! db-info sid aid event)(db-set-session-model-pref! db-info session-id provider model)(db-delete-extension-aggregates! db-info opts)(db-session-group-session-ids db-info group-id)(db-set-turn-attachment-transcription! db-info
session-turn-soul-id
position
transcription
segments)(db-delete-project! db-info project-id)(db-store-session-turn! db-info opts)(db-get-session-model-pref db-info session-id)(db-log! db-info opts)(db-turn-history db-info session-ref)(db-set-session-project! db-info session-id project-id)(store-implementation)Expand, inside a backend namespace, to its op map for Store, AutomationStore
and QueueStore: every op keyed to the backend's own fn of the same name. A
backend missing an op fails to compile instead of failing at its first call.
Expand, inside a backend namespace, to its op map for `Store`, `AutomationStore` and `QueueStore`: every op keyed to the backend's own fn of the same name. A backend missing an op fails to compile instead of failing at its first call.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |