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 Root
func main() {
    logger := createLogger()
    adapter := createAdapter(dsn, logger) // DI logger
    model := ui.NewModel(adapter, logger) // DI logger
    
    p := 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

# Изменить интервал ping
export 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

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

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

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

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

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

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

Name		Name	Last commit message	Last commit date
cmd/sql-top		cmd/sql-top
docs		docs
internal		internal
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
go.mod		go.mod
go.sum		go.sum

Latest commit

History

Folders and files

Repository files navigation

SQL-Top 🚀

📖 Оглавление

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

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

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

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

🎨 Интерфейс

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

📦 Установка

Требования

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

Через go install

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

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

PostgreSQL

MySQL

ClickHouse

С флагом -dsn

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

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

Навигация

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

EXPLAIN Query

Kill Query Confirmation

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

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

Hexagonal Architecture + Composition

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

Dependency Injection

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

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

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

Polling

UI

Timeout

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

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

PostgreSQL

MySQL

ClickHouse

🛠 Разработка

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

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

Сборка

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

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

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

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

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

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

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

Code Quality

Code Quality Metrics

📝 Лицензия

🤝 Contributing

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

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

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

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages