Persistence

Persistence is a core principle of Cascaide. It makes Cascaide applications durable and resumable — even across process restarts or failures.

Cascaide persistence depends on access to a database that implements a specific schema. This schema consists of three tables: cascades, node_executions, and context_events.

This data goes to the database you point it at, and does not require anything specific to cascaide. This gives you excellent basis for data privacy and compliance.

Schema


-- Enums
CREATE TYPE cascade_status AS ENUM (
  'RUNNING',
  'COMPLETED',
  'ERROR'
);
 
CREATE TYPE execution_status AS ENUM (
  'RUNNING',
  'COMPLETED',
  'FAILED'
);
 
-- Table: cascades
CREATE TABLE cascades (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  status cascade_status NOT NULL DEFAULT 'RUNNING',
  fn_id INTEGER NOT NULL DEFAULT 0,
  user_id TEXT NOT NULL,
  created_at TIMESTAMP NOT NULL DEFAULT now(),
  updated_at TIMESTAMP NOT NULL DEFAULT now()
);
 
CREATE INDEX cascades_user_id_status_idx
  ON cascades (user_id, status);
 
-- Table: node_executions
CREATE TABLE node_executions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  node_instance_id TEXT NOT NULL UNIQUE,
  cascade_id UUID NOT NULL,
  node_name TEXT NOT NULL,
  function_id INTEGER NOT NULL,
  input_context JSONB NOT NULL,
  full_output JSONB,
  location TEXT NOT NULL,
  status execution_status NOT NULL DEFAULT 'RUNNING',
  error TEXT,
  started_at TIMESTAMP NOT NULL DEFAULT now(),
  completed_at TIMESTAMP,
  CONSTRAINT fk_node_executions_cascade
    FOREIGN KEY (cascade_id)
    REFERENCES cascades(id)
    ON DELETE CASCADE,
  CONSTRAINT node_executions_cascade_function_unique
    UNIQUE (cascade_id, function_id)
);
 
-- Table: context_events
CREATE TABLE context_events (
  id SERIAL PRIMARY KEY,
  key TEXT NOT NULL,
  value JSONB NOT NULL,
  ui_value JSONB,
  function_id INTEGER NOT NULL,
  cascade_id UUID NOT NULL,
  created_at TIMESTAMP NOT NULL DEFAULT now(),
  CONSTRAINT fk_context_events_cascade
    FOREIGN KEY (cascade_id)
    REFERENCES cascades(id)
    ON DELETE CASCADE
);
 
CREATE INDEX context_events_cascade_function_idx
  ON context_events (cascade_id, function_id);

Tables

`cascades`

A cascade represents a single workflow run — a sequence of node executions that “cascade” into one another.

Column	Type	Description
`id`	`UUID`	Primary key, auto-generated.
`status`	`cascade_status`	`RUNNING`, `COMPLETED`, `ERROR`.
`fn_id`	`INTEGER`	Step counter.
`user_id`	`TEXT`	User who initiated the cascade.
`created_at`	`TIMESTAMP`	Created time.
`updated_at`	`TIMESTAMP`	Last updated.

`node_executions`

Represents a single step in a workflow.

Column	Type	Description
`id`	`UUID`	Primary key.
`node_instance_id`	`TEXT`	Unique instance ID generated at runtime.
`cascade_id`	`UUID`	Parent cascade this node belongs to.
`node_name`	`TEXT`	Node name as registered in your graph.
`function_id`	`INTEGER`	Step index.
`input_context`	`JSONB`	Input data.
`full_output`	`JSONB`	Output data as `PostResult`.
`location`	`TEXT`	Records where the persistence call happened, where was this node initiated.
`status`	`execution_status`	Status.
`error`	`TEXT`	Error message.
`started_at`	`TIMESTAMP`	Start time.
`completed_at`	`TIMESTAMP`	End time.

`context_events`

Event log of all context writes.

Column	Type	Description
`id`	`SERIAL`	Primary key.
`key`	`TEXT`	Context key.
`value`	`JSONB`	Stored value.
`ui_value`	`JSONB`	UI-friendly value.
`function_id`	`INTEGER`	Step index.
`cascade_id`	`UUID`	Parent cascade.
`created_at`	`TIMESTAMP`	Timestamp.

Note on function_id : If a node_execution and context_event share the same function_id within a cascade, it means that the context event was created by that node. Important caveat: UI nodes push the context update onto the next persistent node as UI nodes are often ephemeral.

How They Relate


cascades
  ├── node_executions
  └── context_events

All the values are automatically assigned by Cascaide. When the hydration middleware runs, it automatically pulls the data and reconstructs the local state for use. The persistence middlewares automatically populate the tables as the workflows run.