ThingsBoard Edge uses PostgreSQL as its primary database — for entities, attributes, relations, alarms, events, and the cloud event queue. For time-series data, Edge also supports Cassandra as an alternative storage backend, using the same DATABASE_TS_TYPE variable as the ThingsBoard server.
┌─────────────────────────────────────────────────────────┐
│ Rule Engine ──▶ Save Telemetry Save Attributes ◀── │
└──────────────────────┼───────────────────┼──────────────┘
┌──────────────▼──────┐ ┌────────▼─────────────────────┐
│ PostgreSQL or │ │ PostgreSQL │
│ (time-series) │ │ Entities · Attributes │
└─────────────────────┘ │ Relations · Alarms │
│ Events · Cloud Events │
└──────────────────────────────┘
Data type Storage Notes Entities — devices, assets, users, dashboards, rule chains, device profilesPostgreSQL Always PostgreSQL Attributes — server, client, and shared attributesPostgreSQL Always PostgreSQL Relations — entity-to-entity relationshipsPostgreSQL Always PostgreSQL Alarms — alarm records, acknowledgements, clear eventsPostgreSQL Always PostgreSQL Time-series — telemetry key-value pairs with timestampsPostgreSQL or Cassandra Controlled by DATABASE_TS_TYPE (sql or cassandra) Events — audit logs, rule engine debug events, lifecycle eventsPostgreSQL Always PostgreSQL Cloud Events — events queued for server synchronizationPostgreSQL (cloud_events table) or Kafka Kafka used when TB_QUEUE_TYPE=kafka (since 3.9)
Edge uses HikariCP to manage PostgreSQL connections:
Variable Default Description SPRING_DATASOURCE_URLjdbc:postgresql://localhost:5432/tb_edgeDatabase connection URL SPRING_DATASOURCE_USERNAMEpostgresDatabase username SPRING_DATASOURCE_PASSWORDpostgresDatabase password SPRING_DATASOURCE_MAXIMUM_POOL_SIZE16Maximum connections in the pool
Edge batches writes to maximize PostgreSQL throughput. Instead of inserting one row at a time, it collects data points into batches and flushes them periodically.
Variable Default Description SQL_TS_BATCH_SIZE10000Maximum data points per batch SQL_TS_BATCH_MAX_DELAY_MS100Maximum wait time (ms) before flushing an incomplete batch SQL_TS_BATCH_THREADS3Number of threads processing batches
Variable Default Description SQL_TS_LATEST_BATCH_SIZE1000Maximum entries per batch SQL_TS_LATEST_BATCH_MAX_DELAY_MS50Maximum flush delay (ms) SQL_TS_LATEST_BATCH_THREADS3Batch processing threads
Variable Default Description SQL_ATTRIBUTES_BATCH_SIZE1000Maximum attributes per batch SQL_ATTRIBUTES_BATCH_MAX_DELAY_MS50Maximum flush delay (ms) SQL_ATTRIBUTES_BATCH_THREADS3Batch processing threads
If telemetry is arriving faster than it is being written, increase SQL_TS_BATCH_THREADS and SQL_TS_BATCH_SIZE. Monitor batch stats (logged every SQL_TS_BATCH_STATS_PRINT_MS, default 10 seconds) to identify bottlenecks.
PostgreSQL time-series tables are partitioned by time to keep queries fast and enable efficient data expiration. Set the partition granularity with SQL_POSTGRES_TS_KV_PARTITIONING:
Value Partition size Best for DAYS1 day High write volume — more partitions, faster drops MONTHS1 month (default) Most deployments YEARS1 year Very low write volume INDEFINITENo partitioning Not recommended for production
Event tables (audit logs, rule engine debug events) also use time-based partitioning:
Variable Default Description SQL_EVENTS_REGULAR_PARTITION_SIZE_HOURS168 (7 days)Regular events partition size SQL_EVENTS_DEBUG_PARTITION_SIZE_HOURS1Debug events partition size
ThingsBoard Edge automatically deletes old records based on a configured Time-to-Live (TTL). By default, TTL is disabled — records are kept forever.
Variable Default Description SQL_TTL_TS_ENABLEDtrueEnable automatic TTL cleanup SQL_TTL_TS_EXECUTION_INTERVAL86400000 (1 day)How often the cleanup job runs, in milliseconds SQL_TTL_TS_TS_KEY_VALUE_TTL0 (disabled)Retention period in seconds; 0 means records never expire
Variable Default Description SQL_TTL_EVENTS_EVENTS_TTL0 (disabled)Events TTL in seconds SQL_TTL_EVENTS_DEBUG_EVENTS_TTL604800 (7 days)Debug events TTL in seconds SQL_TTL_AUDIT_LOGS_SECS0 (disabled)Audit log TTL in seconds
Variable Default Description SQL_TTL_CLOUD_EVENTS_ENABLEDtrueEnable automatic TTL cleanup for cloud events SQL_TTL_CLOUD_EVENTS_EXECUTION_INTERVAL86400000 (1 day)How often the cloud events cleanup job runs, in milliseconds SQL_TTL_CLOUD_EVENTS_CLOUD_EVENTS_TTL2628000 (~30 days)Retention period for cloud events in seconds SQL_TTL_EDGE_EVENTS_ENABLEDtrueEnable automatic TTL cleanup for edge events SQL_TTL_EDGE_EVENTS_EXECUTION_INTERVAL86400000 (1 day)How often the edge events cleanup job runs, in milliseconds SQL_TTL_EDGE_EVENTS_EDGE_EVENTS_TTL2628000 (~30 days)Retention period for edge events in seconds
