# Руководство по использованию

*[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) для получения более подробной информации.
