Connect a Postgres table

The postgres connector polls a table and emits one event per new or changed row, keyed by an entity column. It cursors over a monotonic column — an autoincrement id (inserts only) or an updated_at timestamp (inserts and updates).

Install the Postgres extra

The connector needs the asyncpg driver:


uv tool install 'navflow[postgres]'     # or: pip install 'navflow[postgres]'

The Docker image already includes it.

Provide the connection string

Set the DSN in the daemon’s environment (preferred — a DSN in the source config is exported to the catalog YAML):


export PG_DSN=postgresql://user:pass@host:5432/dbname

navflowd also reads DATABASE_URL. (Alternatively, set the dsn field on the source.)

Create the source by discovery

In the console: Sources → Add source → postgres. Enter the table (e.g. orders or public.orders) and click Discover. NavFlow reads information_schema and proposes:

a cursor_column (prefers updated_at, else id) and its cursor_type,
a key_column (an *_id column such as tenant_id),
labels for the key and a status-like column.

Review the proposal and save. (You can also set these fields manually.)

Choose the cursor

The cursor determines what “new” means:

cursor_type: int over an autoincrement id — append-only: captures inserts.
cursor_type: timestamp over updated_at — captures inserts and updates (each time the row’s updated_at advances).


- name: orders
  connector: postgres
  poll: 10s
  config:
    table: orders
    cursor_column: updated_at
    cursor_type: timestamp
    key_column: tenant_id
    labels:
      - { name: tenant_id, field: tenant_id, primary: true }
      - { name: status, field: status }

Confirm ingestion

On the next poll, rows arrive as events keyed by tenant_id. The source’s Recent events shows the rows; numeric columns appear as typed fields; the full row is retained in the payload. Explore lists the tenants and reads their timelines.

Each row’s text line is a compact summary; the original row is kept losslessly in the event payload. Set a text_template on the source to control the rendered line.