tsdb-sql-tool 0.1.0__tar.gz

tsdb_sql_tool-0.1.0/.envrc

@@ -0,0 +1,5 @@
+export SQL_TOOL_TEST_PROFILE=piccolo_dev_magnum
+export SQL_TOOL_TEST_SCHEMA=magnum
+export SQL_TOOL_TEST_TABLE=magnum_data
+export SQL_TOOL_TEST_DATABASE=piccolo_dev
+export SQL_TOOL_TEST_PLAIN_TABLE=flyway_schema_history

tsdb_sql_tool-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,134 @@
+# Contributing to sql-tool
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.13+
+- [uv](https://docs.astral.sh/uv/) (package manager)
+- PostgreSQL 15+ (for integration tests)
+- TimescaleDB extension (optional, for TimescaleDB command tests)
+
+### Install Dependencies
+
+```bash
+git clone https://github.com/vladistan/sql-tool.git
+cd sql-tool
+uv sync --all-extras
+```
+
+### Configure a Test Database Profile
+
+Integration tests require a running PostgreSQL instance. Create a config file at `~/.config/sql-tool/config.toml`:
+
+```toml
+[profiles.test_db]
+host = "localhost"
+port = 5432
+dbname = "postgres"
+user = "postgres"
+password = "your_password"
+default_schema = "public"
+```
+
+See `config.example.toml` for more configuration options including DSN-style connections.
+
+### Integration Test Environment Variables
+
+Integration tests use environment variables to locate your test database objects. Set these to match your local setup:
+
+```bash
+export SQL_TOOL_TEST_PROFILE=test_db              # Config profile name
+export SQL_TOOL_TEST_SCHEMA=public                 # Schema with test tables
+export SQL_TOOL_TEST_TABLE=my_hypertable           # A TimescaleDB hypertable
+export SQL_TOOL_TEST_DATABASE=postgres              # Database name
+export SQL_TOOL_TEST_PLAIN_TABLE=some_regular_table # A non-hypertable table
+```
+
+If not set, tests use generic defaults (`myschema`, `sensor_data`, etc.) that you would need to create in your database.
+
+## Development Workflow
+
+### Running Tests
+
+```bash
+# All tests
+uv run pytest
+
+# Unit tests only (no database required)
+uv run pytest -m unit
+
+# Integration tests only (requires PostgreSQL)
+uv run pytest -m integration
+
+# Skip slow tests
+uv run pytest -m "not slow"
+```
+
+### Linting
+
+```bash
+# Check for issues
+uv run ruff check src/ tests/
+
+# Auto-fix issues
+uv run ruff check --fix src/ tests/
+
+# Format code
+uv run ruff format src/ tests/
+```
+
+### Type Checking
+
+```bash
+uv run mypy src/
+```
+
+### Pre-commit Hooks
+
+```bash
+uv run pre-commit install
+uv run pre-commit run --all-files
+```
+
+## Code Style
+
+- Line length: 88 characters
+- Formatting: ruff (Black-compatible)
+- Import sorting: ruff isort
+- Type annotations: required for all public functions (mypy strict mode)
+- Test coverage: minimum 80%
+
+## Project Structure
+
+```
+src/sql_tool/
+├── cli/           # CLI commands (typer)
+│   ├── commands/  # Subcommand groups (pg, ts, query)
+│   ├── helpers.py # CLI utilities
+│   ├── main.py    # Entry point
+│   └── output.py  # Output formatting
+├── core/          # Core logic
+│   ├── client.py  # PostgreSQL client
+│   ├── config.py  # Configuration loading
+│   ├── models.py  # Data models
+│   ├── postgres.py      # PostgreSQL admin queries
+│   └── timescaledb.py   # TimescaleDB admin queries
+└── formatters/    # Output formatters (table, json, csv)
+
+tests/
+├── cli/           # CLI integration tests
+├── fixtures/      # SQL fixtures
+├── test_client.py
+├── test_config.py
+└── ...
+```
+
+## Submitting Changes
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-change`)
+3. Make your changes
+4. Run the full check suite: `uv run ruff check src/ tests/ && uv run mypy src/ && uv run pytest`
+5. Commit with a descriptive message
+6. Open a pull request

tsdb_sql_tool-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vlad Korolev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tsdb_sql_tool-0.1.0/PKG-INFO

@@ -0,0 +1,309 @@
+Metadata-Version: 2.4
+Name: tsdb-sql-tool
+Version: 0.1.0
+Summary: PostgreSQL query and administration CLI tool
+Project-URL: Homepage, https://github.com/vladistan/sql-tool
+Project-URL: Repository, https://github.com/vladistan/sql-tool
+Project-URL: Issues, https://github.com/vladistan/sql-tool/issues
+Author-email: Vlad Korolev <vlad@v-lad.org>
+License: MIT
+License-File: LICENSE
+Keywords: admin,cli,database,postgresql,sql,timescaledb
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.13
+Requires-Dist: psycopg[binary]>=3.1.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: sentry-sdk>=1.40.0
+Requires-Dist: structlog>=24.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sql-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
+
+```bash
+git clone <repository-url>
+cd sql-tool
+uv sync
+```
+
+Run commands with `uv run sql-tool` or install globally:
+
+```bash
+uv tool install .
+```
+
+## Quick Start
+
+```bash
+# Check connectivity
+sql-tool service check
+
+# Run a query
+sql-tool query -e "SELECT now()"
+
+# List databases
+sql-tool databases
+
+# List tables in a schema
+sql-tool -s myschema table
+
+# Show table columns and preview data
+sql-tool table myschema.sensor_data --head 5
+```
+
+## Commands
+
+### Query Execution
+
+```bash
+# Inline query
+sql-tool query -e "SELECT * FROM users LIMIT 10"
+
+# From file
+sql-tool query queries/report.sql
+
+# From stdin
+echo "SELECT 1" | sql-tool query
+
+# With timeout
+sql-tool query -e "SELECT pg_sleep(5)" -t 3
+```
+
+### Database Overview
+
+```bash
+# List all databases (sorted by size)
+sql-tool databases
+
+# List schemas with space usage
+sql-tool schema
+
+# Schemas across all databases
+sql-tool schema --all-databases
+```
+
+### Table Inspection
+
+```bash
+# List all tables with sizes
+sql-tool table
+
+# Filter by schema
+sql-tool -s myschema table
+
+# Show column definitions
+sql-tool table myschema.sensor_data
+
+# Preview data
+sql-tool table myschema.sensor_data --head 10
+sql-tool table myschema.sensor_data --tail 5
+sql-tool table myschema.sensor_data --sample 3
+
+# Show timestamp range for hypertables
+sql-tool table myschema.sensor_data --range
+```
+
+### Connections
+
+```bash
+# Active connections (non-idle)
+sql-tool connections
+
+# All connections including idle
+sql-tool connections --all
+
+# Connection summary with memory config
+sql-tool connections --summary
+
+# Filter by user, database, or state
+sql-tool connections --filter-user appuser --filter-db mydb
+sql-tool connections --min-duration 5
+```
+
+### Service & Maintenance
+
+```bash
+# Check server connectivity and version
+sql-tool service check
+
+# Vacuum a table
+sql-tool service vacuum my_table
+sql-tool service vacuum my_table --full
+sql-tool service vacuum --all
+
+# Kill a backend process
+sql-tool service kill 12345
+sql-tool service kill 12345 --cancel  # cancel query only
+```
+
+### TimescaleDB
+
+```bash
+# List hypertables
+sql-tool ts hypertables
+
+# Show chunks for a hypertable
+sql-tool ts chunks myschema.sensor_data
+
+# Compression statistics
+sql-tool ts compression
+sql-tool ts compression myschema.sensor_data
+
+# Compression settings and policies
+sql-tool ts compression-settings -s myschema
+
+# Configure compression
+sql-tool ts compression-set myschema.sensor_data --segmentby "device_id, sensor" --orderby "timestamp DESC"
+sql-tool ts compression-set myschema.sensor_data --policy "4 hours"
+
+# Compress chunks
+sql-tool ts compress myschema.sensor_data
+sql-tool ts compress myschema.sensor_data --chunk 11420
+
+# Continuous aggregates
+sql-tool ts caggs
+
+# Retention policies
+sql-tool ts retention
+
+# Background jobs
+sql-tool ts jobs
+sql-tool ts jobs --history
+sql-tool ts jobs --history --job 1005
+```
+
+### Configuration
+
+```bash
+# Show resolved config with source attribution
+sql-tool config show
+
+# List available profiles
+sql-tool config profiles
+```
+
+## Output Formats
+
+All listing commands support multiple output formats:
+
+```bash
+# Table format (default in terminal)
+sql-tool -f table databases
+
+# JSON format
+sql-tool -f json databases
+
+# Compact JSON
+sql-tool --compact -f json databases
+
+# CSV format (default when piped)
+sql-tool databases | head
+
+# CSV without header
+sql-tool --no-header databases
+```
+
+Auto-detection: table format for TTY, CSV when piped.
+
+## Connection Options
+
+Global flags (must appear before the subcommand):
+
+```bash
+sql-tool -H myhost -p 5432 -d mydb -U myuser query -e "SELECT 1"
+sql-tool --dsn "postgresql://user@host/db" databases
+sql-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/sql-tool/config.toml`
+
+```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)
+
+1. CLI flags (`--host`, `--port`, etc.)
+2. `--dsn` flag
+3. Environment variables (`PGHOST`, `PGPORT`, etc.)
+4. Named profile (`--profile` or `SQL_PROFILE`)
+5. Config file defaults
+6. 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
+
+```bash
+# Run tests
+uv run pytest
+
+# Run with coverage
+uv run pytest --cov=sql_tool
+
+# Lint
+uv run ruff check src/
+
+# Type check
+uv run mypy src/
+```