Self-host timescale
2.32.0Time-series database and real-time analytics on Postgres
docker run -d --name timescaledb -p 5432:5432 -v </a/local/data/folder>:/pgdata -e PGDATA=/pgdata -e POSTGRES_PASSWORD=password timescale/timescaledb-ha:pg18- Stars
- 23 862
- RAM
- 8GB RAM recommended (README quick start, for Docker)
- Port
- 5432 (PostgreSQL wire protocol served by the container; the README quick start maps it to host port 6543 to avoid clashing with a local Postgres)
- Requires
- PostgreSQL
timescale/timescaledb-haWhat is timescale?
TimescaleDB is a PostgreSQL extension that adds time-series and event-data handling to an ordinary Postgres server, for developers who want SQL analytics over sensor, market or application telemetry without running a second database engine. Tables created as hypertables are split automatically into time- and key-based chunks, so a query only scans the ranges and columns it needs; row storage takes the writes while a columnar store serves analytics, with compression typically above 90%. Continuous aggregates refresh incrementally in the background on a schedule policy, and the hyperfunction library offers 200+ SQL functions including time_bucket for interval aggregation. The vendor also documents tiered storage, ingestion from Kafka and S3, replication to Iceberg tables, and hybrid keyword-plus-vector search as part of the same platform. Operators get a companion tuning tool (timescaledb-tune) that sizes memory, WAL and parallelism from the host's resources, and the HA container additionally ships TimescaleDB Toolkit, PostGIS and Patroni support. Installation is documented for Debian, Ubuntu, Red Hat, Fedora, Rocky and Arch Linux, macOS via Homebrew or MacPorts, a Windows installer, Docker (the HA image or the lighter Alpine one), Kubernetes StatefulSets, or a CMake build from source, always on top of a supported PostgreSQL server. The community edition is dual-licensed: Apache-2.0 code outside the tsl directory and Timescale-Licensed code inside it, while wider capabilities are sold as TimescaleDB Enterprise and as the managed Tiger Cloud.
timescale alternatives
tdengineSelf-hosted open-source time-series database for IoT and industrial data, offering clustering, stream processing, subscriptions, TDgpt AI and Grafana or Kafka links.Comparetdengine with timescale
gtsdbGTSDB is a self-hosted, open-source time-series database in Go using WAL-first architecture for sub-millisecond reads and 233x faster writes than InfluxDB.Comparegtsdb with timescale
questdbSelf-hosted, open-source time-series database with SAMPLE BY and ASOF join SQL, QuestDB Wire Protocol ingestion, PGWire support and a web console.Comparequestdb with timescale
Apache IoTDBApache IoTDB is a self-hosted, open-source time-series database for industrial IoT with high-throughput reads/writes, ultra-high compression, and SQL-like queries.CompareApache IoTDB with timescale
greptimedbSelf-hosted and open-source: one Rust columnar telemetry store keeps metrics, logs and traces in a single engine with SQL or PromQL queries over object storage.Comparegreptimedb with timescale
tidbSelf-hosted, open-source distributed SQL database with MySQL compatibility, ACID transactions, HTAP analytics and vector search in one engine.Comparetidb with timescale
timeplusSelf-hosted, open-source streaming SQL engine for real-time analytics and AI — a lightweight alternative to ksqlDB and Flink powered by ClickHouse.Comparetimeplus with timescale
cratedbA self-hosted, open-source distributed SQL database with PostgreSQL wire protocol support, for real-time analytics over time-series, full-text and vector data.Comparecratedb with timescale
Should you self-host timescale?
timescale scores 79/100 on selfhost.directory (how scoring works) and ranks #1 of 5 in Time Series. It has 23 862 GitHub stars, +185 in the last 30 days.
It shipped 20 stable releases in the past year. The latest, 2.32.0, came out on 11 November 2026. New versions land roughly every 2 weeks.
Setup is moderate: expect some configuration beyond a single command. An official Docker image is available. It is Apache-2.0-licensed and written mostly in C.
Its closest alternative on selfhost.directory is influxdb (79/100, 31 814 stars). timescale scores higher overall. See timescale vs influxdb side by side.
Features
- Automatic configuration tuning
- Automatic time partitioning (hypertables)
- Columnar storage with compression
- Continuous aggregates
- Hybrid keyword and vector search
- Replication and high availabilityAchieved with PostgreSQL/HA tooling; docs recommend it for production.
- Scheduled background jobs (policies)
- Skip-scan query optimization
- Tiered Storage
timescale README
Get started with TimescaleDB in under 10 minutes. This guide will help you run TimescaleDB locally, create your first hypertable with columnstore enabled, write data to the columnstore, and see instant analytical query performance.
- How to run TimescaleDB with a one-line install or Docker command
- How to create a hypertable with columnstore enabled
- How to insert data directly to the columnstore
- How to execute analytical queries
- Docker installed on your machine
- 8GB RAM recommended
psqlclient (included with PostgreSQL) or any PostgreSQL client like pgAdmin
You have two options to start TimescaleDB:
The easiest way to get started:
Important: This script is intended for local development and testing only. Do not use it for production deployments. For production-ready installation options, see the TimescaleDB installation guide.
Linux/Mac:
curl -sL https://tsdb.co/start-local | shThis command:
- Downloads and starts TimescaleDB (if not already downloaded)
- Exposes PostgreSQL on port 6543 (a non-standard port to avoid conflicts with other PostgreSQL instances on port 5432)
- Automatically tunes settings for your environment using timescaledb-tune
- Sets up a persistent data volume
Alternatively, you can run TimescaleDB directly with Docker:
docker run -d --name timescaledb \
-p 6543:5432 \
-e POSTGRES_PASSWORD=password \
timescale/timescaledb-ha:pg18Note: We use port 6543 (mapped to container port 5432) to avoid conflicts if you have other PostgreSQL instances running on the standard port 5432.
Wait about 1-2 minutes for TimescaleDB to download & initialize.
Connect using psql:
psql -h localhost -p 6543 -U postgres
# When prompted, enter password: passwordYou should see the PostgreSQL prompt. Verify TimescaleDB is installed:
SELECT extname, extversion FROM pg_extension WHERE extname = 'timescaledb';
Expected output:
extname | extversion
-------------+------------
timescaledb | 2.x.x
Prefer a GUI? If you'd rather use a graphical tool instead of the command line, you can download pgAdmin and connect to TimescaleDB using the same connection details (host: localhost, port: 6543, user: postgres, password: password).
Let's create a hypertable for IoT sensor data with columnstore enabled:
-- Create a hypertable with automatic columnstore CREATE TABLE sensor_data ( time TIMESTAMPTZ NOT NULL, sensor_id TEXT NOT NULL, temperature DOUBLE PRECISION, humidity DOUBLE PRECISION, pressure DOUBLE PRECISION ) WITH ( tsdb.hypertable );
tsdb.hypertable - Converts this into a TimescaleDB hypertable
See more:
Let's add some sample sensor readings:
-- Enable timing to see time to execute queries \timing on -- Insert sample data for multiple sensors -- SET timescaledb.enable_direct_compress_insert = on to insert data directly to the columnstore (columnar format for performance) SET timescaledb.enable_direct_compress_insert = on; INSERT INTO sensor_data (time, sensor_id, temperature, humidity, pressure) SELECT time, 'sensor_' || ((random() * 9)::int + 1), 20 + (random() * 15), 40 + (random() * 30), 1000 + (random() * 50) FROM generate_series( NOW() - INTERVAL '90 days', NOW(), INTERVAL '1 seconds' ) AS time; -- Once data is inserted into the columnstore we optimize the order and structure -- this compacts and orders the data in the chunks for optimal query performance and compression DO $$ DECLARE ch TEXT; BEGIN FOR ch IN SELECT show_chunks('sensor_data') LOOP CALL convert_to_columnstore(ch, recompress := true); END LOOP; END $$;
This generates ~7,776,001 readings across 10 sensors over the past 90 days.
Verify the data was inserted:
SELECT COUNT(*) FROM sensor_data;
Now let's run some analytical queries that showcase TimescaleDB's performance:
-- Enable query timing to see performance \timing on -- Query 1: Average readings per sensor over the last 7 days SELECT sensor_id, COUNT(*) as readings, ROUND(AVG(temperature)::numeric, 2) as avg_temp, ROUND(AVG(humidity)::numeric, 2) as avg_humidity, ROUND(AVG(pressure)::numeric, 2) as avg_pressure FROM sensor_data WHERE time > NOW() - INTERVAL '7 days' GROUP BY sensor_id ORDER BY sensor_id; -- Query 2: Hourly averages using time_bucket -- Time buckets enable you to aggregate data in hypertables by time interval and calculate summary values. SELECT time_bucket('1 hour', time) AS hour, sensor_id, ROUND(AVG(temperature)::numeric, 2) as avg_temp, ROUND(AVG(humidity)::numeric, 2) as avg_humidity FROM sensor_data WHERE time > NOW() - INTERVAL '24 hours' GROUP BY hour, sensor_id ORDER BY hour DESC, sensor_id LIMIT 20; -- Query 3: Daily statistics across all sensors SELECT time_bucket('1 day', time) AS day, COUNT(*) as total_readings, ROUND(AVG(temperature)::numeric, 2) as avg_temp, ROUND(MIN(temperature)::numeric, 2) as min_temp, ROUND(MAX(temperature)::numeric, 2) as max_temp FROM sensor_data GROUP BY day ORDER BY day DESC LIMIT 10; -- Query 4: Latest reading for each sensor -- Highlights the value of Skipscan executing in under 100ms without skipscan it takes over 5sec SELECT DISTINCT ON (sensor_id) sensor_id, time, ROUND(temperature::numeric, 2) as temperature, ROUND(humidity::numeric, 2) as humidity, ROUND(pressure::numeric, 2) as pressure FROM sensor_data ORDER BY sensor_id, time DESC;
Notice how fast these analytical queries run, even with aggregations across millions of rows. This is the power of TimescaleDB's columnstore.
TimescaleDB automatically:
- Partitions your data into time-based chunks for efficient querying
- Write directly to columnstore using columnar storage (90%+ compression typical) and faster vectorized queries
- Optimizes queries by only scanning relevant time ranges and columns
- Enables time_bucket() - a powerful function for time-series aggregation
See more:
Now that you've got the basics, explore more:
Continuous aggregates make real-time analytics run faster on very large datasets. They continuously and incrementally refresh a query in the background, so that when you run such query, only the data that has changed needs to be computed, not the entire dataset. This is what makes them different from regular PostgreSQL materialized views, which cannot be incrementally materialized and have to be rebuilt from scratch every time you want to refresh them.
Let's create a continuous aggregate for hourly sensor statistics:
CREATE MATERIALIZED VIEW sensor_data_hourly WITH (timescaledb.continuous) AS SELECT time_bucket('1 hour', time) AS hour, sensor_id, AVG(temperature) AS avg_temp, AVG(humidity) AS avg_humidity, AVG(pressure) AS avg_pressure, MIN(temperature) AS min_temp, MAX(temperature) AS max_temp, COUNT(*) AS reading_count FROM sensor_data GROUP BY hour, sensor_id;
This creates a materialized view that pre-aggregates your sensor data into hourly buckets. The view is automatically populated with existing data.
To keep the continuous aggregate up-to-date as new data arrives, add a refresh policy:
SELECT add_continuous_aggregate_policy( 'sensor_data_hourly', start_offset => INTERVAL '3 hours', end_offset => INTERVAL '1 hour', schedule_interval => INTERVAL '1 hour' );
This policy:
- Refreshes the continuous aggregate every hour
- Processes data from 3 hours ago up to 1 hour ago (leaving the most recent hour for real-time queries)
- Only processes new or changed data incrementally
Now you can query the pre-aggregated data for much faster results:
-- Get hourly averages for the last 24 hours SELECT hour, sensor_id, ROUND(avg_temp::numeric, 2) AS avg_temp, ROUND(avg_humidity::numeric, 2) AS avg_humidity, reading_count FROM sensor_data_hourly WHERE hour > NOW() - INTERVAL '24 hours' ORDER BY hour DESC, sensor_id LIMIT 50;
- Faster queries: Pre-aggregated data means queries run in milliseconds instead of seconds
- Incremental refresh: Only new/changed data is processed, not the entire dataset
- Automatic updates: The refresh policy keeps your aggregates current without manual intervention
- Real-time option: You can enable real-time aggregation to combine materialized and raw data
Compare the performance difference:
-- Query the raw hypertable (slower on large datasets) \timing on SELECT time_bucket('1 hour', time) AS hour, AVG(temperature) AS avg_temp FROM sensor_data WHERE time > NOW() - INTERVAL '60 days' GROUP BY hour ORDER BY hour DESC LIMIT 24; -- Query the continuous aggregate (much faster) SELECT hour, avg_temp FROM sensor_data_hourly WHERE hour > NOW() - INTERVAL '60 days' ORDER BY hour DESC LIMIT 24;
Notice how the continuous aggregate query is significantly faster, especially as your dataset grows!
See more:
- About continuous aggregates
- API reference
- TimescaleDB Documentation
- Time-series Best Practices
- Continuous Aggregates
Learn TimescaleDB with complete, standalone examples using real-world datasets. Each example includes sample data and analytical queries.
- NYC Taxi Data - Transportation and location-based analytics
- Financial Market Data - Trading and market data analysis
- Application Events - Event logging with UUIDv7
Or try some of our workshops
- AI Workshop: EV Charging Station Analysis - Integrate PostgreSQL with AI capabilities for managing and analyzing EV charging station data
- Time-Series Workshop: Financial Data Analysis - Work with cryptocurrency tick data, create candlestick charts
Tiger Cloud is the modern PostgreSQL data platform for all your applications. It enhances PostgreSQL to handle time series, events, real-time analytics, and vector search—all in a single database alongside transactional workloads. You get one system that handles live data ingestion, late and out-of-order updates, and low latency queries, with the performance, reliability, and scalability your app needs. Ideal for IoT, crypto, finance, SaaS, and a myriad other domains, Tiger Cloud allows you to build data-heavy, mission-critical apps while retaining the familiarity and reliability of PostgreSQL. See our whitepaper for a deep dive into Tiger Cloud's architecture and how it meets the needs of even the most demanding applications.
A Tiger Cloud service is a single optimized 100% PostgreSQL database instance that you use as is, or extend with capabilities specific to your business needs. The available capabilities are:
- Time-series and analytics: PostgreSQL with TimescaleDB. The PostgreSQL you know and love, supercharged with functionality for storing and querying time-series data at scale for real-time analytics and other use cases. Get faster time-based queries with hypertables, continuous aggregates, and columnar storage. Save on storage with native compression, data retention policies, and bottomless data tiering to Amazon S3.
- AI and vector: PostgreSQL with vector extensions. Use PostgreSQL as a vector database with purpose built extensions for building AI applications from start to scale. Get fast and accurate similarity search with the pgvector and pgvectorscale extensions. Create vector embeddings and perform LLM reasoning on your data with the pgai extension.
- PostgreSQL: the trusted industry-standard RDBMS. Ideal for applications requiring strong data consistency, complex relationships, and advanced querying capabilities. Get ACID compliance, extensive SQL support, JSON handling, and extensibility through custom functions, data types, and extensions. All services include all the cloud tooling you'd expect for production use: automatic backups, high availability, read replicas, data forking, connection pooling, tiered storage, usage-based storage, and much more.
| Linux/macOS | Linux i386 | Windows | Coverity | Code Coverage | OpenSSF |
|---|---|---|---|---|---|
We welcome contributions to TimescaleDB! See Contributing and Code style guide for details.
Tiger Data is the fastest PostgreSQL for transactional, analytical and agentic workloads. To learn more about the company and its products, visit tigerdata.com.
# Check if container is running docker ps -a # View container logs (use the appropriate container name) # For one-line install: docker logs timescaledb-ha-pg18-quickstart # For manual Docker command: docker logs timescaledb # Stop and remove existing container # For one-line install: docker stop timescaledb-ha-pg18-quickstart && docker rm timescaledb-ha-pg18-quickstart # For manual Docker command: docker stop timescaledb && docker rm timescaledb # Start fresh # Option 1: Use the one-line install curl -sL https://tsdb.co/start-local | sh # Option 2: Use manual Docker command docker run -d --name timescaledb -p 6543:5432 -e POSTGRES_PASSWORD=password timescale/timescaledb-ha:pg18
- Verify Docker container is running:
docker ps - Check port 6543 isn't already in use:
lsof -i :6543 - Try using explicit host:
psql -h 127.0.0.1 -p 6543 -U postgres
The timescale/timescaledb-ha:pg18 image has TimescaleDB pre-installed and pre-loaded. If you see errors, ensure you're using the correct image.
When you're done experimenting:
# Stop the container docker stop timescaledb-ha-pg18-quickstart # Remove the container docker rm timescaledb-ha-pg18-quickstart # Remove the persistent data volume docker volume rm timescaledb_data # (Optional) Remove the Docker image docker rmi timescale/timescaledb-ha:pg18
# Stop the container docker stop timescaledb # Remove the container docker rm timescaledb # (Optional) Remove the Docker image docker rmi timescale/timescaledb-ha:pg18
Note: If you created a named volume with the manual Docker command, you can remove it with docker volume rm <volume_name>.
More in Time Series
victoriametricsOpen-source, self-hosted time series database and monitoring backend that replaces Prometheus or Graphite as Grafana's metrics store, with PromQL and MetricsQL querying.
ArcadeDBOpen-source, self-hosted multi-model database: one ACID engine for graph, document, key-value, vector, full-text and time-series data, queried in SQL, Cypher or Gremlin.
cratedbA self-hosted, open-source distributed SQL database with PostgreSQL wire protocol support, for real-time analytics over time-series, full-text and vector data.
EmoncmsOpen-source app that ingests, logs and charts energy, temperature and environmental readings; self-hosted free via Docker or EmonScripts, from OpenEnergyMonitor.
GrafanaMimirOpen-source, self-hosted long-term TSDB for Prometheus: multi-tenant, replicated metrics storage that scales past a billion active series.
greptimedbSelf-hosted and open-source: one Rust columnar telemetry store keeps metrics, logs and traces in a single engine with SQL or PromQL queries over object storage.
influxdbOpen-source, single-node time series database you self-host for real-time metrics and events, querying Parquet-backed data with SQL or InfluxQL.
questdbSelf-hosted, open-source time-series database with SAMPLE BY and ASOF join SQL, QuestDB Wire Protocol ingestion, PGWire support and a web console.
Super ProductivityFree, open-source, local-first to-do app with timeboxing, time tracking, planner and Kanban boards; self-host the web app via Docker or SuperSync.
tdengineSelf-hosted open-source time-series database for IoT and industrial data, offering clustering, stream processing, subscriptions, TDgpt AI and Grafana or Kafka links.
TelegrafOpen-source, self-hosted telemetry agent that collects, processes and writes metrics and logs via 300+ plugins, shipped as a single static binary configured in TOML.
0 comments