A lightweight time series database with MetricsQL query support, using SQLite as the storage backend.
MetricSQLite provides a VictoriaMetrics-compatible (And also Prometheus) query interface without requiring a separate database service. It's ideal for embedded applications, prototyping, or situations where you want time series capabilities without infrastructure overhead.
- SQLite storage - No external database required, works with a single file or in-memory
- MetricsQL queries - Compatible subset of VictoriaMetrics query language
- Gauge and counter metrics - Built-in support for both metric types
- InfluxDB line protocol - Ingest data using the widely-supported line protocol format
- Counter compression - Consecutive samples with the same value are stored efficiently
- Gauge compaction - Downsample old data to save space
- FastAPI integration - Optional HTTP API compatible with Grafana
pip install metricsqlite
For FastAPI support:
pip install metricsqlite[fastapi]from metricsqlite import MetricsQLiteClient
from datetime import datetime, timezone
client = MetricsQLiteClient(db_path="metrics.db")
client.connect()
client.create_tables()
# Timestamp can be UTC milliseconds, datetime objects and even ISO8601 strings.
client.insert_counter("requests", 100, timestamp=1_767_222_000_000, labels={"endpoint": "/api"})
ts = datetime(2026, 1, 1, 0, 0, 0, tzinfo=timezone.utc)
client.insert_gauge("temperature", 19.0, timestamp=ts, labels={"room": "bedroom"})
client.insert_gauge("temperature", 22.5, timestamp="2026-01-01T00:00:00Z", labels={"room": "kitchen"})
# Instant query
result = client.query('temperature{room="kitchen"}')
for labels, sample in result.series:
print(f"{labels}: {sample.value}")
# Range query
result = client.query_range("avg_over_time(temperature[1h])", start="2026-01-01T00:00:00Z", end="2026-01-01T01:00:00Z")
client.close()Currently, most of the MetricsQL syntax is supported. However, only a limited set of functions is supported. Supporting more functions is planned for the future.
See docs/queries.md for the full query language reference.
Expose a VictoriaMetrics-compatible HTTP API:
from fastapi import FastAPI
from metricsqlite import MetricsQLiteClient
from metricsqlite.fastapi import create_router
app = FastAPI()
client = MetricsQLiteClient("metrics.db")
client.connect()
client.create_tables()
# Read-only endpoints
app.include_router(create_router(client), prefix="/api/v1")
# Or with write endpoints enabled
app.include_router(create_router(client, enable_writes=True), prefix="/api/v1")This adds /api/v1/query, /api/v1/query_range, /api/v1/labels, /api/v1/label/{name}/values, and /api/v1/series endpoints compatible with Grafana and other tools. With enable_writes=True, a /api/v1/influx/write endpoint is also available for InfluxDB line protocol ingestion.
See docs/api.md for endpoint documentation.
Reduce storage by averaging old samples into time buckets:
from datetime import datetime, timedelta
# Compact data older than 7 days into 1-hour buckets
one_week_ago = datetime.now() - timedelta(weeks=1)
samples_compacted, buckets_created = client.compact_gauges(
older_than=one_week_ago,
interval="1h"
)See docs/sqlite.md for details on storage internals, disk usage, and compaction strategies.
- Query Language - MetricsQL syntax and supported functions
- HTTP API - FastAPI endpoint reference
- SQLite Storage - Database structure and optimization
MIT