Technical reference ​

This page is for technical operators, data teams, and AI agents that need to understand Orloi's implementation boundaries.

Choose the detail you need ​

Those pages are deliberately precise about schema versions, privileges, SQL bounds, and lifecycle limits. They describe the current product surface, not a stable public API.

Data lineage and freshness ​

flowchart LR
  airtable["In-scope Airtable activity"]
  payload["Webhook payload\nand capture task"]
  raw["Raw events\ncanonical source-proximate history"]
  compact["Compaction task"]
  compacted["Compacted events\nreadable derived history"]
  deterministic["Deterministic derived work\nmetrics and dashboard facts"]
  interpreted["Optional AI-backed work\nreports and interpretations"]
  surfaces["Dashboard, reports,\nalerts, signals, process views"]

  airtable --> payload --> raw --> compact --> compacted
  raw --> deterministic
  compacted --> deterministic
  compacted --> interpreted
  deterministic --> surfaces
  interpreted --> surfaces

  payload -. "delivery, access, or task failure" .-> captureDelay["No new raw event yet"]
  compact -. "backlog or task failure" .-> compactionDelay["Raw current; derived history stale"]
  deterministic -. "window, input, or task failure" .-> derivedDelay["Some surfaces stale or incomplete"]
  interpreted -. "feature, provider, or task failure" .-> derivedDelay

Text alternative: A new in-scope Airtable change becomes a raw event through a webhook/capture task. A separate compaction task creates readable compacted events. Further work computes deterministic outputs such as metrics and dashboard facts, or optional AI-backed reports and interpretations. The dashboard, alerts, signals, and process views can therefore lag behind raw capture. Capture, compaction, and later derived work can each fail or become stale independently.

Freshness checks ​

When a recent in-scope Airtable change is missing or delayed, check the stages in order:

  1. Observation active — the observed base is configured to capture future activity.
  2. Latest raw event — the change reached the customer Postgres destination.
  3. Latest compacted event — readable activity history caught up.
  4. Affected result — the report, metric, alert, or process view had time to use that history.

A later stage can lag an earlier one. A current raw-event time shows that observation and capture are working; it does not prove that every derived surface is current.

If raw activity does not advance, check Airtable access, the selected scope, whether the base is active, and the provider's availability. If raw activity advances but compacted activity does not, allow for processing backlog and raise the issue with the operating team. If only one result is delayed, inspect that feature's status and time window. A task retry can resume the current path, but it is not a promise that old data will be recreated.

Restore normal database access before trusting dashboard results when a database health warning appears. After a repair, make another small in-scope change and verify raw activity, compacted activity, and the affected view in that order.

Recovery boundaries ​

An interval can be incomplete when the base was inactive, access was invalid, a field was outside scope, or the database was unavailable. Keep that context visible when interpreting trends; do not treat the interval as zero activity.

Orloi does not provide a general-purpose historical import or replay flow for these gaps. Use Airtable or another original source when a decision depends on a missing period.

When escalating, share the observed base, the test change and its Airtable time, raw and compacted activity times, the affected report or metric, and any recent Airtable or database change. This usually distinguishes a source-access problem, processing delay, or storage issue.

Table families and storage layers ​

The Architecture and stored data page is the Advanced guide to raw activity, readable activity, metrics, reports, alerts, signals, process data, and AI-derived output. The Data reference is the source for table families, columns, compatibility notes, sensitivity, and schema-version checks.

Use those pages when the distinction between source-proximate history, readable derived history, and later outputs affects an investigation or integration. Do not infer a retention guarantee from a table name or from a provenance link; the Raw event retention guide and its optional SQL procedure define the documented cleanup paths.

Optional AI path ​

flowchart LR
  context["Compacted events and\nfeature-specific stored context"]
  settings["Configured feature,\nprovider, and model"]
  provider["External AI provider"]
  output["Report or other\nAI-backed interpretation"]
  postgres["Customer Postgres\norloi schema"]

  context --> settings --> provider --> output --> postgres

Text alternative: When an AI-backed feature is enabled and runs, Orloi uses compacted events and the stored context required by that feature, sends it to the configured provider and model, then stores the resulting report or interpretation in the customer Postgres orloi schema. This path is separate from raw capture and deterministic metrics.

Provider connectivity and schema upgrades ​

Orloi accepts a standard TCP postgres:// or postgresql:// connection string. The saved connection must be reachable from Orloi and must be able to create and manage the dedicated orloi objects that Orloi owns. Orloi does not support the Prisma Accelerate prisma+postgres:// URL or an HTTP database API.

For provider setup, keep the exact URL and role that will be saved in view. Do not test with a more privileged local administrator connection and then save a different, weaker connection. Provider backups and recovery remain the customer's responsibility.

Network and TLS boundaries ​

  • The host and port must be reachable from Orloi; a database reachable only from a laptop or private network that Orloi cannot join will not work.
  • With the current integration, sslmode=require enables encrypted TLS but does not provide certificate verification. Orloi cannot accept a custom CA file or configure verify-full. Do not use this setup path when policy requires certificate verification or private-only networking that Orloi cannot reach.
  • Supabase's direct connection is the preferred persistent connection. If Orloi cannot reach its IPv6 direct endpoint, use the provider-documented shared pooler session mode rather than the transaction pooler.
  • Neon migrations and session settings favor its direct, non-pooled URL. Retain the URL's TLS parameters rather than stripping them to work around a pooler limitation.
  • An RDS private instance needs a network path from Orloi through its VPC or other approved routing. Do not expose it publicly only to test setup. The current setup flow is not suitable when an RDS CA bundle and full certificate verification are mandatory.
  • Railway's private *.railway.internal host is not reachable by an external Orloi connection. Its public TCP URL is an intentional exposure decision and must be reviewed for TLS and access controls.

See Postgres connection help for the normal setup entry point and current provider links. The Manage page intentionally does not contain these networking and TLS details.

Schema ownership and upgrades ​

The connection used for setup and runtime must retain ownership-level control of the Orloi-managed objects because Orloi checks and upgrades them through the saved connection. Ordinary read or write grants are not a substitute for that upgrade capability. Do not manually drop, recreate, alter, or downgrade Orloi tables as an upgrade procedure.

If a later upgrade fails, restore the saved connection's ability to manage the objects and retry through the normal product path. For agent and BI access, use a separate read-only path; do not reuse the setup/runtime credential. The AI agent database access page describes the role separation in detail.

Database moves and destructive operations ​

Replacing the saved Postgres connection is not a historical-data migration:

  • Future processing uses the new destination after the replacement succeeds.
  • The old database keeps the data already written there; Orloi does not copy or delete it.
  • The new database starts with only the objects and data it receives after it becomes the destination.

For a password or network rotation on the same database, test and replace the connection string, then verify a fresh in-scope event. For a database move, retain or export the old database as required and plan any historical copy or consolidation yourself. Orloi does not currently provide a documented migration, merge, or rollback workflow for historical data between destinations.

Deleting an observed base is a Manage action that removes the Orloi engine configuration; it does not delete the customer-owned Postgres database or its stored data. Deleting that database, dropping the Orloi schema, or deleting stored rows outside the documented Raw event retention workflows is a destructive database-owner or provider-admin action. Back up or export what must be retained and confirm the legal, contractual, and recovery implications before doing it.

BI and agent isolation ​

BI tools and agents should use a dedicated read-only access path rather than the connection that installs, upgrades, and writes Orloi data. A reader with access to the underlying Orloi tables may be able to read every observed base in that destination.

sync_id, a dashboard filter, or a prompt is not an authorization boundary. For single-base access, use a dedicated database or destination, an authenticated API with server-enforced allowlisted queries, separately owned restricted views, or tested row-level security. The full role, grant, and isolation procedures are in AI agent database access; bounded recurring exports and customer-owned BI models are in the SQL and BI cookbook.