Struct Runtime 

pub struct Runtime { /* private fields */ }

A manifest-driven runtime that executes CRUD operations against an underlying data store. Two backends are supported:

• SQLite (default): single-process, file-or-memory, with a write mutex + read pool, FTS5 search, and per-row LoroDoc CRDT snapshots.
• Postgres: live cluster, suitable for multi-replica deployments. Routes entity CRUD through pylon_storage::pg_datastore::PostgresDataStore. CRDT mode and FTS5-shaped search are SQLite-only at this layer; the Postgres backend returns NOT_SUPPORTED for those paths and the router degrades to JSON change events (no binary CRDT broadcasts).

Pick a backend by passing a postgres:// URL to Runtime::open; any other string is treated as a SQLite filesystem path.

Implementations

impl Runtime

pub fn open(url: &str, manifest: AppManifest) -> Result<Self, RuntimeError>

Open a runtime against either a SQLite file path or a Postgres URL.

Backend selection is by URL prefix:

• postgres://... or postgresql://... → Postgres (requires the postgres-live feature on pylon-storage, enabled by default).
• Anything else → SQLite, treating the string as a filesystem path (":memory:" works via Runtime::in_memory instead).

pub fn open_postgres( url: &str, manifest: AppManifest, ) -> Result<Self, RuntimeError>

Open a runtime backed by a live Postgres cluster.

Schema must be applied separately via pylon migrate / the storage adapter’s plan apply path — Runtime does not auto-create tables on Postgres (in contrast to SQLite, where from_connection runs CREATE TABLE IF NOT EXISTS on every open). This matches how production Postgres deployments are typically managed: schema is migrated via a controlled, observable step, not as a side effect of the server starting up.

pub fn is_in_memory(&self) -> bool

Returns true if this runtime is backed by an in-memory SQLite DB.

Stored at open time rather than queried via conn.path() because the path-based check conflates “no filename” with “in-memory”: Connection::open("") yields a file-backed DB with empty path, and would falsely pass as in-memory. Since we always know at construction time which constructor was used, track the bit.

Gates the test-reset endpoint — a false positive here would let /api/__test__/reset truncate real tables.

pub fn db_path(&self) -> Option<String>

Filesystem path to the SQLite database, if this runtime is file-backed. Returns None for in-memory runtimes AND Postgres runtimes (no local file). Used by the server bootstrap to derive companion paths (session store, change log persistence) without requiring the caller to pass them in.

pub fn reset_for_tests(&self) -> Result<(), RuntimeError>

Drop every row from every entity table. Intended for test harnesses that call /api/__test__/reset between cases; refuses to run on anything but an in-memory database.

Does NOT drop the tables themselves — schema stays, indexes stay, triggers stay. Just truncates user data + the change log.

pub fn in_memory(manifest: AppManifest) -> Result<Self, RuntimeError>

Create an in-memory SQLite-backed runtime (useful for tests and benchmarks). For Postgres-backed equivalents, use open_postgres with a test-cluster URL.

pub fn ensure_search_indexes(&self) -> Result<(), RuntimeError>

Create the search index tables (_facet_bitmap, per-entity _fts_<Entity>, and a covering index for each declared sortable field) for every searchable entity in the manifest.

Production deployments do this via the storage adapter’s apply_schema / migration plan; that path also handles adding/removing the tables when a search: block is added or removed across deploys. This method is a quick path for tests and benchmarks that build a Runtime::in_memory(...) directly without going through the schema-plan pipeline.

pub fn manifest(&self) -> &AppManifest

Return a reference to the app manifest.

pub fn lock_conn_pub(&self) -> Result<MutexGuard<'_, Connection>, RuntimeError>

Expose the write connection mutex for transactional operations. SQLite-only — Postgres mode returns NOT_SQLITE_BACKEND. Callers that need a transaction on Postgres should use [Runtime::transact_ops] (via the DataStore trait), which routes to a real Postgres transaction inside PostgresDataStore.

pub fn read_pool_size(&self) -> usize

Return the number of read connections in the pool. Always 0 for in-memory SQLite (pool is empty by design) and for Postgres mode (the pool concept doesn’t apply — PostgresDataStore manages its own connection internally).

pub fn is_postgres(&self) -> bool

Return true if this runtime is backed by Postgres. Useful for SQLite-only fast-paths to early-exit cleanly.

pub fn crdt_store(&self) -> &LoroStore

Borrow the CRDT store. SQLite-only — Postgres mode does not yet support per-row CRDT snapshots at the runtime layer (CRDT broadcasts degrade to JSON change events).

Panics

Panics on Postgres backend. Call sites that may run under either backend should branch on is_postgres() first.

pub fn insert(&self, entity: &str, data: &Value) -> Result<String, RuntimeError>

Insert a new row. Returns the generated ID.

For entities with crdt: true (the default) the LoroDoc snapshot

• the SQLite materialized row are committed together in a single SQLite transaction so a crash between the two leaves neither. crdt: false entities skip the LoroDoc and use a direct write (legacy LWW path). Both produce the same on-disk row shape, so reads, indexes, FTS, and policies don’t change between modes.

pub fn get_by_id( &self, entity: &str, id: &str, ) -> Result<Option<Value>, RuntimeError>

Get a single row by ID.

pub fn list(&self, entity: &str) -> Result<Vec<Value>, RuntimeError>

List all rows for an entity.

pub fn list_after( &self, entity: &str, after: Option<&str>, limit: usize, ) -> Result<Vec<Value>, RuntimeError>

List rows after a cursor ID (for cursor-based pagination).

pub fn update( &self, entity: &str, id: &str, data: &Value, ) -> Result<bool, RuntimeError>

Update a row by ID. Returns true if a row was found and updated.

For entities with crdt: true (the default) the LoroDoc receives the patch first; the SQLite UPDATE writes the same fields so the materialized view stays in lockstep with the doc state.

pub fn delete(&self, entity: &str, id: &str) -> Result<bool, RuntimeError>

Delete a row by ID. Returns true if a row was actually deleted.

pub fn lookup( &self, entity: &str, field: &str, value: &str, ) -> Result<Option<Value>, RuntimeError>

Lookup a single row by a field value (e.g., email).

pub fn link( &self, entity: &str, id: &str, relation: &str, target_id: &str, ) -> Result<bool, RuntimeError>

Link two entities by setting a foreign-key field.

pub fn unlink( &self, entity: &str, id: &str, relation: &str, ) -> Result<bool, RuntimeError>

Unlink a relation by setting the foreign-key field to null.

pub fn query_filtered( &self, entity: &str, filter: &Value, ) -> Result<Vec<Value>, RuntimeError>

Execute a filtered query with operators ($not, $gt, $in, $like, $order, $limit).

pub fn query_graph(&self, query: &Value) -> Result<Value, RuntimeError>

Execute a graph-style query.

Input: { "User": { "where": { "email": "..." }, "include": { "posts": {} } } } Returns nested results following relations.

pub fn insert_with_conn( &self, conn: &Connection, entity: &str, data: &Value, ) -> Result<String, RuntimeError>

Insert using an already-locked connection (for transactions).

pub fn update_with_conn( &self, conn: &Connection, entity: &str, id: &str, data: &Value, ) -> Result<bool, RuntimeError>

Update using an already-locked connection (for transactions).

pub fn delete_with_conn( &self, conn: &Connection, entity: &str, id: &str, ) -> Result<bool, RuntimeError>

Delete using an already-locked connection (for transactions).

pub fn get_by_id_with_conn( &self, conn: &Connection, entity: &str, id: &str, ) -> Result<Option<Value>, RuntimeError>

Read a row by id using a pre-held connection (for transactions).

pub fn list_with_conn( &self, conn: &Connection, entity: &str, ) -> Result<Vec<Value>, RuntimeError>

List rows using a pre-held connection (for transactions).

pub fn list_after_with_conn( &self, conn: &Connection, entity: &str, after: Option<&str>, limit: usize, ) -> Result<Vec<Value>, RuntimeError>

List after cursor using a pre-held connection (for transactions).

pub fn lookup_with_conn( &self, conn: &Connection, entity: &str, field: &str, value: &str, ) -> Result<Option<Value>, RuntimeError>

Lookup by field using a pre-held connection (for transactions).

pub fn link_with_conn( &self, conn: &Connection, entity: &str, id: &str, relation: &str, target_id: &str, ) -> Result<bool, RuntimeError>

Link relation using a pre-held connection (for transactions).

pub fn unlink_with_conn( &self, conn: &Connection, entity: &str, id: &str, relation: &str, ) -> Result<bool, RuntimeError>

Unlink relation using a pre-held connection (for transactions).

pub fn query_filtered_with_conn( &self, conn: &Connection, entity: &str, filter: &Value, ) -> Result<Vec<Value>, RuntimeError>

Query with filters using a pre-held connection (for transactions).

Shares the filter-building logic with [query_filtered] by executing against the provided connection rather than acquiring one.

pub fn query_graph_with_conn( &self, conn: &Connection, query: &Value, ) -> Result<Value, RuntimeError>

Graph query using a pre-held connection (for transactions).

pub fn aggregate( &self, entity: &str, spec: &Value, ) -> Result<Value, RuntimeError>

Run an aggregation query. See pylon_http::DataStore::aggregate for the spec shape.

pub fn pg_data_store_pub(&self) -> Option<&PostgresDataStore>

Borrow the underlying Postgres DataStore if this runtime is Postgres-backed. Used by the DataStore adapter in datastore.rs to delegate transact/search etc. without re-implementing them. Accessor for the underlying PostgresDataStore. Used by integration tests to exercise in-tx primitives directly without going through a TS function handler. Also useful for callers that need to drop down to raw PG (e.g. running an EXPLAIN against the live cluster from an admin tool). Returns None on SQLite-backed runtimes.

Trait Implementations

impl DataStore for Runtime

fn search(&self, entity: &str, query: &Value) -> Result<Value, DataError>

Bridge the typed SearchQuery / SearchResult shapes to the trait’s JSON-in / JSON-out contract. The router passes a JSON body; we deserialize, look up the entity’s SearchConfig, run the planner, and re-serialize. Serialization round-tripping lets this method live on the DataStore trait without forcing pylon-http to depend on pylon-storage.

fn crdt_snapshot( &self, entity: &str, row_id: &str, ) -> Result<Option<Vec<u8>>, DataError>

Return the binary CRDT snapshot for a row. Ok(None) for any entity with crdt: false (the LWW opt-out) — the router uses that to decide whether to ship a binary update over WebSocket after the write.

fn crdt_apply_update( &self, entity: &str, row_id: &str, update: &[u8], ) -> Result<Vec<u8>, DataError>

Client-pushed Loro update. Imports into the row’s LoroDoc, re-projects the doc state into the materialized SQLite columns (so subsequent reads see the merged content), and returns the fresh full-row snapshot for the router to broadcast to other clients.

Wrapped in a single SQLite transaction — same crash-safety shape as Runtime::insert/update. Either the LoroStore + SQLite columns both update or neither does.

fn manifest(&self) -> &AppManifest

fn insert(&self, entity: &str, data: &Value) -> Result<String, DataError>

fn get_by_id(&self, entity: &str, id: &str) -> Result<Option<Value>, DataError>

fn list(&self, entity: &str) -> Result<Vec<Value>, DataError>

fn list_after( &self, entity: &str, after: Option<&str>, limit: usize, ) -> Result<Vec<Value>, DataError>

fn update( &self, entity: &str, id: &str, data: &Value, ) -> Result<bool, DataError>

fn delete(&self, entity: &str, id: &str) -> Result<bool, DataError>

fn lookup( &self, entity: &str, field: &str, value: &str, ) -> Result<Option<Value>, DataError>

fn link( &self, entity: &str, id: &str, relation: &str, target_id: &str, ) -> Result<bool, DataError>

fn unlink( &self, entity: &str, id: &str, relation: &str, ) -> Result<bool, DataError>

fn query_filtered( &self, entity: &str, filter: &Value, ) -> Result<Vec<Value>, DataError>

fn query_graph(&self, query: &Value) -> Result<Value, DataError>

fn aggregate(&self, entity: &str, spec: &Value) -> Result<Value, DataError>

Run an aggregation query.

fn transact(&self, ops: &[Value]) -> Result<(bool, Vec<Value>), DataError>

Execute transactional operations. Each element is a JSON object with op (“insert”/“update”/“delete”), entity, and optionally id/data.