tsdb-tool
PostgreSQL and TimescaleDB query and administration CLI tool.
Provides multiple output formats (table, JSON, CSV), flexible connection management (CLI flags, DSN, PG* env vars, config profiles), and admin commands for database inspection and maintenance.
Installation
git clone <repository-url>
cd tsdb-tool
uv sync
Run commands with uv run tsdb-tool or install globally:
uv tool install .
Quick Start
# Check connectivity
tsdb-tool service check
# Run a query
tsdb-tool query -e "SELECT now()"
# List databases
tsdb-tool databases
# List tables in a schema
tsdb-tool -s myschema table
# Show table columns and preview data
tsdb-tool table myschema.sensor_data --head 5
Commands
Query Execution
# Inline query
tsdb-tool query -e "SELECT * FROM users LIMIT 10"
# From file
tsdb-tool query queries/report.sql
# From stdin
echo "SELECT 1" | tsdb-tool query
# With timeout
tsdb-tool query -e "SELECT pg_sleep(5)" -t 3
Database Overview
# List all databases (sorted by size)
tsdb-tool databases
# List schemas with space usage
tsdb-tool schema
# Schemas across all databases
tsdb-tool schema --all-databases
Table Inspection
# List all tables with sizes
tsdb-tool table
# Filter by schema
tsdb-tool -s myschema table
# Show column definitions
tsdb-tool table myschema.sensor_data
# Preview data
tsdb-tool table myschema.sensor_data --head 10
tsdb-tool table myschema.sensor_data --tail 5
tsdb-tool table myschema.sensor_data --sample 3
# Show timestamp range for hypertables
tsdb-tool table myschema.sensor_data --range
Connections
# Active connections (non-idle)
tsdb-tool connections
# All connections including idle
tsdb-tool connections --all
# Connection summary with memory config
tsdb-tool connections --summary
# Filter by user, database, or state
tsdb-tool connections --filter-user appuser --filter-db mydb
tsdb-tool connections --min-duration 5
Service & Maintenance
# Check server connectivity and version
tsdb-tool service check
# Vacuum a table
tsdb-tool service vacuum my_table
tsdb-tool service vacuum my_table --full
tsdb-tool service vacuum --all
# Kill a backend process
tsdb-tool service kill 12345
tsdb-tool service kill 12345 --cancel # cancel query only
TimescaleDB
# List hypertables
tsdb-tool ts hypertables
# Show chunks for a hypertable
tsdb-tool ts chunks myschema.sensor_data
# Compression statistics
tsdb-tool ts compression
tsdb-tool ts compression myschema.sensor_data
# Compression settings and policies
tsdb-tool ts compression-settings -s myschema
# Configure compression
tsdb-tool ts compression-set myschema.sensor_data --segmentby "device_id, sensor" --orderby "timestamp DESC"
tsdb-tool ts compression-set myschema.sensor_data --policy "4 hours"
# Compress chunks
tsdb-tool ts compress myschema.sensor_data
tsdb-tool ts compress myschema.sensor_data --chunk 11420
# Continuous aggregates
tsdb-tool ts caggs
# Retention policies
tsdb-tool ts retention
# Background jobs
tsdb-tool ts jobs
tsdb-tool ts jobs --history
tsdb-tool ts jobs --history --job 1005
Configuration
# Show resolved config with source attribution
tsdb-tool config show
# List available profiles
tsdb-tool config profiles
Output Formats
All listing commands support multiple output formats:
# Table format (default in terminal)
tsdb-tool -f table databases
# JSON format
tsdb-tool -f json databases
# Compact JSON
tsdb-tool --compact -f json databases
# CSV format (default when piped)
tsdb-tool databases | head
# CSV without header
tsdb-tool --no-header databases
Auto-detection: table format for TTY, CSV when piped.
Connection Options
Global flags (must appear before the subcommand):
tsdb-tool -H myhost -p 5432 -d mydb -U myuser query -e "SELECT 1"
tsdb-tool --dsn "postgresql://user@host/db" databases
tsdb-tool -P production table
| Flag | Env Var | Description |
|---|---|---|
-H, --host |
PGHOST |
PostgreSQL host |
-p, --port |
PGPORT |
PostgreSQL port |
-d, --database |
PGDATABASE |
Database name |
-U, --user |
PGUSER |
User name |
-W, --password |
PGPASSWORD |
Password |
--dsn |
Connection DSN | |
-P, --profile |
SQL_PROFILE |
Named profile |
Configuration File
Location: ~/.config/tsdb-tool/config.toml
default_timeout = 30
default_format = "table"
[profiles.local]
host = "localhost"
port = 5432
dbname = "postgres"
user = "postgres"
[profiles.production]
dsn = "postgresql://readonly@prod-db.example.com:5432/myapp?sslmode=verify-full"
[profiles.staging]
dsn = "postgresql://user@staging-db.example.com/myapp"
sslmode = "verify-full"
connect_timeout = 5
See config.example.toml for a full example.
Precedence (highest to lowest)
- CLI flags (
--host,--port, etc.) --dsnflag- Environment variables (
PGHOST,PGPORT, etc.) - Named profile (
--profileorSQL_PROFILE) - Config file defaults
- Built-in defaults (
localhost:5432/postgres)
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error (SQL syntax, permission denied) |
| 2 | Usage error (invalid arguments) |
| 3 | Input error (file not found, invalid parameters) |
| 5 | Network error (connection failed, authentication) |
| 6 | Timeout (query timeout, connection timeout) |
| 7 | Configuration error (malformed config, unknown profile) |
Development
# Run tests
uv run pytest
# Run with coverage
uv run pytest --cov=tsdb_tool
# Lint
uv run ruff check src/
# Type check
uv run mypy src/
Metadata
Release files for tsdb-tool 0.1.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tsdb_tool-0.1.3.tar.gz | 103.1 kB | Without provenance | Details for tsdb_tool-0.1.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tsdb_tool-0.1.3-py3-none-any.whl | Python 3 | none | any | Details for tsdb_tool-0.1.3-py3-none-any.whl |
Total release size: 155.6 kB
Release files / tsdb_tool-0.1.3.tar.gz
| Download URL | tsdb_tool-0.1.3.tar.gz |
|---|---|
| Size | 103.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4fc60fe36474a56c66c23e62a585aedf83fbe128dc72b3db56ade68709e8de02
|
|
BLAKE2b-256 checksum How to use checksums |
a07e1e2f83486507a4698ae43c3e472806886f96621aa63776cfcccb6f712577
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.3
|
Release files / tsdb_tool-0.1.3-py3-none-any.whl
| Download URL | tsdb_tool-0.1.3-py3-none-any.whl |
|---|---|
| Size | 52.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f81c08d365538bf7c7839bb02a2fa46f540b3e15246689967149f99fc5431f4a
|
|
BLAKE2b-256 checksum How to use checksums |
fa38603a8fe395a143d1a94fcd0932923c4c8b3d843a4607e2bae7f5dcffce46
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.3
|
Security for tsdb-tool 0.1.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.