SQL-Top 🚀

Live Query Monitor для PostgreSQL, MySQL и ClickHouse — терминальный TUI-профайлер баз данных в реальном времени.

📖 Оглавление

• Возможности
• Установка
• Быстрый старт
• Использование
• Горячие клавиши
• Архитектура
• Конфигурация
• Примеры подключения
• Разработка
• Тестирование
• Соответствие стандартам

---

✨ Возможности

🔍 Мониторинг в реальном времени

• Live-обновление активных запросов каждую секунду
• Diff-движок для отслеживания новых/завершённых запросов
• История до 5000 запросов в кольцевом буфере

🎯 Поддержка СУБД

СУБД	Версии	Драйвер
PostgreSQL	12+	pgx/v5
MySQL	5.7+, 8.0+	go-sql-driver/mysql
ClickHouse	21.8+	clickhouse-go/v2

🛠 Функции профайлинга

• Просмотр активных запросов с детализацией:
  • PID / query_id
  • Пользователь и база данных
  • Состояние (state)
  • Длительность выполнения
  • Потребление памяти (ClickHouse)
  • Настройки сессии (PostgreSQL)
• EXPLAIN запросов — план выполнения без выхода из приложения
• Kill Query — завершение долгих запросов по PID
• Копирование запроса в буфер обмена

🎨 Интерфейс

• TUI на bubbletea — современный терминальный интерфейс
• Адаптивная вёрстка — подстраивается под размер терминала
• Цветовая схема — выделение статусов и проблемных зон
• Модальные окна — для EXPLAIN, подтверждения Kill, копирования

---

📊 Сравнительный анализ инструментов мониторинга

Критерий	🚀 SQL-Top	🐍 pg_activity	🐘 DBeaver / DataGrip
Тип инструмента	TUI (Terminal UI)	TUI (Terminal UI)	GUI (Desktop IDE)
Язык / Стек	Go (Single Binary)	Python (pip deps)	Java / Eclipse
Портативность	✅ Отличная (~21MB, zero deps)	⚠️ Средняя (нужен Python/Libs)	📦 Низкая (500MB+ installer)
Время запуска	⏱️ Мгновенно (~70ms)	⏱️ Быстро (<500ms)	⏳ Долго (5–15 сек)
Поддержка СУБД	🔌 PG, MySQL, ClickHouse	❌ Только PostgreSQL	✅ Все популярные
Безопасность	🛡️ Safe EXPLAIN (No ANALYZE)	❌ Нет EXPLAIN в TUI	⚠️Опасно (ANALYZE по умолчанию)
Нагрузка на БД	📉 Минимальная (оптимизирован)	Минимальная	📊 Зависит от плагинов
Киллер-фича	💡 Delta Highlighting	Simple Monitor	Визуальный конструктор

Примечание: Измерения SQL-Top выполнены 07.04.2026 на Windows (Go 1.25.0). Время запуска: среднее из 5 запусков. Размер бинарника: без сжатия UPX. Сравнение с конкурентами основано на публичной документации.

---

📦 Установка

Требования

• Go 1.25.0+
• Terminal с поддержкой UTF-8
• Доступ к целевой БД

Из исходников

git clone https://github.com/turkprogrammer/sql-top.git
cd sql-top
go build -o sql-top ./...

Через go install

go install github.com/turkprogrammer/sql-top/cmd/sql-top@latest

Готовый бинарник

# Windows
sql-top.exe -dsn "postgres://user:pass@localhost:5432/db"# Linux/macOS
./sql-top -dsn "mysql://user:pass@localhost:3306/db"

---

🚀 Быстрый старт

PostgreSQL

sql-top postgres://postgres:password@localhost:5432/mydb

MySQL

sql-top mysql://root:password@localhost:3306/mydb

ClickHouse

sql-top clickhouse://default:password@localhost:9000/mydb

С флагом -dsn

sql-top -dsn postgres://user:pass@host:5432/db

---

📖 Использование

Основной интерфейс

После запуска вы увидите таблицу с активными запросами:

╭──────────────────────────────────────────────────────────────╮
│ SQL-Top — Live Query Monitor ● Connected │
├──────────────────────────────────────────────────────────────┤
│ PID User DB State Duration Query │
├──────────────────────────────────────────────────────────────┤
│ 12345 postgres mydb active 2.5s SELECT… │
│ 67890 app_user analytics idle 15.3s UPDATE… │
╰──────────────────────────────────────────────────────────────╯

Навигация

• ↑/↓ или j/k — перемещение по списку запросов
• Enter — показать EXPLAIN для выбранного запроса
• k — завершить запрос (требуется подтверждение)
• y — скопировать запрос в буфер обмена
• q или Ctrl+C — выход

Модальные окна

EXPLAIN Query

╭────────────────────────────────────────────╮
│ EXPLAIN QUERY [×] │
├────────────────────────────────────────────┤
│ Seq Scan on users │
│ Filter: (age > 25) │
│ Cost: 0.00..15.00 │
├────────────────────────────────────────────┤
│ Press ESC to close │
╰────────────────────────────────────────────╯

Kill Query Confirmation

╭────────────────────────────────────────────╮
│ ⚠ KILL QUERY CONFIRMATION [×] │
├────────────────────────────────────────────┤
│ Are you sure you want to kill query? │
│ PID: 12345 │
│ Query: SELECT * FROM large_table... │
├────────────────────────────────────────────┤
│ [y] Yes, kill it [n] No, cancel │
╰────────────────────────────────────────────╯

---

⌨ Горячие клавиши

Клавиша	Действие	Описание
↑ / k	Navigation Up	Переместиться вверх по списку
↓ / j	Navigation Down	Переместиться вниз по списку
Enter	Show EXPLAIN	Показать план выполнения запроса
k	Kill Query	Завершить выбранный запрос
y	Copy Query	Скопировать текст запроса
ESC	Close Modal	Закрыть модальное окно
q	Quit	Выход из приложения
Ctrl+C	Graceful Shutdown	Корректное завершение работы

---

🏗 Архитектура

Hexagonal Architecture + Composition

┌─────────────────────────────────────────────────┐
│ cmd/sql-top │
│ (Composition Root) │
└────────────────────┬────────────────────────────┘
│
┌────────────┴────────────┐
│ │
┌───────▼────────┐ ┌────────▼────────┐
│ UI Layer │ │ Domain Layer │
│ (bubbletea) │ │ (Interfaces) │
│ - model.go │ │ - provider.go │
│ - styles.go │ │ - sanitize.go │
│ - help.go │ │ - config.go │
└───────┬────────┘ └────────┬────────┘
│ │
│ ┌───────────────────┘
│ │
┌───────▼────────────────────────▼────────┐
│ Infrastructure Layer (Adapters) │
│ ┌──────────┬──────────┬─────────────┐ │
│ │ Postgres │ MySQL │ ClickHouse │ │
│ │ adapter │ adapter │ adapter │ │
│ │ fetcher │ fetcher │ fetcher │ │
│ │ explainer│explainer│ explainer │ │
│ └──────────┴──────────┴─────────────┘ │
└─────────────────────────────────────────┘

Структура проекта

sql-top/
├── cmd/
│ └── sql-top/
│ └── main.go # Точка входа, DI, graceful shutdown
├── internal/
│ ├── domain/
│ │ ├── provider.go # Интерфейсы (ports) и типы
│ │ ├── sanitize.go # Санитизация запросов и DSN
│ │ ├── diff.go # Diff-движок для запросов
│ │ ├── query.go # Тип WaitEventType и методы
│ │ └── config.go # Константы конфигурации
│ ├── infrastructure/
│ │ ├── base/
│ │ │ └── adapter.go # Базовый адаптер (composition)
│ │ ├── postgres/
│ │ ├── mysql/
│ │ └── clickhouse/
│ ├── history/
│ │ └── ringbuffer.go # Кольцевой буфер истории
│ └── ui/
│ ├── model.go # TUI модель (bubbletea)
│ ├── styles.go # Стили lipgloss
│ └── help.go # Справка
├── go.mod
├── go.sum
└── README.md

Dependency Injection

// main.go — Composition Rootfuncmain() {
logger:=createLogger()
adapter:=createAdapter(dsn, logger) // DI loggermodel:=ui.NewModel(adapter, logger) // DI loggerp:=tea.NewProgram(model, tea.WithAltScreen())
p.Run()
}

---

⚙ Конфигурация

Константы (domain/config.go)

Подключение к БД

Константа	Значение	Описание
DefaultMaxConns	2	Макс. количество подключений в пуле
DefaultMinConns	1	Мин. количество подключений в пуле
DefaultConnMaxLifetime	5 мин	Время жизни подключения

Polling

Константа	Значение	Описание
DefaultPollInterval	1 сек	Интервал опроса активных запросов
DefaultRingBufferCapacity	5000	Ёмкость буфера истории

UI

Константа	Значение	Описание
DefaultModalWidth	80	Ширина модального окна
DefaultModalHeight	30	Высота модального окна
DefaultQueryTruncateLength	60	Макс. длина запроса в таблице

Timeout

Константа	Значение	Описание
ClipboardConfirmTimeout	2 сек	Подтверждение копирования
PingInterval	5 сек	Интервал ping проверки
KillQueryTimeout	5 сек	Timeout для kill query
ExplainQueryTimeout	10 сек	Timeout для explain query

Переменные окружения

Переменная	Значение по умолчанию	Описание
SQLTOP_DEBUG	0	Включает debug-логирование (установите 1)
SQLTOP_KILL_TIMEOUT	5s	Timeout для завершения запроса (kill query)
SQLTOP_EXPLAIN_TIMEOUT	10s	Timeout для получения плана выполнения (EXPLAIN)
SQLTOP_PING_INTERVAL	5s	Интервал проверки подключения к БД
SQLTOP_CLIPBOARD_TIMEOUT	2s	Время отображения подтверждения копирования

# Включить debug-режимexport SQLTOP_DEBUG=1
# Увеличить таймауты для медленной БДexport SQLTOP_KILL_TIMEOUT=30s
export SQLTOP_EXPLAIN_TIMEOUT=60s
# Изменить интервал pingexport SQLTOP_PING_INTERVAL=10s
# Запуск с настройками
sql-top postgres://user:pass@localhost:5432/db

---

🔗 Примеры подключения

PostgreSQL

# Локальное подключение
sql-top postgres://postgres:password@localhost:5432/mydb
# Удалённое подключение с SSL
sql-top postgres://user:pass@db.example.com:5432/prod?sslmode=require
# С указанием схемы
sql-top postgres://user:pass@localhost:5432/db?search_path=analytics

MySQL

# Локальное подключение
sql-top mysql://root:password@localhost:3306/mydb
# Удалённое подключение
sql-top mysql://app:secret@db.example.com:3306/production
# С TLS
sql-top mysql://user:pass@localhost:3306/db?tls=preferred

ClickHouse

# Локальное подключение
sql-top clickhouse://default:password@localhost:9000/mydb
# Удалённое подключение
sql-top clickhouse://admin:secret@clickhouse.example.com:9000/analytics
# С указанием базы данных
sql-top clickhouse://user:pass@localhost:9000/default

---

🛠 Разработка

Требования для разработки

• Go 1.25.0+
• Git
• Доступ к тестовой БД (PostgreSQL/MySQL/ClickHouse)

Клонирование

git clone https://github.com/turkprogrammer/sql-top.git
cd sql-top
go mod download

Сборка

# Сборка для текущей ОС
go build ./...
# Кросс-компиляция
GOOS=linux GOARCH=amd64 go build -o sql-top-linux ./cmd/sql-top
GOOS=windows GOARCH=amd64 go build -o sql-top.exe ./cmd/sql-top

Запуск в режиме разработки

# С debug-логированием
SQLTOP_DEBUG=1 go run ./cmd/sql-top -dsn "postgres://..."# С указанием DSN
go run ./cmd/sql-top postgres://localhost:5432/mydb

---

🧪 Тестирование

Запуск всех тестов

go test ./... -count=1 -v

Покрытие тестами

go test ./... -coverprofile=coverage.out
go tool cover -html=coverage.out

Статический анализ

# Встроенный vet
go vet ./...
# Staticcheck
staticcheck ./...
# Форматирование
gofmt -l .
gofmt -w .# Автоисправление

Структура тестов

internal/
├── domain/
│ ├── sanitize_test.go # 6 тестов
│ └── diff_test.go # 8 тестов
├── infrastructure/
│ ├── postgres/
│ │ └── fetcher_test.go # 4 теста
│ ├── mysql/
│ │ └── fetcher_test.go # 4 теста
│ └── clickhouse/
│ └── fetcher_test.go # 4 теста
└── ui/
└── model_test.go # 17 тестов

Итого: 44 unit-теста, покрытие критичных путей ~50%.

Примечание: Текущие тесты покрывают изолированные компоненты (domain, UI логика, конструкторы адаптеров). Интеграционные тесты с реальными БД находятся в разработке.

---

✅ Соответствие стандартам

Code Quality

SQL-Top соответствует современным Go-практикам:

Принцип	Статус	Описание
KISS	✅	Простая архитектура без избыточных абстракций
YAGNI	✅	Нет преждевременной оптимизации
SOLID	✅	Интерфейсы в domain, реализация в infrastructure
Hexagonal Architecture	✅	Ports & Adapters + Dependency Injection
Error Handling	✅	Все ошибки обёрнуты с %w, errors.Is() для сравнений
Graceful Shutdown	✅	Context cancellation + signal handling
No Globals	✅	DI через параметры, нет синглтонов
Functions ≤50 LOC	✅	Все функции ≤50 строк
Defensive Coding	✅	Nil guards, resource leak prevention, defensive copies
Structured Logging	✅	log/slog во всех слоях, DSN маскируется

Code Quality Metrics

# 0 warnings
go vet ./... # ✅ чисто
gofmt -l .# ✅ чисто# Тесты
go test ./... # ✅ 44 теста проходят

---

📝 Лицензия

MIT License — см. файл LICENSE для деталей.

---

🤝 Contributing

Как внести вклад

1. Fork репозиторий
2. Создайте feature branch (git checkout -b feature/amazing-feature)
3. Commit изменения (git commit -m 'Add amazing feature')
4. Push в branch (git push origin feature/amazing-feature)
5. Откройте Pull Request

Требования к коду

• Форматирование:gofmt перед коммитом
• Тесты: Покрытие для новой функциональности
• Документация: Обновление README при изменении API
• Стандарты: Соответствие Qwen.md принципам

---

🙏 Благодарности

• bubbletea — TUI фреймворк
• lipgloss — Стили для терминала
• pgx — PostgreSQL драйвер
• clickhouse-go — ClickHouse драйвер