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
--statusShow current circuit breaker status
--resetReset circuit breaker
--jsonOutput as JSON
-c, --config <path>Path to configuration file

Examples​

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

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

Circuit Breaker States​

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

analyzer​

Query pattern analyzer for identifying optimization opportunities.

kysera debug analyzer [options]

Options​

OptionDescription
--since <datetime>Analyze queries since datetime
--top <n>Show top N patterns (default: 10)
--jsonOutput as JSON
-c, --config <path>Path to configuration file

Examples​

# Analyze query patterns
kysera debug analyzer

# Show top 20 patterns
kysera debug analyzer --top 20

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​