TimescaleDB Sink Node

Quick Reference

TimescaleDB Connection The Postgres username/password used to connect.

JDBC URL The PostgreSQL connection URL. TimescaleDB is a Postgres extension, so this is an ordinary Postgres URL. ex: jdbc:postgresql://host:5432/metrics

Schema Name (optional) Schema qualifying the target table. ex: public

Table Name The target table. It must already exist — you own its column types. ex: metrics

Time Column The column used as the hypertable's time dimension. Coerced to TIMESTAMPTZ. ex: ts

Time Unit Unit for numeric epoch time values. Ignored for ISO-8601 string timestamps.

Create hypertable on startup Promotes the table to a hypertable if it isn't one already. Default: on.

Write Mode Insert appends rows; Upsert updates on conflict.

Batch Size Rows written per transaction.

Overview

The TimescaleDB Sink node writes records from your workflow into a TimescaleDB hypertable. TimescaleDB is a PostgreSQL extension for time-series data, so the connection is a normal Postgres connection and the target is a normal Postgres table — with the time-based partitioning, compression, and retention features TimescaleDB adds on top.

The node handles the one part that isn't standard SQL for you: the time column. Whatever form your timestamp arrives in — epoch milliseconds, epoch seconds, or an ISO-8601 string — it is converted to a UTC TIMESTAMPTZ before the row is written. It can also promote the target table to a hypertable on startup, so you don't need to run the TimescaleDB DDL yourself.

Rows are written in batches inside a single transaction. If any row in a batch fails, the whole batch rolls back.

Configuration

Field	Description	Required	Default
TimescaleDB Connection	Select or create a username/password credential for the Postgres role used to write.	No	—
JDBC URL	PostgreSQL connection URL (e.g. jdbc:postgresql://host:5432/metrics). Must be a jdbc:postgresql: URL.	Yes	—
Schema Name	Schema qualifying the target table (e.g. public). Leave blank to use the database default.	No	—
Table Name	The target table. It must already exist; the node does not create it.	Yes	—
Time Column	The record field / column used as the hypertable's time dimension. Every record must include it.	Yes	—
Time Unit	Unit for numeric time values: Seconds, Milliseconds, Microseconds, or Nanoseconds. Ignored when the value is an ISO-8601 string.	No	Milliseconds
Create hypertable on startup	Runs create_hypertable(..., if_not_exists => TRUE) when the workflow starts. Turn off if the hypertable already exists or the role lacks DDL rights.	No	On
Write Mode	Insert appends every record as a new row. Upsert updates existing rows on conflict.	No	Insert
Upsert Key Columns	Comma-separated conflict-target columns (e.g. device_id,ts). Shown and required only when Write Mode is Upsert.	Conditional	—
Batch Size	Maximum rows per batch insert / transaction.	No	1000

The Time Column

Every record must carry the field named in Time Column. A record missing it, or holding an empty value, is rejected on its own — the rest of the batch still writes.

The value is interpreted by its type:

Value	Interpretation
A number	Epoch offset in the configured Time Unit — e.g. 1753280531000 with Milliseconds
A string	An ISO-8601 timestamp such as 2026-07-23T14:02:11Z. Time Unit does not apply
Anything else	The record is rejected with a type error

If your timestamps are numeric, make sure Time Unit matches how they were produced. Reading epoch seconds as milliseconds places every row in 1970.

Create Hypertable on Startup

Left on, the node promotes the target table to a hypertable when the workflow starts. The call is idempotent, so an existing hypertable is left alone.

Turn it off when:

• The database role can write but lacks DDL privileges — the call would fail even though the hypertable already exists.
• You created the hypertable with specific settings (chunk interval, compression, retention policy) and want no unconfigured call in the startup path.

Either way, the table itself is never created for you. Create it with the column types you want before running the workflow:

CREATE TABLE device_metrics (
  ts          TIMESTAMPTZ      NOT NULL,
  device_id   TEXT             NOT NULL,
  temperature DOUBLE PRECISION,
  humidity    DOUBLE PRECISION
);

Write Modes

Insert appends each record as a new row. A primary key or unique constraint violation fails the whole batch and rolls it back.

Upsert updates the existing row when a record conflicts on the columns listed in Upsert Key Columns. Those columns must match a unique constraint or index on the table.

On a hypertable, a unique index has to include the time (partitioning) column. In practice that means the conflict target is usually an identity column plus the time column — for example device_id,ts — rather than the identity column alone.

Related Nodes

• JDBC Sink: Write to any JDBC database without hypertable handling
• InfluxDB Sink: Alternative time-series destination
• JDBC Source: Read records from a relational database