mcp-dbutils

# Руководство по использованию *[English](../en/usage.md) | [中文](../zh/usage.md) | [Français](../fr/usage.md) | [Español](../es/usage.md) | [العربية](../ar/usage.md) | Русский* Этот документ предоставляет подробные инструкции по использованию MCP Database Utilities, помогая вам максимально использовать его возможности для анализа данных с помощью ИИ. ## Основной рабочий процесс Основной рабочий процесс использования MCP Database Utilities выглядит следующим образом: 1. **Настройка подключений к базе данных**: Определите ваши подключения к базе данных в файле `config.yaml` 2. **Запуск службы MCP**: Запустите службу через конфигурацию вашего ИИ-клиента 3. **Взаимодействие с ИИ**: Задавайте вопросы о ваших базах данных на естественном языке 4. **Просмотр результатов**: ИИ выполнит необходимые запросы и представит результаты в легко понятном формате ## Доступные инструменты MCP Database Utilities предоставляет несколько инструментов, которые может использовать ваш ИИ: ### dbutils-list-connections Перечисляет все доступные подключения к базам данных с подробной информацией, включая тип базы данных, хост, порт и имя базы данных, скрывая конфиденциальную информацию, такую как пароли. Опциональный параметр check_status позволяет проверить, доступно ли каждое соединение, хотя это может увеличить время отклика. Используйте этот инструмент, когда вам нужно понять доступные ресурсы базы данных или диагностировать проблемы с подключением. **Пример взаимодействия**: **Вы**: "Какие подключения к базам данных у меня доступны?" **ИИ**: "Я проверю ваши доступные подключения к базам данных. Вот что я нашел: 1. **postgres-db** - Тип: PostgreSQL - Хост: localhost - База данных: analytics - Пользователь: analyst 2. **sqlite-db** - Тип: SQLite - Путь: /path/to/database.db 3. **mysql-db** - Тип: MySQL - Хост: db.example.com - База данных: customer_data - Пользователь: reader" ### dbutils-list-tables Перечисляет все таблицы в указанном подключении к базе данных с именами таблиц, URI и доступными описаниями, сгруппированными по типу базы данных для удобной идентификации. Этот инструмент полезен для исследования структуры базы данных и понимания, какие таблицы доступны для анализа. **Пример взаимодействия**: **Вы**: "Перечислите все таблицы в моей базе данных postgres." **ИИ**: "Я проверю это для вас. Вот таблицы в вашей базе данных postgres: - клиенты - продукты - заказы - инвентарь - сотрудники" ### dbutils-run-query Выполняет запросы SQL только для чтения (только SELECT) к указанной базе данных, с поддержкой сложных запросов, включая JOIN, GROUP BY и агрегатные функции, возвращая структурированные результаты с именами столбцов и строками данных. Этот инструмент необходим для извлечения конкретной информации из баз данных и проведения пользовательского анализа. **Пример взаимодействия**: **Вы**: "Запросите количество клиентов, которые зарегистрировались за последние 30 дней." **ИИ**: "Я проверю это для вас. Согласно данным, за последние 30 дней было 42 новых регистрации клиентов." ### dbutils-describe-table Предоставляет подробную информацию о структуре таблицы, включая имена столбцов, типы данных, допустимость NULL, значения по умолчанию и комментарии в удобочитаемом формате. Этот инструмент особенно полезен для понимания схемы таблицы перед выполнением запросов или анализом данных. **Пример взаимодействия**: **Вы**: "Опишите структуру таблицы клиентов." **ИИ**: "Вот структура таблицы клиентов: | Столбец | Тип | Nullable | По умолчанию | Описание | |---------|------|----------|--------|-------------| | id | INTEGER | Нет | NULL | Уникальный идентификатор клиента | | name | VARCHAR(100) | Нет | NULL | Полное имя клиента | | email | VARCHAR(100) | Нет | NULL | Адрес электронной почты (уникальный) | | registration_date | DATE | Нет | CURRENT_DATE | Дата регистрации | | last_login | TIMESTAMP | Да | NULL | Временная метка последнего входа | | status | ENUM | Нет | 'активный' | Статус аккаунта (активный, неактивный, приостановлен) |" ### dbutils-get-ddl Получает полный оператор DDL (язык определения данных) для создания указанной таблицы, включая все определения столбцов, ограничения и индексы. Этот инструмент полезен для понимания точного определения таблицы или для воссоздания аналогичной структуры таблицы в другой среде. **Пример взаимодействия**: **Вы**: "Покажите мне DDL для таблицы заказов." **ИИ**: "Вот оператор DDL для таблицы заказов: ```sql CREATE TABLE orders ( order_id INT PRIMARY KEY AUTO_INCREMENT, customer_id INT NOT NULL, order_date DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, total_amount DECIMAL(10,2) NOT NULL CHECK (total_amount > 0), status VARCHAR(20) NOT NULL DEFAULT 'в обработке', FOREIGN KEY (customer_id) REFERENCES customers(id) ); CREATE INDEX idx_order_date ON orders(order_date); CREATE INDEX idx_customer_id ON orders(customer_id); ```" ### dbutils-list-indexes Перечисляет все индексы в указанной таблице, включая имена индексов, типы (уникальный/неуникальный), методы индексирования и включенные столбцы, сгруппированные по имени индекса. Этот инструмент полезен для понимания того, как индексирована таблица, что может помочь оптимизировать запросы и улучшить производительность. **Пример взаимодействия**: **Вы**: "Какие индексы существуют в таблице продуктов?" **ИИ**: "Вот индексы в таблице продуктов: 1. **pk_product_id** (Первичный) - Столбцы: product_id - Тип: B-tree - Уникальный: Да 2. **idx_category** (Вторичный) - Столбцы: category_id - Тип: B-tree - Уникальный: Нет 3. **idx_product_name** (Вторичный) - Столбцы: name - Тип: B-tree - Уникальный: Нет 4. **idx_price_category** (Вторичный) - Столбцы: price, category_id - Тип: B-tree - Уникальный: Нет" ### dbutils-get-stats Получает статистическую информацию о таблице, включая предполагаемое количество строк, среднюю длину строки, размер данных и размер индекса. Эта статистика полезна для понимания объема данных и планирования оптимизации производительности. **Пример взаимодействия**: **Вы**: "Получите статистику для таблицы продуктов." **ИИ**: "Вот статистика для таблицы продуктов: - Всего строк: 1,245 - Размер таблицы: 2.3 МБ - Статистика по столбцам: * product_id: 1,245 уникальных значений * категория: 8 различных категорий * цена: среднее $45.99, мин $5.99, макс $299.99" ### dbutils-list-constraints Перечисляет все ограничения в таблице, включая первичные ключи, внешние ключи, уникальные ограничения и ограничения проверки, с таблицами и столбцами, на которые ссылаются внешние ключи. Этот инструмент полезен для понимания отношений между таблицами и правил целостности данных. **Пример взаимодействия**: **Вы**: "Покажите ограничения для таблицы заказов." **ИИ**: "Таблица заказов имеет следующие ограничения: - Первичный ключ: order_id - Внешний ключ: customer_id ссылается на клиенты(id) - Внешний ключ: product_id ссылается на продукты(id) - Ограничение проверки: order_amount > 0" ### dbutils-explain-query Предоставляет план выполнения для SQL-запроса, показывая, как движок базы данных будет обрабатывать запрос, включая методы доступа, типы соединений и предполагаемые затраты. Этот инструмент необходим для понимания и оптимизации производительности сложных запросов. **Пример взаимодействия**: **Вы**: "Объясните план выполнения для этого запроса: SELECT * FROM orders WHERE customer_id = 123" **ИИ**: "План выполнения для этого запроса: 1. Сканирование индекса: использование индекса customer_id_idx 2. Оценочная стоимость: 12.5 3. Оценочное количество строк: 8 4. Условие фильтрации: customer_id = 123" ### dbutils-get-performance Получает метрики производительности для подключения к базе данных, включая количество запросов, среднее время выполнения, использование памяти и статистику ошибок. Эта информация ценна для мониторинга состояния базы данных и выявления потенциальных узких мест. **Пример взаимодействия**: **Вы**: "Получите метрики производительности для базы данных." **ИИ**: "Текущие метрики производительности базы данных: - Время выполнения запроса: в среднем 45 мс - Коэффициент попаданий в кэш: 87% - Активные соединения: 3 - Недавний коэффициент ошибок: 0.2%" ### dbutils-analyze-query Анализирует характеристики производительности SQL-запроса, предоставляя план выполнения, фактическое время выполнения и конкретные рекомендации по оптимизации. Этот инструмент выходит за рамки простого объяснения, идентифицируя потенциальные проблемы и предлагая конкретные улучшения для ускорения выполнения запросов. **Пример взаимодействия**: **Вы**: "Проанализируйте этот запрос: SELECT * FROM orders JOIN customers ON orders.customer_id = customers.id WHERE order_date > '2023-01-01'" **ИИ**: "Результаты анализа запроса: 1. Проблема производительности: Использование SELECT * извлекает ненужные столбцы 2. Отсутствующий индекс: Нет индекса на столбце order_date 3. Предложения по оптимизации: - Выбирайте только необходимые столбцы - Добавьте индекс на столбец order_date - Рассмотрите возможность добавления предложения LIMIT для ограничения количества результатов" ## Распространенные сценарии использования ### 1. Исследование данных **Вы**: "Я хочу понять структуру моей базы данных." **ИИ**: "Я могу помочь вам исследовать структуру вашей базы данных. Позвольте мне перечислить все таблицы, а затем вы можете выбрать одну, чтобы узнать больше о ее структуре." **Вы**: "Хорошо, перечислите все таблицы." **ИИ**: "Ваша база данных содержит следующие таблицы: - клиенты - продукты - заказы - инвентарь - сотрудники О какой таблице вы хотели бы узнать больше?" **Вы**: "Расскажите мне о структуре таблицы клиентов." **ИИ**: "Таблица клиентов имеет следующую структуру: - id (целое число, первичный ключ) - имя (varchar(100), не null) - email (varchar(100), уникальный, не null) - дата_регистрации (дата, не null) - последний_вход (timestamp) - статус (enum: 'активный', 'неактивный', 'приостановлен')" ### 2. Анализ данных **Вы**: "Проанализируйте тенденции продаж за последние 6 месяцев." **ИИ**: "Я проанализирую тенденции продаж за последние 6 месяцев. Позвольте мне выполнить несколько запросов..." [ИИ выполняет несколько запросов, анализируя данные о продажах] **ИИ**: "На основе анализа последних 6 месяцев: 1. Общие продажи: $1,245,678, рост на 15% по сравнению с предыдущими 6 месяцами 2. Самый продаваемый продукт: Продукт X, составляющий 23% от общих продаж 3. Пиковые периоды продаж: пятницы и субботы, составляющие 45% от общих продаж 4. Коэффициент удержания клиентов: 78%, рост на 5% по сравнению с предыдущими 6 месяцами" ### 3. Анализ между базами данных **Вы**: "Сравните структуру таблицы пользователей между производственной и тестовой базами данных." **ИИ**: "Я сравню структуру таблицы пользователей между двумя базами данных..." [ИИ запрашивает обе базы данных для структур таблиц] **ИИ**: "Различия в структуре таблицы пользователей между производственной и тестовой базами данных: 1. Производственная имеет дополнительный столбец 'last_login_ip' (varchar(45)) 2. Столбец 'email' в тестовой базе данных не имеет уникального ограничения 3. Производственная имеет дополнительный индекс: idx_user_status 4. Тестовая база данных не имеет ограничения внешнего ключа: fk_user_role" ## Лучшие практики ### Оптимизация запросов 1. **Ограничение размера результирующего набора**: Используйте предложения LIMIT для ограничения количества возвращаемых строк 2. **Выбор только необходимых столбцов**: Избегайте использования SELECT * 3. **Использование индексированных столбцов**: Используйте столбцы с индексами в предложениях WHERE 4. **Избегание сложных вычислений**: Перенесите сложные вычисления на уровень приложения ### Рекомендации по безопасности 1. **Использование учетных записей только для чтения**: Создавайте выделенные учетные записи базы данных только для чтения для доступа ИИ 2. **Ограничение доступа к таблицам**: Предоставляйте доступ только к необходимым таблицам 3. **Использование SSL/TLS**: Включите шифрование для удаленных подключений к базе данных 4. **Регулярная смена паролей**: Периодически меняйте пароли базы данных ### Оптимизация производительности 1. **Настройка пула соединений**: Настройте размер пула соединений в зависимости от вашего использования 2. **Настройки тайм-аута запроса**: Установите разумные длительности тайм-аута для запросов 3. **Кэширование результатов**: Рассмотрите возможность кэширования для часто запрашиваемых данных 4. **Мониторинг производительности**: Регулярно проверяйте метрики производительности для выявления потенциальных проблем ## Устранение неполадок Если вы столкнулись с проблемами во время использования, обратитесь к разделу устранения неполадок в [Руководстве по установке](installation.md) или обратитесь к [Технической документации](technical/architecture.md) для получения более подробной информации.