Setup ​

Use this guide when connecting an Airtable base to a Postgres destination for the first time.

Prerequisites ​

Before setup, decide:

  • which Airtable base Orloi should observe
  • which tables and fields are in scope
  • which Postgres database should receive Orloi data
  • who should be allowed to query the resulting changelog
  • whether AI-derived reports and summaries should be enabled

Orloi is designed around customer-owned Postgres storage. The database destination must be reachable by Orloi and must allow Orloi to install objects in a dedicated orloi schema.

Connect Airtable ​

Connect the Airtable account that can access the base you want to observe.

Use a connected Airtable account or OAuth authorization that has access to the target base and the tables in scope. If a table or field is not visible to that account or authorization, Orloi cannot reliably capture and interpret it.

Orloi reads Airtable metadata and activity for the selected scope. It does not write back to Airtable.

Airtable access requirements ​

The connected Airtable account or OAuth authorization must be able to read the selected base, selected tables, schema metadata, and in-scope fields.

Orloi does not write records, update fields, or modify Airtable schema.

If the connected account or authorization cannot access a table or field, Orloi cannot reliably capture or interpret changes for it.

Airtable permissions define what Orloi can access. Orloi scope defines what Orloi captures, stores, and uses after connection.

The exact Airtable OAuth scopes are shown during connection and may depend on the integration mode.

Configure base scope ​

Scope means the base, tables, and fields Orloi is allowed to capture.

Choose the base Orloi should observe, then confirm which tables and fields are in scope.

Exclude sensitive tables or fields before activation. Orloi starts capturing new in-scope activity only after activation.

Orloi captures new activity after activation. It does not reconstruct historical Airtable activity by default.

Connect Postgres ​

Connect the Postgres database where Orloi should store changelog data.

Orloi writes to a dedicated orloi schema. During installation, the connected database role must be able to create and manage that schema and its objects.

Simple setup: use one Postgres role for installation and runtime.

Stricter setup: use an elevated install role first, then switch to a narrower runtime role.

After installation, runtime permissions should be limited to the objects Orloi needs to insert, update, and read in the orloi schema. If you want separate install and runtime roles, install with the privileged role first, then configure the runtime connection with the narrower role.

Orloi works with standard Postgres-compatible databases that provide a reachable connection string and allow the required schema permissions.

Common candidates include Supabase, Neon, RDS, and Railway. Confirm networking, SSL, and schema permissions before activation.

Required Postgres permissions ​

During installation, Orloi needs permission to:

  • create the orloi schema
  • create tables, indexes, and internal metadata objects inside that schema
  • run schema upgrades for Orloi-managed objects

At runtime, Orloi needs permission to:

  • insert raw events
  • insert and update processing state
  • write compacted events, reports, metrics, and dashboard signals
  • read Orloi-managed tables for processing and dashboard views

Orloi does not need permission to modify your existing application schemas.

Activate capture ​

Activate the engine after Airtable scope and Postgres storage have both been configured.

Orloi only starts capture after the Postgres destination has been installed and verified. If storage setup fails, Orloi does not start capture.

Successful activation means:

  • the orloi schema exists
  • Orloi-managed tables and indexes were installed
  • the engine is enabled for the selected Airtable base and scope
  • the dashboard can show engine status and freshness

Verify installation ​

After activation, make a small change in an in-scope Airtable table.

Within the first few minutes, check the dashboard or Postgres destination for:

  • engine status showing active
  • last raw event time updating
  • latest compacted event time updating after processing
  • no setup or capture errors
  • dashboard freshness showing current status

If there is no activity in the selected Airtable scope, Orloi may have nothing new to show yet.

Troubleshooting setup ​

If Airtable connection fails, confirm the connected Airtable account or OAuth authorization can access the selected base and tables.

If Postgres installation fails, confirm the connection string, SSL settings, network allowlists, and schema creation permissions.

If activation succeeds but no events appear, confirm that new changes are happening in tables included in scope.

If Postgres becomes unavailable after activation, Orloi is designed to fail visibly instead of silently discarding captured history. Check dashboard status and logs before trusting freshness-sensitive reports or metrics.