# Sources of external dictionaries
An external dictionary can be connected from many different sources.
The configuration looks like this:
```xml
...
...
...
```
The source is configured in the `source` section.
Types of sources (`source_type`):
- [Local file](#dicts-external_dicts_dict_sources-local_file)
- [Executable file](#dicts-external_dicts_dict_sources-executable)
- [HTTP(s)](#dicts-external_dicts_dict_sources-http)
- [ODBC](#dicts-external_dicts_dict_sources-odbc)
- DBMS
- [MySQL](#dicts-external_dicts_dict_sources-mysql)
- [ClickHouse](#dicts-external_dicts_dict_sources-clickhouse)
- [MongoDB](#dicts-external_dicts_dict_sources-mongodb)
## Local file
Example of settings:
```xml
/opt/dictionaries/os.tsvTabSeparated
```
Setting fields:
- `path` – The absolute path to the file.
- `format` – The file format. All the formats described in "[Formats](../formats/index.md#formats)" are supported.
## Executable file
Working with executable files depends on [how the dictionary is stored in memory](external_dicts_dict_layout.md#dicts-external_dicts_dict_layout). If the dictionary is stored using `cache` and `complex_key_cache`, ClickHouse requests the necessary keys by sending a request to the executable file's `STDIN`.
Example of settings:
```xml
cat /opt/dictionaries/os.tsvTabSeparated
```
Setting fields:
- `command` – The absolute path to the executable file, or the file name (if the program directory is written to `PATH`).
- `format` – The file format. All the formats described in "[Formats](../formats/index.md#formats)" are supported.
## HTTP(s)
Working with executable files depends on [how the dictionary is stored in memory](external_dicts_dict_layout.md#dicts-external_dicts_dict_layout). If the dictionary is stored using `cache` and `complex_key_cache`, ClickHouse requests the necessary keys by sending a request via the `POST` method.
Example of settings:
```xml
http://[::1]/os.tsvTabSeparated
```
In order for ClickHouse to access an HTTPS resource, you must [configure openSSL](../operations/server_settings/settings.md#server_settings-openSSL) in the server configuration.
Setting fields:
- `url` – The source URL.
- `format` – The file format. All the formats described in "[Formats](../formats/index.md#formats)" are supported.
## ODBC
You can use this method to connect any database that has an ODBC driver.
Example of settings:
```xml
DatabaseName
TableName
DSN=some_parametersSQL_QUERY
```
Setting fields:
- `db` – Name of the database. Omit it if the database name is set in the `` parameters.
- `table` – Name of the table.
- `connection_string` – Connection string.
- `invalidate_query` – Query for checking the dictionary status. Optional parameter. Read more in the section [Updating dictionaries](external_dicts_dict_lifetime.md#dicts-external_dicts_dict_lifetime).
## Example of connecting PostgreSQL
Ubuntu OS.
Installing unixODBC and the ODBC driver for PostgreSQL:
sudo apt-get install -y unixodbc odbcinst odbc-postgresql
Configuring `/etc/odbc.ini` (or `~/.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 =
```
The dictionary configuration in ClickHouse:
```xml
table_nameDSN=myconnection
postgresql_table
300360idsome_columnUInt640
```
You may need to edit `odbc.ini` to specify the full path to the library with the driver `DRIVER=/usr/local/lib/psqlodbcw.so`.
### Example of connecting MS SQL Server
Ubuntu OS.
Installing the driver: :
```
sudo apt-get install tdsodbc freetds-bin sqsh
```
Configuring the driver: :
```
$ 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
```
Configuring the dictionary in ClickHouse:
```xml
test
dict
DSN=MSSQL;UID=test;PWD=test300360ksString
```
## DBMS
### MySQL
Example of settings:
```xml
3306clickhouseqwertyexample01-11example01-21db_name
table_name
id=10SQL_QUERY
```
Setting fields:
- `port` – The port on the MySQL server. You can specify it for all replicas, or for each one individually (inside ``).
- `user` – Name of the MySQL user. You can specify it for all replicas, or for each one individually (inside ``).
- `password` – Password of the MySQL user. You can specify it for all replicas, or for each one individually (inside ``).
- `replica` – Section of replica configurations. There can be multiple sections.
- `replica/host` – The MySQL host.
\* `replica/priority` – The replica priority. When attempting to connect, ClickHouse traverses the replicas in order of priority. The lower the number, the higher the priority.
- `db` – Name of the database.
- `table` – Name of the table.
- `where ` – The selection criteria. Optional parameter.
- `invalidate_query` – Query for checking the dictionary status. Optional parameter. Read more in the section [Updating dictionaries](external_dicts_dict_lifetime.md#dicts-external_dicts_dict_lifetime).
MySQL can be connected on a local host via sockets. To do this, set `host` and `socket`.
Example of settings:
```xml
localhost/path/to/socket/file.sockclickhouseqwertydb_name
table_name
id=10SQL_QUERY
```
### ClickHouse
Example of settings:
```xml
example01-01-19000defaultdefault
ids
id=10
```
Setting fields:
- `host` – The ClickHouse host. If it is a local host, the query is processed without any network activity. To improve fault tolerance, you can create a [Distributed](../table_engines/distributed.md#table_engines-distributed) table and enter it in subsequent configurations.
- `port` – The port on the ClickHouse server.
- `user` – Name of the ClickHouse user.
- `password` – Password of the ClickHouse user.
- `db` – Name of the database.
- `table` – Name of the table.
- `where ` – The selection criteria. May be omitted.
### MongoDB
Example of settings:
```xml
localhost27017testdictionary_source
```
Setting fields:
- `host` – The MongoDB host.
- `port` – The port on the MongoDB server.
- `user` – Name of the MongoDB user.
- `password` – Password of the MongoDB user.
- `db` – Name of the database.
- `collection` – Name of the collection.