Skip to main content

kysera debug

Debug and performance analysis tools for SQL queries and database operations.

Commands​

CommandDescription
sqlReal-time SQL query monitoring and debugging
profileQuery profiling and performance analysis
errorsError analysis and diagnostics
circuit-breakerCircuit breaker status and management
analyzerQuery pattern analyzer

sql​

Real-time SQL query monitoring and debugging.

kysera debug sql [options]

Options​

OptionDescription
-w, --watchWatch mode - monitor queries in real-time
-f, --filter <pattern>Filter queries by pattern (regex)
-h, --highlight <keyword>Highlight specific keywords
--show-paramsShow query parameters
--show-durationShow query execution time
-l, --limit <n>Limit number of queries to show (default: 50)
-c, --config <path>Path to configuration file

Examples​

# Watch queries in real-time
kysera debug sql --watch

# Watch with duration display
kysera debug sql --watch --show-duration

# Filter queries by pattern
kysera debug sql --watch --filter "SELECT.*users"

# Highlight specific keywords
kysera debug sql --watch --highlight "JOIN"

# Show query parameters
kysera debug sql --watch --show-params

# Analyze recent queries from logs
kysera debug sql --limit 100

Output​

In watch mode, each query is displayed with:

  • Timestamp
  • Query ID and status (✓ success / ✗ error)
  • Duration (if --show-duration)
  • Row count
  • SQL with syntax highlighting
  • Parameters (if --show-params)

The command also provides summary statistics:

  • Top query patterns by frequency
  • Slow queries (>1s)
  • Failed queries with errors
  • Success rate, average duration, P95 duration

profile​

Query profiling and performance analysis with statistical metrics.

kysera debug profile [options]

Options​

OptionDescription
-q, --query <sql>SQL query to profile
-t, --table <name>Profile queries on specific table
-o, --operation <type>Operation type: select, insert, update, delete
-i, --iterations <n>Number of iterations (default: 100)
-w, --warmup <n>Number of warmup runs (default: 10)
--show-planShow query execution plan
--compare <query>Compare with another query
--jsonOutput as JSON
-c, --config <path>Path to configuration file

Examples​

# Profile a specific query
kysera debug profile --query "SELECT * FROM users WHERE status = 'active'"

# Profile table operations
kysera debug profile --table users --operation select

# Profile with execution plan
kysera debug profile --query "SELECT * FROM orders" --show-plan

# Compare two queries
kysera debug profile \
  --query "SELECT * FROM users WHERE id = 1" \
  --compare "SELECT * FROM users WHERE email = 'test@example.com'"

# Custom iterations
kysera debug profile --query "SELECT 1" --iterations 1000 --warmup 50

Output​

Profile results include:

Performance Metrics:

  • Average duration
  • Minimum/Maximum duration
  • P50 (Median), P95, P99 percentiles
  • Standard deviation

Response Time Distribution:

  • Histogram showing timing distribution

Execution Plan (with --show-plan):

  • PostgreSQL: EXPLAIN ANALYZE output
  • MySQL: EXPLAIN output
  • SQLite: EXPLAIN QUERY PLAN output

Analysis:

  • Performance rating (Excellent/Good/Moderate/Poor)
  • Consistency rating based on standard deviation

errors​

Error analysis and diagnostics.

kysera debug errors [options]

Options​

OptionDescription
--since <datetime>Show errors since datetime
--type <error-type>Filter by error type
-l, --limit <n>Limit number of results
--jsonOutput as JSON
-c, --config <path>Path to configuration file

Examples​

# Show recent errors
kysera debug errors

# Show errors from last 24 hours
kysera debug errors --since "2025-01-01T00:00:00"

# Filter by error type
kysera debug errors --type "UNIQUE_CONSTRAINT"

circuit-breaker​

Circuit breaker status and management.

kysera debug circuit-breaker [options]

Options​

OptionDescription
-a, --action <type>Action: status, reset, open, close (default: status)
-s, --service <name>Service name: database, cache, api
-t, --threshold <n>Error threshold for opening circuit (default: 5)
--timeout <ms>Reset timeout in milliseconds (default: 30000)
-w, --watchWatch mode - monitor in real-time
--jsonOutput as JSON
-c, --config <path>Path to configuration file

Examples​

# Check circuit breaker status
kysera debug circuit-breaker --action status

# Check specific service
kysera debug circuit-breaker --service database

# Reset circuit breaker
kysera debug circuit-breaker --action reset

# Manually open circuit breaker
kysera debug circuit-breaker --action open --service database

# Close circuit breaker
kysera debug circuit-breaker --action close

# Watch mode - real-time monitoring
kysera debug circuit-breaker --watch

# Configure threshold and timeout
kysera debug circuit-breaker --threshold 10 --timeout 60000

Circuit Breaker States​

StateDescription
CLOSEDNormal operation, requests pass through
OPENCircuit is open, requests fail fast
HALF_OPENTesting if service recovered

analyzer​

Query analyzer for identifying optimization opportunities, index usage, and performance insights.

kysera debug analyzer [options]

Options​

OptionDescription
-q, --query <sql>SQL query to analyze
-t, --table <name>Analyze queries for specific table
-e, --explainShow execution plan
-s, --suggestionsShow optimization suggestions (default: true)
-i, --indexesAnalyze index usage
--statisticsShow table statistics
--jsonOutput as JSON
-c, --config <path>Path to configuration file

Examples​

# Analyze a specific query
kysera debug analyzer --query "SELECT * FROM users WHERE email = 'test@example.com'"

# Analyze with execution plan
kysera debug analyzer --query "SELECT * FROM orders" --explain

# Analyze table indexes
kysera debug analyzer --table users --indexes

# Show table statistics
kysera debug analyzer --table orders --statistics

# Get optimization suggestions
kysera debug analyzer --query "SELECT * FROM users" --suggestions

# Full analysis with all features
kysera debug analyzer --table users --indexes --statistics --suggestions

# Output as JSON
kysera debug analyzer --table users --json

Output​

Query Analysis:

  • Estimated cost and rows
  • Index recommendations
  • Missing indexes detection
  • Query complexity score

Index Analysis (with --indexes):

  • Index usage statistics
  • Unused indexes
  • Duplicate indexes
  • Recommended indexes

Table Statistics (with --statistics):

  • Row count
  • Table size
  • Index size
  • Average row size

Configuration​

Debug commands use the database configuration from kysera.config.ts:

import { defineConfig } from '@kysera/cli'

export default defineConfig({
  database: {
    dialect: 'postgres',
    host: 'localhost',
    database: 'myapp'
  }
})

Requirements​

Some debug features require additional setup:

Query Logging Table​

For debug sql without watch mode:

CREATE TABLE query_logs (
  id SERIAL PRIMARY KEY,
  query_text TEXT NOT NULL,
  duration_ms INTEGER,
  error TEXT,
  executed_at TIMESTAMP DEFAULT NOW()
);

Kysera Debug Plugin​

For automatic query logging, use @kysera/debug:

import { createDebugPlugin } from '@kysera/debug'

const debugPlugin = createDebugPlugin({
  logQueries: true,
  logSlowQueries: true,
  slowQueryThreshold: 1000
})

See Also​