VoltroDocumentation

Voltro + Timescale

Run Voltro on Timescale (TimescaleDB) — it's Postgres plus the time-series extension, so the full reactive surface works; hypertables are an opt-in per table.

Timescale (Timescale Cloud / TimescaleDB) is Postgres with the TimescaleDB extension — so it uses Voltro's postgres dialect with the complete reactive surface: LISTEN/NOTIFY CDC, advisory-lock cluster workflows, read replicas, JSONB. Nothing in the framework changes; you simply also have hypertables and continuous aggregates available when you want them.

Connect

DB_DIALECT=postgres
DB_URL=postgresql://tsdbadmin:[PASSWORD]@[SERVICE].[PROJECT].tsdb.cloud.timescale.com:[PORT]/tsdb?sslmode=require

sslmode=require is mandatory on Timescale Cloud.

Hypertables are opt-in

Voltro's schema DSL emits ordinary Postgres tables. To turn one into a TimescaleDB hypertable (chunked by time for fast time-series queries), run create_hypertable(...) yourself after the table exists — via a custom migration or a *.seed.ts that issues the SQL. The framework's voltro migrate doesn't generate hypertable DDL; it's a deliberate, per-table decision.

A table you convert to a hypertable still works with the reactive engine and ctx.store exactly as before — the conversion is transparent to Voltro's read/write path. Heavy time-series ingestion tables are usually NOT the ones you mark .reactive() (you don't want a subscription firing on every metric insert), so the two concerns rarely collide.

Enabling CDC

Timescale is real Postgres, so Voltro's change-data-capture is LISTEN/NOTIFY and on by default (CDC=1) — no extension, no flag, and TimescaleDB's presence changes nothing here. Timescale Cloud puts no transaction pooler in front by default, so the DB_URL you connect with is session-mode and reactivity works immediately. (If you mark a hypertable .reactive(), every chunk insert fires a notification — usually you don't want that on high-ingest time-series tables; see the hypertable note above.)

Pooling / SSL

  • No transaction pooler by default — reactivity works directly.
  • SSL: sslmode=require always.

Verify

[voltro:dev] sql dialect resolved: postgres — CDC: LISTEN/NOTIFY, RETURNING: native
[voltro:dev] read replicas: 0 configured (DB_REPLICA_URLS empty) — all queries → primary
[voltro:dev] workflow engine: cluster-sql, dialect=postgres

Confirm with voltro logs --tail 50.

See also