Database API

p

Техническая архитектура и базовые протоколы

Database API в экосистеме SourceMod представляет собой абстрактный слой, обеспечивающий унифицированный доступ к реляционным СУБД. Его ядро компилируется в двоичный модуль, который взаимодействует с внешними библиотеками, такими как libmysqlclient или sqlite3. API использует драйверную модель, где каждый драйвер реализует стандартный интерфейс для обработки соединений, пулов и транзакций. Это позволяет подключаться к MySQL, PostgreSQL и SQLite через идентичный набор нативных функций, минимизируя код плагина. Архитектура строго разделяет логику установки соединения и выполнения запросов, что критично для стабильности сервера.

Точная процедура настройки драйверов и подключения

Перед использованием API необходимо обеспечить наличие и корректную настройку драйверов на уровне SourceMod. Для MySQL требуется файл libmysqlclient, который размещается в папке extensions. Драйвер SQLite поставляется в составе базовой сборки SourceMod. Основная конфигурация подключений хранится в файле databases.cfg в формате KeyValues. В этом файле вы определяете именованные профили подключений с конкретными параметрами. Каждый профиль должен содержать точные технические параметры, включая таймауты и размер пула. Без корректного конфигурационного файла плагин не сможет установить связь с базой данных.

После редактирования файла databases.cfg перезапуск сервера не обязателен. Конфигурация перечитывается при каждом запросе нового соединения через API. Однако изменения в самих драйверах (замена файлов .dll/.so) требуют полной перезагрузки серверного процесса.

Методы написания и оптимизации SQL-запросов

Эффективность плагина напрямую зависит от качества формируемых SQL-запросов. Database API предоставляет два основных метода: `SQL_Query` для операций чтения (SELECT) и `SQL_Execute` или `SQL_Query` для операций изменения (INSERT, UPDATE, DELETE). Все строки запросов должны быть экранированы через `SQL_EscapeString` для предотвращения инъекций. Для параметризованных запросов используйте `SQL_BindParamInt`, `SQL_BindParamFloat`, `SQL_BindParamString` — это предпочтительный метод, повышающий безопасность и производительность. Избегайте составления запросов через конкатенацию строк с пользовательским вводом.

Критически важна оптимизация запросов, выполняемых в игровых тиках, таких как `OnPlayerDeath` или `OnRoundStart`. Создавайте индексы в таблицах базы данных на часто запрашиваемых столбцах, например, `steamid`, `timestamp`. Для сложных операций агрегации (подсчёт статистики) используйте предварительно рассчитанные таблицы или кэширование результатов в памяти плагина. Лимитируйте выборки с помощью `LIMIT` и выбирайте только необходимые столбцы, а не `SELECT *`.

Управление асинхронными операциями и потоками

Синхронные запросы блокируют основной поток сервера, что приводит к "лагам" при высокой нагрузке. Database API реализует асинхронную модель через обратные вызовы (callbacks). Используйте функции `SQL_TQuery` для неблокирующего выполнения. Эта функция принимает хендл базы данных, строку запроса, ссылку на функцию-обработчик и произвольные данные (DataPack или значение). Сервер продолжает обрабатывать игровые события, пока запрос выполняется в отдельном потоке пула. По завершении запроса вызывается указанная функция, где вы можете обработать результат через `SQL_GetRowCount` и `SQL_FetchRow`.

Асинхронная модель требует тщательного управления памятью. Все хендлы, созданные в ходе запроса (например, `DBResultSet`), должны быть закрыты в коллбэке с помощью `CloseHandle()`. Утечка хендлов приводит к постепенному увеличению потребления памяти и нестабильности сервера. Используйте встроенные отладчики SourceMod для мониторинга количества открытых хендлов.

Стандарты безопасности и предотвращение уязвимостей

Безопасность взаимодействия с базой данных строится на двух принципах: валидация входных данных и параметризация запросов. Любые данные, полученные от клиента (никнейм, сообщение в чате), должны рассматриваться как потенциально опасные. Перед использованием в запросе их необходимо обработать функцией `SQL_EscapeString`, которая экранирует специальные символы. Однако более надежным методом является использование привязки параметров через `SQL_BindParam`. Этот метод передаёт данные отдельно от текста запроса, что полностью исключает возможность SQL-инъекции на уровне драйвера.

Настройте права доступа пользователя базы данных (для MySQL/PostgreSQL) по принципу минимальных привилегий. Учётная запись, которую использует игровой сервер, не должна иметь прав на DROP, GRANT или доступ к другим базам. Ограничьте её права только необходимыми операциями SELECT, INSERT, UPDATE, DELETE на конкретных таблицах. Регулярно обновляйте драйверы и библиотеки СУБД для устранения известных уязвимостей. Ведение детального лога всех ошибок базы данных в отдельный файл поможет вовремя обнаружить попытки атак или сбои в работе.

Мониторинг производительности и отладка запросов

Производительность Database API мониторится через комбинацию инструментов SourceMod и внешних средств СУБД. Включите детальное логирование запросов в конфигурации SourceMod, добавив `log_queries 1` в `sourcemod.cfg`. Это заставит движок записывать все выполняемые запросы и их время выполнения в файл `logs/sql.log`. Анализируйте этот лог на предмет медленных запросов, время выполнения которых превышает 100 миллисекунд. Для MySQL используйте встроенный slow query log, настроив параметр `long_query_time`. Профилируйте проблемные запросы с помощью `EXPLAIN` для выявления отсутствующих индексов или полных сканирований таблиц.

При отладке используйте встроенные функции SourceMod для проверки состояния соединения, такие как `SQL_IsSameConnection` или `SQL_CheckConfig`. Для симуляции нагрузки и проверки стабильности создайте тестовый плагин, который генерирует массовые параллельные запросы. Контролируйте использование оперативной памяти серверным процессом во время такой нагрузки. Убедитесь, что конфигурация пула соединений в `databases.cfg` соответствует реальной нагрузке, и при необходимости откорректируйте параметры `max_connections` и `timeout`.

Добавлено: 21.04.2026