---
name: Database Tool
description: Быстрый просмотр структуры БД — таблицы, колонки, превью строк, схемы. Без генерации SQL.
kind: tool
tool_key: database_tool
triggers: таблицы, покажи таблицы, структура бд, колонки, схема, превью, первые строки, список таблиц, describe, list tables, show tables, какие таблицы, перечисли таблицы
---

# Database Tool — быстрый просмотр структуры БД

Лёгкий инструмент для структурных операций с базой данных.
**Не генерирует SQL** — вызывает каталог БД напрямую, поэтому работает быстро.

## Когда использовать

- Пользователь спрашивает "какие таблицы есть в БД?"
- Нужно посмотреть колонки таблицы перед аналитическим запросом
- Нужен превью первых N строк таблицы
- Нужен список схем в базе данных

## Когда НЕ использовать

- Для сложных аналитических запросов с JOIN, GROUP BY, подзапросами — используй `sql_tool`
- Для агрегации, фильтрации, вычислений — используй `sql_tool`
- Для работы с CSV-данными — используй `pandas_tool`

## Обязательный порядок действий

⚠️ **НИКОГДА не вызывай `preview` или `describe_table` с угаданным именем таблицы.**
Всегда придерживайся следующего порядка:

1. Если схема БД неизвестна → сначала `list_schemas`, затем `list_tables`
2. Если схема известна → сразу `list_tables`
3. Только после получения реального списка таблиц → `preview` или `describe_table`

```
# Правильно: разведка → действие
database_tool(action="list_tables")          # узнать реальные имена
database_tool(action="preview", table="<реальное_имя>", limit=5)

# Неправильно: угадывать имена таблиц
database_tool(action="preview", table="table1")   # ❌ выдуманное имя
```

Если `list_tables` вернул пустой список — вызови `list_schemas` и повтори
`list_tables` с найденной схемой перед тем, как делать выводы об отсутствии таблиц.

## Параметры

| Параметр | Тип | Описание |
|----------|-----|----------|
| `action` | `"list_tables"` \| `"describe_table"` \| `"preview"` \| `"list_schemas"` | Действие |
| `table` | `str` (опционально) | Имя таблицы (для `describe_table` и `preview`). **Только реальные имена из `list_tables`!** |
| `db_schema` | `str` (опционально) | Схема БД. Не угадывай — используй результат `list_schemas` |
| `limit` | `int` (опционально) | Количество строк для preview (по умолчанию 10, макс. 50) |

## Примеры вызовов

### Показать первые строки всех таблиц (правильный порядок)
```
# Шаг 1: получить список таблиц
database_tool(action="list_tables")
# Шаг 2: для каждой таблицы из результата
database_tool(action="preview", table="<имя_из_list_tables>", limit=5)
```

### Список таблиц
```
database_tool(action="list_tables")
```

### Список таблиц, если схема неизвестна
```
# Шаг 1: узнать схемы
database_tool(action="list_schemas")
# Шаг 2: список таблиц в нужной схеме
database_tool(action="list_tables", db_schema="<схема_из_list_schemas>")
```

### Описание колонок таблицы
```
database_tool(action="describe_table", table="orders")
```

### Превью первых строк
```
database_tool(action="preview", table="users", limit=5)
```

### Список схем
```
database_tool(action="list_schemas")
```

## Примеры запросов пользователя

- "Покажи таблицы в БД"
- "Какие колонки в таблице users?"
- "Покажи первые 10 строк таблицы orders"
- "Какие схемы есть в базе?"
- "Что за таблица titanic?"
- "Перечисли таблицы"

## Результат

Результат инжектится в sandbox как переменная (например `db_tables`, `columns_orders`, `preview_users`)
и доступен для последующих инструментов (`plotly_tool`, `pandas_tool`).