> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> MySQL 테이블 엔진 문서

# MySQL 테이블 엔진

MySQL 엔진을 사용하면 원격 MySQL 서버에 저장된 데이터에 대해 `SELECT` 및 `INSERT` 쿼리를 실행할 수 있습니다.

<div id="creating-a-table">
  ## 테이블 생성하기
</div>

```sql theme={null}
CREATE TABLE [IF NOT EXISTS] [db.]table_name [ON CLUSTER cluster]
(
    name1 [type1] [DEFAULT|MATERIALIZED|ALIAS expr1] [TTL expr1],
    name2 [type2] [DEFAULT|MATERIALIZED|ALIAS expr2] [TTL expr2],
    ...
) ENGINE = MySQL({host:port, database, table, user, password[, replace_query, on_duplicate_clause] | named_collection[, option=value [,..]]})
SETTINGS
    [ connection_pool_size=16, ]
    [ connection_max_tries=3, ]
    [ connection_wait_timeout=5, ]
    [ connection_auto_close=true, ]
    [ connect_timeout=10, ]
    [ read_write_timeout=300 ]
;
```

[CREATE TABLE](/ko/reference/statements/create/table) 쿼리에 대한 자세한 설명은 해당 문서를 참조하십시오.

테이블 구조는 원본 MySQL 테이블 구조와 다를 수 있습니다.

* 컬럼 이름은 원본 MySQL 테이블과 같아야 하지만, 그중 일부만 어떤 순서로든 사용할 수 있습니다.
* 컬럼 타입은 원본 MySQL 테이블의 타입과 달라도 됩니다. ClickHouse는 값을 ClickHouse 데이터 타입으로 [형 변환](/ko/reference/engines/database-engines/mysql#data_types-support)하려고 시도합니다.
* [external\_table\_functions\_use\_nulls](/ko/reference/settings/session-settings#external_table_functions_use_nulls) 설정은 널 허용 컬럼을 처리하는 방식을 정의합니다. 기본값은 1입니다. 값이 0이면 테이블 함수는 널 허용 컬럼을 만들지 않고 null 대신 기본값을 삽입합니다. 이는 배열 내부의 NULL 값에도 적용됩니다.

**엔진 매개변수**

* `host:port` — MySQL 서버 주소입니다.
* `database` — 원격 데이터베이스 이름입니다.
* `table` — 원격 테이블 이름입니다.
* `user` — MySQL 사용자입니다.
* `password` — 사용자 비밀번호입니다.
* `replace_query` — `INSERT INTO` 쿼리를 `REPLACE INTO`로 변환하는 플래그입니다. `replace_query=1`이면 해당 쿼리로 대체됩니다.
* `on_duplicate_clause` — `INSERT` 쿼리에 추가되는 `ON DUPLICATE KEY on_duplicate_clause` 표현식입니다.
  예시: `INSERT INTO t (c1,c2) VALUES ('a', 2) ON DUPLICATE KEY UPDATE c2 = c2 + 1`에서 `on_duplicate_clause`는 `UPDATE c2 = c2 + 1`입니다. `ON DUPLICATE KEY` 절과 함께 사용할 수 있는 `on_duplicate_clause`는 [MySQL 문서](https://dev.mysql.com/doc/refman/8.0/en/insert-on-duplicate.html)를 참조하십시오.
  `on_duplicate_clause`를 지정하려면 `replace_query` 매개변수에 `0`을 전달해야 합니다. `replace_query = 1`과 `on_duplicate_clause`를 동시에 전달하면 ClickHouse에서 예외가 발생합니다.

인수는 [이름이 지정된 컬렉션](/ko/concepts/features/configuration/server-config/named-collections)을 사용해 전달할 수도 있습니다. 이 경우 `host`와 `port`는 별도로 지정해야 합니다. 이 방식은 프로덕션 환경에 권장됩니다.

`=, !=, >, >=, <, <=`와 같은 단순한 `WHERE` 절은 MySQL 서버에서 실행됩니다.

나머지 조건과 `LIMIT` 샘플링 제약은 MySQL 쿼리가 완료된 후에만 ClickHouse에서 실행됩니다.

여러 레플리카를 지원하며, `|`로 나열해야 합니다. 예를 들면 다음과 같습니다.

```sql theme={null}
CREATE TABLE test_replicas (id UInt32, name String, age UInt32, money UInt32) ENGINE = MySQL(`mysql{2|3|4}:3306`, 'clickhouse', 'test_replicas', 'root', 'clickhouse');
```

<div id="usage-example">
  ## 사용 예시
</div>

MySQL에서 테이블 생성:

```text theme={null}
mysql> CREATE TABLE `test`.`test` (
    ->   `int_id` INT NOT NULL AUTO_INCREMENT,
    ->   `int_nullable` INT NULL DEFAULT NULL,
    ->   `float` FLOAT NOT NULL,
    ->   `float_nullable` FLOAT NULL DEFAULT NULL,
    ->   PRIMARY KEY (`int_id`));
Query OK, 0 rows affected (0,09 sec)

mysql> insert into test (`int_id`, `float`) VALUES (1,2);
Query OK, 1 row affected (0,00 sec)

mysql> select * from test;
+------+----------+-----+----------+
| int_id | int_nullable | float | float_nullable |
+------+----------+-----+----------+
|      1 |         NULL |     2 |           NULL |
+------+----------+-----+----------+
1 row in set (0,00 sec)
```

일반 인수를 사용해 ClickHouse에서 테이블을 생성합니다:

```sql theme={null}
CREATE TABLE mysql_table
(
    `float_nullable` Nullable(Float32),
    `int_id` Int32
)
ENGINE = MySQL('localhost:3306', 'test', 'test', 'bayonet', '123')
```

또는 [이름이 지정된 컬렉션](/ko/concepts/features/configuration/server-config/named-collections):

```sql theme={null}
CREATE NAMED COLLECTION creds AS
        host = 'localhost',
        port = 3306,
        database = 'test',
        user = 'bayonet',
        password = '123';
CREATE TABLE mysql_table
(
    `float_nullable` Nullable(Float32),
    `int_id` Int32
)
ENGINE = MySQL(creds, table='test')
```

MySQL 테이블에서 데이터 가져오기:

```sql theme={null}
SELECT * FROM mysql_table
```

```text theme={null}
┌─float_nullable─┬─int_id─┐
│           ᴺᵁᴸᴸ │      1 │
└────────────────┴────────┘
```

<div id="mysql-settings">
  ## 설정
</div>

기본 설정은 연결조차 재사용하지 않아 효율이 그다지 높지 않습니다. 이러한 설정을 사용하면 서버가 초당 처리할 수 있는 쿼리 수를 늘릴 수 있습니다.

<div id="connection-auto-close">
  ### `connection_auto_close`
</div>

쿼리 실행 후 연결을 자동으로 닫아, 연결 재사용을 비활성화할 수 있습니다.

가능한 값:

* 1 — 연결 자동 닫기가 허용되며, 연결 재사용이 비활성화됩니다
* 0 — 연결 자동 닫기가 허용되지 않으며, 연결 재사용이 활성화됩니다

기본값: `1`.

<div id="connection-max-tries">
  ### `connection_max_tries`
</div>

페일오버를 지원하는 풀의 재시도 횟수를 설정합니다.

가능한 값:

* 양의 정수
* 0 — 페일오버를 지원하는 풀에 대해 재시도하지 않습니다.

기본값: `3`.

<div id="connection-pool-size">
  ### `connection_pool_size`
</div>

연결 풀의 크기입니다(모든 연결이 사용 중인 경우, 일부 연결이 해제될 때까지 쿼리는 대기합니다).

가능한 값:

* 양의 정수.

기본값: `16`.

<div id="connection-wait-timeout">
  ### `connection_wait_timeout`
</div>

사용 가능한 연결이 생길 때까지 대기하는 시간 제한(초)입니다(이미 `connection_pool_size`개의 연결이 활성 상태인 경우). 0이면 대기하지 않습니다.

Possible values:

* 양의 정수.

기본값: `5`.

<div id="connect-timeout">
  ### `connect_timeout`
</div>

연결 시간 제한(초)입니다.

가능한 값:

* 양의 정수.

기본값: `10`.

<div id="read-write-timeout">
  ### `read_write_timeout`
</div>

읽기-쓰기 타임아웃(초)입니다.

가능한 값:

* 양의 정수.

기본값: `300`.

<div id="see-also">
  ## 관련 항목
</div>

* [MySQL 테이블 함수](/ko/reference/functions/table-functions/mysql)
* [MySQL을 딕셔너리 소스로 사용하는 방법](/ko/reference/statements/create/dictionary/sources/mysql)