Overview

ProxySQL 3.1.6 introduced an embedded time-series database (TSDB) that captures and stores time-series metrics natively, without requiring any external monitoring infrastructure. All metric data is collected directly from ProxySQL’s internal Prometheus registry and persisted to a local SQLite database file, making it immediately available for historical analysis and capacity planning.

The TSDB is fully self-contained: it has no external dependencies, requires no separate processes, and stores everything in proxysql_stats.db alongside ProxySQL’s other persistent state. Metrics are queryable via standard SQL through the Admin interface, making it easy to integrate with existing SQL-based tooling or run ad-hoc queries during incident investigation.

Collected samples are automatically rolled up into hourly aggregates (with AVG, MAX, MIN, and COUNT) and retained for up to 365 days, while raw per-sample data follows a configurable retention window (default 7 days). An optional backend TCP health-probe subsystem records the reachability and connect latency of every backend server. A built-in web dashboard is available at http://<host>:6080/tsdb for interactive browsing and visualization.

Getting Started

Enable the TSDB by connecting to the Admin interface and running:

SET tsdb-enabled=1;
LOAD TSDB VARIABLES TO RUNTIME;
SAVE TSDB VARIABLES TO DISK;

Once enabled, ProxySQL immediately begins sampling metrics at the configured interval. No restart is required.

Configuration Variables

Variable Reference

Admin Commands

-- View all current TSDB variable values
SHOW TSDB VARIABLES;

-- View runtime status counters
SHOW TSDB STATUS;

-- Apply in-memory changes to the running instance
LOAD TSDB VARIABLES TO RUNTIME;

-- Persist in-memory changes to disk (survives restarts)
SAVE TSDB VARIABLES TO DISK;

Tables

All TSDB tables are accessible through the Admin interface (port 6032 by default). Raw tables (tsdb_metrics, tsdb_metrics_hour, tsdb_backend_health) live in the Stats schema. The status table (stats_tsdb) is in the Stats schema as well.

tsdb_metrics

Description: Stores raw metric samples collected every tsdb-sample_interval seconds. Each row represents a single observation of one metric series (a unique combination of metric name and label set). The table contains all metric families exported by ProxySQL’s Prometheus registry, including counters, gauges, histograms, and summaries. Raw data is retained for tsdb-retention_days days.

Fields:

Schema:

CREATE TABLE tsdb_metrics (
  timestamp    INT  NOT NULL,
  metric_name  TEXT NOT NULL,
  labels       TEXT NOT NULL DEFAULT '{}',
  value        REAL,
  PRIMARY KEY (timestamp, metric_name, labels)
) WITHOUT ROWID

Example:

SELECT * FROM tsdb_metrics
WHERE metric_name = 'proxysql_client_connections_connected'
ORDER BY timestamp DESC
LIMIT 5;

+------------+---------------------------------------+--------+-------+
| timestamp  | metric_name                           | labels | value |
+------------+---------------------------------------+--------+-------+
| 1743000060 | proxysql_client_connections_connected | {}     | 42    |
| 1743000055 | proxysql_client_connections_connected | {}     | 41    |
| 1743000050 | proxysql_client_connections_connected | {}     | 43    |
+------------+---------------------------------------+--------+-------+

tsdb_metrics_hour

Description: Stores hourly rollups of all metric series computed from tsdb_metrics. Each row holds the statistical summary (AVG, MAX, MIN, COUNT) for one metric series within a one-hour bucket. Hourly aggregates are retained independently from raw data for up to 365 days, providing long-term trend visibility even after raw samples have been purged.

Fields:

Schema:

CREATE TABLE tsdb_metrics_hour (
  bucket       INT  NOT NULL,
  metric_name  TEXT NOT NULL,
  labels       TEXT NOT NULL DEFAULT '{}',
  avg_value    REAL,
  max_value    REAL,
  min_value    REAL,
  count        INT,
  PRIMARY KEY (bucket, metric_name, labels)
) WITHOUT ROWID

Example:

SELECT bucket, avg_value, max_value, min_value, count
FROM tsdb_metrics_hour
WHERE metric_name = 'proxysql_client_connections_connected'
ORDER BY bucket DESC
LIMIT 5;

+------------+-----------+-----------+-----------+-------+
| bucket     | avg_value | max_value | min_value | count |
+------------+-----------+-----------+-----------+-------+
| 1743000000 | 38.4      | 55        | 12        | 720   |
| 1742996400 | 31.2      | 48        | 8         | 720   |
| 1742992800 | 22.7      | 35        | 5         | 720   |
+------------+-----------+-----------+-----------+-------+

tsdb_backend_health

Description: Records the result of periodic TCP health probes against each backend server. Each row captures whether the server was reachable and how long the TCP connection took to establish. This table is only populated when tsdb-monitor_enabled=1. Raw probe data is retained for tsdb-retention_days days.

Fields:

Schema:

CREATE TABLE tsdb_backend_health (
  timestamp  INT  NOT NULL,
  hostgroup  INT  NOT NULL,
  hostname   TEXT NOT NULL,
  port       INT  NOT NULL,
  probe_up   INT  NOT NULL,
  connect_ms INT,
  PRIMARY KEY (timestamp, hostgroup, hostname, port)
) WITHOUT ROWID

Example:

SELECT timestamp, hostgroup, hostname, port, probe_up, connect_ms
FROM tsdb_backend_health
ORDER BY timestamp DESC
LIMIT 5;

+------------+-----------+---------------+------+----------+------------+
| timestamp  | hostgroup | hostname      | port | probe_up | connect_ms |
+------------+-----------+---------------+------+----------+------------+
| 1743000060 |         0 | 192.168.1.10  | 3306 |        1 |          2 |
| 1743000060 |         0 | 192.168.1.11  | 3306 |        1 |          3 |
| 1743000050 |         0 | 192.168.1.10  | 3306 |        0 |       NULL |
+------------+-----------+---------------+------+----------+------------+

stats_tsdb

Description: Provides a snapshot of the current TSDB runtime status. Each row is a named counter or gauge describing the overall state of the database. Query this table to quickly check data volume, disk usage, and the time range of available data.

Fields:

Status Variables:

Schema:

CREATE TABLE stats_tsdb (
  Variable_Name  VARCHAR NOT NULL PRIMARY KEY,
  Variable_Value VARCHAR NOT NULL
)

Example:

SELECT * FROM stats_tsdb;

+----------------------+----------------+
| Variable_Name        | Variable_Value |
+----------------------+----------------+
| Total_Series         | 1284           |
| Total_Datapoints     | 18432000       |
| Disk_Size_Bytes      | 31457280       |
| Oldest_Datapoint_TS  | 1742395200     |
| Newest_Datapoint_TS  | 1743000055     |
+----------------------+----------------+

SQL Query Examples

Check Current TSDB Status

SELECT * FROM stats_tsdb;

View Recent Metric Samples

Retrieve the last 10 samples for a specific metric:

SELECT *
FROM tsdb_metrics
WHERE metric_name = 'proxysql_client_connections_connected'
ORDER BY timestamp DESC
LIMIT 10;

Hourly Trend Analysis

View the last 24 hours of hourly aggregates for a metric:

SELECT bucket, avg_value, max_value
FROM tsdb_metrics_hour
WHERE metric_name = 'proxysql_client_connections_connected'
ORDER BY bucket DESC
LIMIT 24;

Backend Health Check

Find backends that failed TCP probes recently:

SELECT *
FROM tsdb_backend_health
WHERE probe_up = 0
ORDER BY timestamp DESC
LIMIT 10;

REST API

The TSDB exposes a REST API through ProxySQL’s built-in HTTP server (default port 6080). All endpoints return JSON.

GET /api/tsdb/metrics

Returns a list of all metric names currently stored in the TSDB.

Example response:

{
  "metrics": [
    "proxysql_client_connections_connected",
    "proxysql_client_connections_created",
    "proxysql_questions"
  ]
}

GET /api/tsdb/query

Queries time-series data for a specific metric within a time range.

Query parameters:

Example request:

GET /api/tsdb/query?metric=proxysql_client_connections_connected&from=1743000000&to=1743003600

Example response:

{
  "metric": "proxysql_client_connections_connected",
  "datapoints": [
    { "timestamp": 1743000000, "value": 38, "labels": {} },
    { "timestamp": 1743000005, "value": 41, "labels": {} }
  ]
}

GET /api/tsdb/status

Returns the current TSDB system status, equivalent to querying stats_tsdb.

Example response:

{
  "total_series": 1284,
  "total_datapoints": 18432000,
  "disk_size_bytes": 31457280,
  "oldest_timestamp": 1742395200,
  "newest_timestamp": 1743000055
}

Web Dashboard

An interactive web dashboard is available at http://<host>:6080/tsdb. The dashboard provides:

• A metric selector to browse all available time series.
• A time range picker for selecting the window of interest.
• Chart.js-powered line graphs for visualizing metric trends over time.

No authentication is required by default. Access to the dashboard is controlled by network-level access to the HTTP port (default 6080).

Storage Considerations

All TSDB data is stored in proxysql_stats.db in ProxySQL’s data directory. At the default sampling interval of 5 seconds, raw data growth is approximately 10–50 MB per day, depending on the number of active metric series. Hourly rollup data grows at under 1 MB per day.

The following factors influence storage consumption:

• tsdb-sample_interval: Lower values produce more samples. At 1-second intervals, expect up to 5× more raw data than the default.
• tsdb-retention_days: Increasing retention linearly increases raw data storage. Hourly aggregates are always retained for 365 days regardless of this setting.
• tsdb-monitor_enabled: Enabling backend health probes adds one row per backend per tsdb-monitor_interval seconds, which is generally a small fraction of total storage.

To reduce disk usage, increase tsdb-sample_interval, reduce tsdb-retention_days, or disable tsdb-monitor_enabled if backend probes are not needed.